Skip to the content
Documentation
Help Start
Reading in:
  • German: 9,110 of 9,110 pages
About the help in other languages
All help pages

Caching for designers

The caches a designer's templates live in (view cache, cache-blocks, compiled templates, packed assets, Velocity's response cache), what each keeps, what clears it, and the template rules that keep cached pages correct…

Download as PDF

Address: https://doc.exponential.earth/exphelp/viewer/help/designers/theme-design/caching-for-designers.md

On this page

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

  1. The layers
  2. The view cache
  3. Cache-blocks
  4. Rules for templates
  5. Clearing

The layers

LayerHoldsCleared
View cachethe HTML of a node's full view ($module_result.content)on publish, for the affected nodes
Cache-blocksparts of templates you wrap in {cache-block}when keys change, on expiry, on content publish (unless told otherwise)
Compiled templatestemplates turned into PHPwhen the template file changes (with development checks) or on clear
Packed assetsmerged CSS and JSa new file per source change
Velocity response cachewhole responses, on installations with the Velocity server./console exp:velocity cache clear --apply

The view cache

site.ini [ContentSettings]:

ViewCaching=enabled
CachedViewModes=full;sitemap;pdf

The 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 of 0 stores 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_ttl keeps working.
  • Per node, ViewCacheTweaks[<node_id>] has options such as pr_user (cache per user) and disabled (comments in settings/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-block}

Parameters (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

AfterClear
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.

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.

Something wrong on this page? Report an error

Documentation license

This documentation is free documentation, licensed under the GNU Free Documentation License 1.3 or later.

Exponential Copyright © 1998-2026 Exponential Foundation and 7x