Help Center

Menu

Use Edge Side include (ESI) tags with Squiz Edge

This tutorial shows you how to use Matrix to take advantage of the Edge Side Includes (ESI) capabilities in Squiz Edge to display cached conditional content within your site.

The sections in this how-to article use ESI technology to print different "aside" content in the design based on what section of the site from which the user views the page.

About Squiz Edge

Squiz Edge is a globally distributed content delivery and caching network created by Squiz. It was born out of industry-wide issues where website owners need to:

  • Deliver a fast web experience to end-users, no matter their location

  • Provide dynamic and personalized content to globally distributed users.

Before you start

Meet the following prerequisites before continuing with this tutorial:

Set up the design

Begin setting up the design by nesting a standard page to sit under the left-column menu for our aside content to live.

  1. Start by creating a new Standard page asset named "Aside Content" somewhere under the Nested Content folder.

  2. Make the page Live and set the component to Code.

  3. Add some placeholder content:

    <p>Aside content will go here...</p>

  4. Edit the Parse File of the main Design and find the closing </div><!--.sub-nav-wrapper-- > tag.

  5. Just after this div, add a new Nested Content Design Area asset named "aside_content" to nest your page within.

    <mysource_area id_name="aside_content" design_area="nest_content"/>

  6. After saving the Parse File, go to the Customisation screen, customize the aside_content Design Area, and choose the Aside Content page as the asset to nest within.

Preview one of the pages in the site, and notice the sample Aside content will go here…​ text located just after the left-col menu:

Create the content

The next step is to create some content to include in the aside area.

The content displays based on the location of the page on the site.

You also change the names of the first level pages in the template site to be a little more interesting.

  1. Change the name and URL for each of the three top-level pages of the site to the following:

    • Services - /services

    • About - /about

    • News - /news

    The URL here is important: it is the value you check against to figure out the section of the site viewed by the user.

Next, create the actual HTML page to which you link to your ESI tag.

  1. Within the "ESI" folder, create a Standard page asset named "Promo Content (ESI)".

    Wherever you create this page, make sure it has a browseable URL that you can use to view the page on the frontend.

  2. Make the page Live and set the component to Code.

This content area holds all the possible content that can appear as "promo content" within the page. You use the choose | when | otherwise technique to display the content conditionally.

  1. Add some HTML content for the "Services" area. This content displays when the URL of the frontend page resides within the /services section of the site.

    <!--@@  /services content  @@-->
<esi:choose>
    <esi:when test="$(ESI_ARGS{section}) == 'services'">

        <div class="panel panel-default">
            <div class="panel-heading">
                <h3 class="panel-title">Contact us for a quote</h3>
            </div>
            <div class="panel-body">
                <p><a href="#">Click here to get a free quote!</a></p>
            </div>
        </div>

   </esi:when>
</esi:choose>

    The test checks whether the $(ESI_ARGS{section})ESI variable is equal to "services" and, if so, prints some additional HTML into the content area.

  2. Save the content and preview the Promo Content (ESI) page.

    You should not see any content because the text evaluates to false. To see the conditional content, pass an ESI based query string to the URL of the page, like this: https://example.com/esi/promo-content-esi?SQ_ASSET_CONTENTS_RAW&esi_section=services.

Passing the ?SQ_ASSET_CONTENTS_RAW query parameter lets you view the page without any designs or paint layouts applied. Previewing the page with that URL query string should display a page that looks something like this:
esi with squiz edge esi content preview

You now have your content ready to be Edge Side Included into your design.

Include the content into the design

Update the Aside Content page that is currently printing the placeholder content of "Aside content will go here…​" and replace it with the ESI content.

  1. Go to the contents screen of the Aside Content page and replace the content with the following ESI tag:

    <!-- ESI Start - Promo Content -->
<esi:include src="./?a=1234?SQ_ASSET_CONTENTS_RAW&esi_section=services"/> (1)
<!-- ESI End - Promo Content -->
    1 Replace the ./?a=1234 part with the correct asset ID of your Promo Content (ESI) page asset.

  2. If you preview any page in the site now, you should see the promo content included in the left column:

    esi with squiz edge esi content preview frontend

The promo content is being included on all pages because it is hard-coded within the esi_section=services part of the ESI URL. The final task involves making the content dynamic by including the Services promo content on pages located in the /services section of the site.

  1. Make the esi_section variable in the first level page’s URL dynamic using the %frontend_asset_linking_lineage^index:1^as_asset:asset_web_path% keyword.

    If the %asset_linking_lineage% keyword is not available in your version of Matrix, there are other keyword combinations you can use to get this value. For example, %frontend_asset_url_path^explode:/^index:1%.

  2. Update the ESI tag using this keyword as the esi_section query parameter value.

    <!-- ESI Start - Promo Content -->
<esi:include src="./?a=1234?SQ_ASSET_CONTENTS_RAW&esi_section=%frontend_asset_linking_lineage^index:1^as_asset:asset_web_path%"/>
<!-- ESI End - Promo Content -->

  3. Preview pages of your site both within and outside of the /services area.

Notice the Services promo content appearing for pages that live under the /services URL path and nowhere else.

Add more conditional content

You have added some content for the Services section of the site. However, you can add other content for the other areas using the same technique.

For example, you can add more <esi:choose> tags into the Promo Content (ESI) page content, one for each section:

<!--@@  /services content  @@-->
<esi:choose>
    <esi:when test="$(ESI_ARGS{section}) == 'services'">
       Services promo content here...
   </esi:when>
</esi:choose>

<!--@@  /about content  @@-->
<esi:choose>
    <esi:when test="$(ESI_ARGS{section}) == 'about'">
       About promo content here...
   </esi:when>
</esi:choose>

<!--@@  /news content  @@-->
<esi:choose>
    <esi:when test="$(ESI_ARGS{section}) == 'news'">
       News promo content here...
   </esi:when>
</esi:choose>

You might also want to have content that should appear for multiple sections, in which case, you can use the OR operator within the test= attribute:

<!--@@  /about and /news content  @@-->
<esi:choose>
    <esi:when test="($(ESI_ARGS{section}) == 'about') | ($(ESI_ARGS{section}) == 'news')">
       About and News promo content here...
   </esi:when>
</esi:choose>

Summary

You now have configured Matrix to include conditional content in your design using the power of ESI tags.

You can keep using this implementation example to explore further the possibilities of ESI tags using other test conditions such as the $(HTTP_COOKIE{ cookie }) and $(HTTP_ACCEPT_LANGUAGE{ language }) variables.