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.