ez.no / exponential / documentation / reference / template functions / miscellaneous / cache-block
{cache-block [keys=value1] [expiry=value2] [ignore_content_expiry] [subtree_expiry=value3]}
{* tpl code *}
{/cache-block}
| Name | Type | Description | Required |
|---|---|---|---|
| value1 | string or array | cache key(s) | no |
| value2 | integer | timeout in seconds before cache expires | no |
| ignore_content_expiry | - | disables cache expiry when new content is publish | no |
| value3 | string | subtree which expires the cache block | no |
When building a site you normally have several dynamic elements in your main template pagelayout.tpl. This template will then use much of the total processing time for your site, which is undesireable. To limit this processing time you can use the cache-block template function.
How it works
The principle of the cache-block function is to store the result of dynamic template code in a plain HTML/text file which can be loaded the next time the same code is requested.
For example you normally have a list of folders/objects which makes up your navigation menu. This menu is often the same for many/every page and will cause unneeded overhead since Exponential will fetch this information on every pageload. You can use a cache block to store the result of the dynamic code which makes up your navigation to remove this overhead.
Keys
The keys parameter can be used to define the uniqueness of the cache block. By default Exponential uses the template name and position of the block as keys. This means that if the cache-block is common for all cases that use the given template (normally pagelayout.tpl) you don't need to specify any keys.
If you need to specify a key you can do this either as a single variable (example 2) or as an array (example 2).
Expiry
If you don't specify the expiry parameter, Exponential will automatically expire the cache block in two hours or if any content is published. If this expiry does not fit your needs you can specify the expiry time manually in seconds.
A value of 0 will disable cache expiry based on time alltogether. This feature is only available in 3.4 and later (3.4 alpha 2, rev. 5531 to be precise)
ignore_content_expiry
By default, Exponential will expire all cache-blocks if you publish anything on your site.
If you spesify the ignore_content_expiry parameter, Exponential WILL NOT expire the cache-block when new content is published. Cache-block will still expire after 2 hours or any other timeout set by the Expiry parameter. This parameter is only available in Exponential 3.3 and later (3.3 beta 2, rev. 4406 to be precise)
subtree_expiry
This option makes it possible to expire a cache block when content is published under a specific subtree. Using this option will also implicitly turn on 'ignore_content_expiry' for this specific cache-block. This parameter is only available in Exponential 3.4 and later (3.4 alpha 2, rev. 5531 to be precise). See also example 6.
Usage tips
Since there is some overhead in using the cache-block itself you should try to use as few cache-blocks as possible and make them unique enough using keys.
It's often very efficient to have two large cache-blocks which will cache all header information/title/path and footer information. This used in combination with a nested cache-block to only process e.g. a menu once is efficient.
Example 1 (pagelayout.tpl):
In this example, the left menu will be stored in a cache-block. Note that in this example, the menu will be the same on all pages
<html> <head> <link rel="stylesheet" type="text/css" href={"stylesheets/core.css"|ezdesign} /> <link rel="stylesheet" type="text/css" href={"stylesheets/debug.css"|ezdesign} /> {include uri="design:page_head.tpl" enable_glossary=false() enable_help=false()} </head> <body> {include uri="design:page_toppath.tpl"} {cache-block} {include uri="design:left_menu.tpl"} {/cache-block} {$module_result.content} {include uri="design:page_copyright.tpl"} </body> </html>
Example 2 (unique pr url):
In this example, we supply one key to the cache-block
{cache-block keys=$uri_string} ... tpl code {/cache-block}
Example 3 (unique pr url and pr user):
In this example, we supply two keys using an array
Example (unique pr url and pr user):
{cache-block keys=array($uri_string,$current_user.contentobject_id)} ... tpl code {/cache-block}
Example 4
A template block will by default expire after 2 hours.
This templateblock will expire after 120 seconds
{cache-block expiry=120} ... tpl code {/cache-block}
Example 5
This templateblock will not expire when new content is published. However, it will expire every second hour.
{cache-block ignore_content_expiry} ... tpl code {/cache-block}
Example 6
This templateblock will expire when new content is published under the "services/" subtree (eg, a new item "services/item").
{cache-block subtree_expiry="services/"} ... tpl code {/cache-block}
log in or create a user account to comment.
Comments