ESI Support

Edge Side Includes (ESI) is a widely-used standard for caching of web pages. The basic idea is that parts of a web page that do not get updated frequently can be identified using special ESI markup, and cached in servers close to clients.

CUE Front can support ESI if correctly configured, and the Tomorrow Online demo publication makes use of ESI for displaying page headers and footers. This section contains a brief description of the Tomorrow Online implementation.

Tomorrow Online's default-master.twig template contains the following lines:

{% if data.headerMenuESI %}
  <esi:include src="{{ data.headerMenuESI }}" onerror="continue"/>
{% elseif data.headerMenu %}
  {% include "organisms-header" with {"menu" : data.headerMenu} %}
{% endif %}

Here, the template sends an ESI tag instead of executing a header template if the data received from the Cook indicates that ESI is in use (that is, if it contains a headerMenuESI field. It replaces {{ data.headerMenuESI }} with the value of the field (.esi/header-menu).

The response passes through an ESI caching server on the way to the client. The ESI server replaces the esi:include tag with the actual header menu which it obtains either from its cache or by sending a request for the .esi/header-menu resource back to the Tomorrow Online server. After inserting the header menu, the caching server passes the completed page on to the client.

Any response received by the Cook for a URL starting with the characters .esi/ is handled specially, as described in Mapping URLs To GraphQL Queries. In the case of Tomorrow Online, this means that the response will be generated by the esi/header-menu.graphql query, which returns a header menu.

The mechanisms used to implement ESI here are very flexible, and can be modified to meet your needs. In particular, the rule that treats URLs starting with the characters .esi/ in a special way is defined in a simple recipe configuration, and can easily be modified as described in Configuring URL-GraphQL query mappings.

The Waiter incorporates a simple ESI parser for use during development, so that you do not need to include an ESI cache in your development environment. The parser is enabled by default. To disable it in a production system, replace

enableESIParser: true

with

enableESIParser: false

in your waiter-config.yaml file.

The Waiter's ESI parser only supports the esi:include element, and does not support the use of unbalanced templates. What that means is that the HTML content replaced by an esi:include element must contain a balanced set of HTML start and end tags - you can't have the start of an element in one template and the end in another. This kind of templating is actually allowed by the ESI standard, but it is generally regarded as bad practice and is not handled by the Waiter's parser.