Document why FacetBlock should keep max-age=0, how using BigPipe is the solution, and how this will be difficult to optimize further.

1 files changed, 26 insertions, 2 deletions

diff --git a/src/Plugin/Block/FacetBlock.php b/src/Plugin/Block/FacetBlock.php
index 2103525..11df9d1 100644
--- a/src/Plugin/Block/FacetBlock.php
+++ b/src/Plugin/Block/FacetBlock.php
@@ -106,8 +106,32 @@ class FacetBlock extends BlockBase implements ContainerFactoryPluginInterface {
    * {@inheritdoc}
    */
   public function getCacheMaxAge() {
-    // Makes sure a facet block is never cached.
-    // @TODO Make blocks cacheable, see: https://www.drupal.org/node/2581629
+    // A facet block cannot be cached, because it must always match the current
+    // search results, and Search API gets those search results from a data
+    // source that can be external to Drupal. Therefore it is impossible to
+    // guarantee that the search results are in sync with the data managed by
+    // Drupal. Consequently, it is not possible to cache the search results at
+    // all. If the search results cannot be cached, then neither can the facets,
+    // because they must always match.
+    // Fortunately, facet blocks are rendered using a lazy builder (like all
+    // blocks in Drupal), which means their rendering can be deferred (unlike
+    // the search results, which are the main content of the page, and deferring
+    // their rendering would mean sending an empty page to the user). This means
+    // that facet blocks can be rendered and sent *after* the initial page was
+    // loaded, by installing the BigPipe (big_pipe) module.
+    //
+    // When BigPipe is enabled, the search results will appear first, and then
+    // each facet block will appear one-by-one, in DOM order.
+    // See https://www.drupal.org/project/big_pipe.
+    //
+    // In a future version of Facet API, this could be refined, but due to the
+    // reliance on external data sources, it will be very difficult if not
+    // impossible to improve this significantly.
+    //
+    // Note: when using Drupal core's Search module instead of the contributed
+    //       Search API module, the above limitations do not apply, but for now
+    //       it is not considered worth the effort to optimize this just for
+    //       Drupal core's Search.
     return 0;
   }