Template caching and cache-block
Three caches decide how often your templates really run. Knowing them explains why a change shows at once or not at all, and where to put work that is expensive.
| Cache | Holds | Renewed |
|---|---|---|
| Compiled templates | Each template turned into PHP code (site.ini [TemplateSettings] TemplateCompile=enabled, the default). | When the template file is newer than its compiled code. |
| Content view cache | The result of a node view: the HTML of the node template and the rest of $module_result (site.ini [ContentSettings] ViewCaching=enabled, for the view modes in CachedViewModes, by default full, sitemap and pdf). | When the node, or content it depends on, is published, moved or removed; stored per role set of the user, language, view parameters and more. |
| Cache blocks | The output of each {cache-block} of a template. | After their expiry time, and when any content is published, unless the block says otherwise. |
The pagelayout is not in the view cache: it runs on every request. So does a node template's work only when its view is not cached. That is why fetches in the pagelayout belong in cache blocks.
cache-block
Everything between {cache-block} and {/cache-block} is rendered once, stored, and printed from the store on later requests:
{cache-block keys=array( $module_result.uri ) expiry=3600}
{def $menu = fetch( 'content', 'list', hash( 'parent_node_id', 2,
'sort_by', array( 'priority', true() ) ) )}
<ul>
{foreach $menu as $item}
<li><a href={$item.url_alias|ezurl}>{$item.name|wash}</a></li>
{/foreach}
</ul>
{undef $menu}
{/cache-block}| Parameter | Does |
|---|---|
| keys | A value or an array of values. Each combination is a cache entry of its own. Without keys, there is one entry per place in the template and siteaccess. |
| expiry | Seconds until the entry expires. 7200 (two hours) when left out; 0 for no time limit. |
| ignore_content_expiry | The entry is not expired when content is published; only its expiry time ends it. |
| subtree_expiry | The entry is expired only when content below the given node is published (a node id, a system address or a URL alias), not when other content is. |
The key of an entry always includes the template, the place of the block in it and the siteaccess. Everything else the output depends on must be in keys: the current page ($module_result.uri or a node id), the signed-in user's roles if the output depends on permissions, a view parameter. A value that is not in the keys is printed for everyone as it was when the entry was made. Never put output for one user into a block keyed only by page: the next visitor sees it.
{cache-block subtree_expiry='news' expiry=0}
{* the latest news, renewed only when something below news is published *}
{/cache-block}Details: cache-block. The same block exists in the other engines as {expcacheblock} (Smarty) and {% expcacheblock %} (Twig).
Clearing
An edited template needs nothing: it is compiled again on its next use. Clear caches when the change is of another kind:
| After | Clear |
|---|---|
| A new template at a path no design had, or a changed override rule | php bin/php/ezcache.php --clear-tag=template, and --clear-tag=ini for the rule |
| A change that cached pages must show | php bin/php/ezcache.php --clear-id=content (the view cache) |
| A change inside a cache block | php bin/php/ezcache.php --clear-id=template-block |
| A new design folder, with DesignLocationCache=enabled | php bin/php/ezcache.php --clear-id=design_base |
Add --allow-root-user when you run it as root. The caches can also be cleared in the administration interface under Setup, Caches, and from the Cache tab of the Exp Debug bar. Avoid --clear-all on a busy site: every page then has to be built again.
The full story of every cache a template meets, with its file and key: Template caches; all caches of the system: Caches.
Contributors
- Graham Brookins Updated Maintainer
Comments
Add a comment