Caching for designers
This page is for designers who want fast pages that are still correct for every visitor. Exponential caches at several levels; most of them work without the designer doing anything, but templates can break them, or be broken by them.
Contents
The layers
| Layer | Holds | Cleared |
|---|---|---|
| View cache | the HTML of a node's full view ($module_result.content) | on publish, for the affected nodes |
| Cache-blocks | parts of templates you wrap in {cache-block} | when keys change, on expiry, on content publish (unless told otherwise) |
| Compiled templates | templates turned into PHP | when the template file changes (with development checks) or on clear |
| Packed assets | merged CSS and JS | a new file per source change |
| Velocity response cache | whole responses, on installations with the Velocity server | ./console exp:velocity cache clear --apply |
The view cache
site.ini [ContentSettings]:
ViewCaching=enabled
CachedViewModes=full;sitemap;pdfThe full view of a node is cached per node, view mode, language, the user's roles and limitations, view parameters and
more (the hash is built in kernel/classes/eznodeviewfunctions.php). The pagelayout is not cached; it runs on every
request around the cached content.
Consequences for designers:
- A full view template must not print anything specific to one visitor (their name, their basket) unless the cache varies by it. Put such things in the pagelayout, or in a part that is not cached.
- A full view can set its own lifetime with the template variable
cache_ttl, which the kernel reads after rendering (eznodeviewfunctions.php). The ezwebin event calendar keeps its page for 400 seconds:{set-block scope=root variable=cache_ttl}400{/set-block}. A value of0stores nothing; use that rarely, since a page that is never cached is rendered on every request. - Since 6.0.15, output that changes at a known time says so with
{cache_until( 'tomorrow' )},{cache_until( $event_start )}or{cache_until( 0 )}: it works in every template (the pagelayout, menus, layout blocks, cache-block bodies too), and every cache keeps the page no longer (cache_until and seconds_until, Caching time-dependent content).cache_ttlkeeps working. - Per node,
ViewCacheTweaks[<node_id>]has options such aspr_user(cache per user) anddisabled(comments insettings/site.ini).
Cache-blocks
Wrap expensive parts of the pagelayout (menus, footers) in a cache-block with the keys that change their output:
cache-block keys=array( $module_result.uri, $current_user.role_id_list|implode( ',' ) )
include uri='design:pagelayout/menu.tpl'
/cache-blockParameters (lib/eztemplate/classes/eztemplatecachefunction.php): keys, expiry (seconds; default 7200; 0 for
no time limit), ignore_content_expiry (keep it when content is published), subtree_expiry (expire when something
below a node is published). Details: Cache-block.
Rules for templates
- Everything that changes the output is a key. The current page, the user's roles, the language, the basket state. A menu that marks the current page needs the URI or node id in its keys.
- Never put user data in a block without the user in the keys (or without the role list, if it varies only by role).
- Never print
csp_nonce()in a cache-block or a view-cached template: the nonce changes on every request. - Keep keys small. Every distinct key value writes a cache file. The admin pagelayout casts its section filter to a number for that reason ("every distinct raw value would write its own cache file").
- Do not fetch inside a block what is needed outside it: a cache hit skips the fetch.
Clearing
| After | Clear |
|---|---|
| changing a view template | --clear-id=content (and template if compiled templates are not checked) |
| changing a part inside a cache-block | --clear-id=template-block |
| adding templates or overrides | --clear-id=template-override |
See The packer cache and deploys for the full table.
Related pages
- Cache-block
- cache_until and seconds_until
- Template compilation and cache
- Theme performance
- Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.
Become an Exponential Partner
Partners share their information, provide funding, contribute back and develop the products with us, and that is how Exponential grows. A partner website and dashboard are planned for mid-2027: please become a partner today to speed up our growth rate and land new features faster.