diff options
authorWim Leers2016-01-14 15:26:25 (GMT)
committerWim Leers2016-01-14 15:27:12 (GMT)
commit86dfe25567e7187b79721ee0ac5c2611bad7a979 (patch)
parent547c687aac9f104a69a2e92732b45f11218e8764 (diff)
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:
+ // 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
+ //
+ // 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;