HST-2 Edge Side Includes Support

Overview

Bloomreach Content (HST) supports basic Edge Side Includes (ESI) for both external ESI processors—such as Content Delivery Networks (CDNs) like Akamai, or cache servers like Varnish and Squid—and for the built-in HST ESI Processor.

Edge Side Includes is a markup language designed to enable dynamic web content assembly at the edge of the network. ESI addresses web infrastructure scaling by allowing partial page assembly closer to the user. The ESI Language Specification 1.0 was submitted to the W3C in August 2001.

You can configure HST Components to output ESI markup instead of fully rendered HTML. In this configuration, an external ESI processor replaces the ESI markup with the corresponding HTML fragments before the response reaches the client.

If your infrastructure does not include an external ESI processor, the HST ESI Processor can process ESI markup within the HST container. This allows HST Components to serve ESI markup asynchronously, and the HST ESI Processor aggregates the fragments into the final response. When combined with HST Page Caching, this approach enables caching of entire pages while still rendering and aggregating specific dynamic components on each request.

Configuring HST Components to Render ESI Markup

An HST page consists of a tree of reusable HST Components, managed in the repository.

To enable ESI markup for a component:

  1. Set the hst:async property to true on the HST Component node. This marks the component and its descendants for asynchronous rendering.

    hst:async: true

    By default, this configuration causes the component to render asynchronously using client-side AJAX requests.

    For more information on asynchronous components, see Asynchronous HST Components and Containers.

  2. To use ESI processing instead of AJAX for asynchronous rendering, set the hst:asyncmode property to esi:

    hst:asyncmode: esi

    If hst:asyncmode is not set, the default value is ajax.

When hst:asyncmode is set to esi, the component renders ESI markup in the initial response. For example:

<esi:include src="http://example.org/news?_hn:type=component-rendering&amp;_hn:ref=r1_r2" onerror="continue"/>

The src attribute points to an HST Component Rendering URL, which renders only the specified component window (identified by its namespace, such as r1_r2).

The final page response includes HTML for all descendant components except those marked for ESI-based asynchronous rendering. Those components output ESI markup as shown above.

An external ESI processor (such as Akamai) processes the page, requests the ESI Include URLs, and replaces the ESI markup with the retrieved HTML fragments before delivering the final output to the client.

HST ESI Processor

HST can operate as an ESI processor, resolving Edge Side Includes markup within the container. HST ESI processing integrates with HST Page Caching, allowing cached pages to include dynamic fragments that are processed on each request.

To enable the HST ESI Processor, add the following properties to /WEB-INF/hst-config.properties:

# Enable ESI fragment processing before writing output to the client.
esi.default.fragments.processing = true

# Control whether ESI processing is limited to async components.
# Set to false to allow manual ESI includes in templates.
esi.processing.condition.async.components = false

Default ESI Include Elements for Asynchronous Components

For ESI-based asynchronous components, the HST container renders a simple ESI Include element for the component window:

<esi:include src="http://example.org/news?_hn:type=component-rendering&amp;_hn:ref=r1_r2" onerror="continue" />

When the HST ESI Processor is enabled, it processes this ESI Include markup and replaces it with the fully rendered HTML for the specified component window.

In most cases, you do not need to manually add ESI elements to your templates. Marking a component as asynchronous with hst:asyncmode: esi is sufficient.

If you need to add additional ESI elements manually (for example, to use ESI tags other than <esi:include>), you can do so as described below.

Supported ESI Tags

You can manually render ESI markup in component templates (JSP, Freemarker, etc.) without marking the component as asynchronous. The HST ESI Processor supports the following ESI elements:

  • ESI comment blocks: <!--esi ... -->
  • ESI include elements: <esi:include ... />
  • ESI comment elements: <esi:comment ... />
  • ESI remove elements: <esi:remove>...</esi:remove>
  • ESI variable elements: <esi:vars>...</esi:vars>

Example ESI markup in a template:

<!--esi
<h1>ESI Processing Enabled</h1>
-->

<esi:comment text="Related New Articles." />
<esi:include src="http://example.org/news?_hn:type=component-rendering&amp;_hn:ref=r1_r2" onerror="continue" />

<esi:comment text="Include the license info or show a link." />
<!--esi
<pre>
  <esi:include src="http://www.example.com/LICENSE"/>
</pre>
-->
<esi:remove>
  <a href='http://www.example.com/LICENSE'>The license</a>
</esi:remove>

<esi:vars>
  <img src="http://www.example.com/$(HTTP_COOKIE{type})/hello.gif"/>
  <ul>
    <li>Accept Language: en? $(HTTP_ACCEPT_LANGUAGE{en})</li>
    <li>Host: $(HTTP_HOST)</li>
    <li>Referer: $(HTTP_REFERER)</li>
    <li>User Agent: $(HTTP_USER_AGENT{browser}), $(HTTP_USER_AGENT{version}), $(HTTP_USER_AGENT{os})</li>
    <li>Query String: $(QUERY_STRING{first}) $(QUERY_STRING{last})</li>
  </ul>
</esi:vars>

Refer to the ESI Specification for details on each ESI element.

Supported URLs in ESI Include Tags

The HST ESI Processor supports only local HST URLs in <esi:include> tags. It does not support external or non-HST URLs.

Supported URL types:

  • HST Component Rendering URL, created with HstResponse#createComponentRenderingURL() or <hst:componentRenderingURL />
  • HST Resource URL, created with HstResponse#createResourceURL() or <hst:resourceURL />
  • HST Render URL, created with HstResponse#createRenderURL() or <hst:renderURL />

Example JSP template usage:

<esi:include src="<hst:componentRenderingURL/>" onerror="continue" />

This approach is equivalent to marking the component as an ESI-based asynchronous component, but you can add additional ESI elements as needed.

Limitations

The HST ESI Processor has the following limitations:

  • Only local HST URLs are supported in <esi:include> tags. External and non-HST URLs are not supported.
  • HST Navigation URLs (created with HstResponse#createNavigationalURL() or <hst:link />) are not supported as ESI include sources.
  • Only the value "continue" is supported for the onerror attribute of <esi:include>. Other values are not supported.
  • Surrogate-Capabilities header controls are not supported. See Surrogate-Capabilities header controls.
  • The following ESI tags are not supported: <esi:inline/>, <esi:choose>, <esi:when>, <esi:otherwise>, <esi:try>, and <esi:attempt>.
Share Feedback
Page: /build/web-application/hst-2-edge-side-includes-support
Section: Build
Category *