Introduction

Your Front-end Templates must be audited to ensure that page content variations (that should not be cached) are abstracted and included using the ESI include method.

Generally speaking this process involves ensuring anything that should not be cached is not cached by the Aurora View Cache (Varnish), which might otherwise prevent customers from using the site properly, e.g. being unable to add products to their basket due to the basket page being cached.

This being so, you or your Agency should make note of all the considerations described in this Support Article and make an effort to ensure that not only the templates explicitly described in this Support Article are prepared for Varnish, but the Front-end Templates as a whole are updated to handle this.

👍

You should update your Front-end Templates and publish the completed changes to your Live store in advance of enabling Varnish or the Aurora View Cache. All methods used will work perfectly without the caching being active and will mean that when it is activated, there will be no disruption as templates are then changed to accommodate the new caching behaviour.

What will Varnish cache and when?

The following pages are cached by the Aurora View Cache when using Varnish:

• Home page.
• All category pages.
• Standard content pages (with the exception of blog pages).
• Static assets (CSS/JS/Images)

This being so, the following pages (among others) are not cached by Varnish:

• Basket page.
• Checkout process (including the Order Complete page).
• Members area.
• All of the Aurora Back-end.
• Data feeds (Google Base, etc.).

The following exceptions may cause a user to be served a non-cached page when it in fact should have been cached:

• Logging in.
• A logged in admin user.
  • The presence of the cookie "ac_no_stats" (usually created when logging in as an admin and remaining after logout)
• Customising a category/product listing page i.e. changing a list sort order.
• Comparing products.
• Changing the currency or language.
• Having a query string within the page URL, e.g. http://www.yoursite.com/?query=present

🚧

Assets that are also cached by your CDN (Content Delivery Network) may reflect an incorrect X-Cache value. This reflects the Aurora View Cache status of the asset when your CDN first requested the asset.

🚧

Although a page may be reported as being cached, there are likely to be areas within the page that are still dynamically generate based on user specific content included using ESI templates.

How do I know if a page is cached?

The X-Cache HTTP header reflects whether or not the cache has been used to serve the requested page:

• A value of MISS means that the page was not cached.
• A value of HIT means that the page was served from the cache.

How can I find out how long a page has been cached for?

The Age HTTP header reflects how many seconds a page has existed within the cache. This value is reset to zero whenever the cache is cleared or if the cache is not being used at all (i.e. the X-Cache HTTP header has a value of MISS).

How do I prevent Varnish caching things?

You can prevent Varnish from caching a template using the ESI include method in your Front-end templates. Please see the following examples of two includes of the navigation template. The first will be cached by Aurora View Cache (Varnish) and the second will not.

{include file="_includes/navigation_header.tpl.html"}
 
{include_esi file="_includes/navigation_header.tpl.html"}

🚧

Templates that are included using the ESI include method will have their own caching profile and in some cases may be generated every time they are requested and not cached by the Aurora View Cache (Varnish).

📘

Using "include_esi" is backwards compatible with non-Varnish enabled sites and will include the content as a standard "include" in this case.

What templates are ESI whitelisted?

All of the following templates are supported by the ESI include method as standard:

• _includes/navigation_header.tpl.html

• _includes/navigation_user.tpl.html ( requires use of handler="user" )

• _includes/country_selector_prompt.tpl.html  ( requires use of handler="user" )

• basket/minibasket-container.tpl.html

• basket/dropdownbasket.tpl.html

• _includes/nonaffiliate_phonenumber1.tpl.html

• _includes/nonaffiliate_phonenumber2.tpl.html

• products/latest-arrivals.tpl.html

• _includes/recently_viewed.tpl.html

• blog/articles.tpl.html

• blog/articles_1.tpl.html

• blog/articles_2.tpl.html

• blog/articles_3.tpl.html

• _includes/integrations.tpl.html

👍

If you need a new template added to the whitelist, please contact your Agency for assistance. It may be advisable to simply use a template already included in the whitelist above in order to avoid development or delays in the deployment of your new templates.

How can I clear the view cache?

The view cache is cleared automatically by Aurora under the following circumstances:

• Product changes
• Product stock changes
• Content changes (with the exception of updates to language variations)
• Snippet changes
• Store settings changes

The view cache can be cleared manually from the Aurora Back-end under Tools > Cache.**

This will take effect immediately and will result in all cached content being re-cached; this should have minimal impact on server performance, but should be avoided during periods of high traffic as it will reduce server performance for a short period of time while the cache warms up again (content is added back into the cache).

How to prepare your Store for Varnish

Things you should check for in your templates

Anything that checks the user's Session, e.g. $smarty.session.xxx, should be evaluated for the possibility that this may change between cache storages and so be moved into an ESI include.

🚧

Some session data is safe to use where its changing will trigger a cache clearance, such as the Currency data, as described in the What will Varnish cache and when? section.

Any content that could be affected by the user viewing it should be considered for inclusion in an ESI template.

Front-end Templates you should not cache

❗️

The ESI includes are HTML snippets requested via a URL with the template name listed as a GET parameter and so there is a whitelist of allowable templates, which is currently manually controlled by Aurora Commerce.

You will need to speak to your Agency if you require whitelisted templates that are not already supported.

As a rule of thumb, you should not cache anything that might change on a per-request or per-visitor basis.

👍

Here is a list of includes (and their typical location in the Front-end Templates) that Aurora Commerce suggest should not be cached by the Aurora View Cache (and so only be included using the ESI include method):

• • Inside the header template, typically found in _includes/header.tpl.html:
    • {include_esi file="basket/dropdownbasket.tpl.html"}
      Reason: Dependant on user's basket
    • {include_esi file="basket/minibasket-container.tpl.html" }
      Reason: Dependant on user's basket
    • {include_esi file="_includes/nonaffiliate_phonenumber1.tpl.html" }
      Reason: Dependant on $affiliate_visitor ( derived from a user cookie )
    • {include_esi file="_includes/nonaffiliate_phonenumber2.tpl.html" }
      Reason: Dependant on $affiliate_visitor ( derived from a user cookie )
    • {include_esi file="_includes/navigation_header.tpl.html" }
      Reason: Dependant on user login status in "$smarty.session.user"
  • Inside the footer template, typically found in _includes/footer.tpl.html:
    • {include_esi file="_includes/recently_viewed.tpl.html" handler="user" }
      Reason: Dependant on products recently viewed by the user, so must use the handler="user" attribute.

🚧

It is acceptable to use the normal {include xxx} smarty method from within any templates included using the {include_esi xxx} method. Because the parent template being included is called by the ESI include method, any templates it then loads will also be included in the same way, i.e. if the parent template has been included by ESI, there is no need to also use the ESI include method for any child included within the parent template.

Please see another example below showing a more genuine working example of the use of the ESI include and some indication as to why each section might not be cached.

<html>
	<head>
		<title>Page Title</title>
	</head>
	<body>
		<div id="header">
			<div id="logo"><img src="http://my.cdn.com/HJDUHS/image.jpg" alt="" /></div>
			<div id="user_navigation">
				{include_esi file="_includes/navigation_user.tpl.html"}
			</div>
			<div id="mini_basket">
				{include_esi file="basket/minibasket-container.tpl.html"}
			</div>
		</div> 
		<div id="content">
			Page Content.
		</div>
		<div id="footer">
			<div id="recently_viewed">
				{include_esi file="_includes/recently_viewed.tpl.html" handler="user"}
			</div>
			<div id="affiliate_content">
				{include_esi file="_includes/affiliate_content.tpl.html"}
			</div>
		</div>
	</body>
<html>

In the above example, the main page HTML along with the logo and content are cached whereas the user navigation, mini basket, recently viewed and affiliate content are not cached:

• The user navigation HTML is not cached because this varies based on whether or not the user is logged in.
• The mini basket HTML is not cached because this varies based on what is in the users basket.
• The recently viewed HTML is not cached because this varies based on user activity:
  • This also uses the user handler to load data related to user activity; avoid using multiple references within a single page as this can affect site performance.
• The affiliate content HTML is not cached because this varies based on user cookie values.

Typically (but not always) ESI include references are limited to the header and footer templates, though they can be placed anywhere required in the Front-end Templates.

🚧

The ESI include method will include content whether or not the Aurora View Cache is enabled and so all template updates should be applied, tested and deployed before the Aurora View Cache is enabled on a Live store.

What does "Esi Template not found" mean?

If you see the message "Esi Template not found", then you have attempted to include a template that has not yet been whitelisted by Aurora.

🚧

The template whitelist is a security measure to prevent undesirable templates from being requested outside the cache, which could prevent performance gains from being achieved.

👍

If you need a new template added to the ESI whitelist, please contact your Agency for assistance. It may be advisable to simply use a template already included in the whitelist in order to avoid development or delays in the deployment of your new templates.