Summary

Usage

{cache-block [ keys=keys                      ]
             [ expiry=expiry                  ]
             [ ignore_content_expiry          ]
             [ subtree_expiry=subtree_expiry  ]}

...

{/cache-block}

Parameters

Description

This solution makes it possible to reduce the processing time of the main template ("pagelayout.tpl"), which often contains a lot of dynamic elements. It can be used to instruct the system to store and reuse cached blocks of template code based on different conditions.

A typical example of where the "cache-block" mechanism should be used is the main menu of a site. The menu is often dynamically generated by fetching and displaying information about some nodes. It is usually the same for almost every page, therefore it should not be generated from scratch every time eZ Publish is instructed to render a page. This is where the "cache-block" solution comes in. In this particular scenario, it can be used to cache the contents of the main menu and thus reduce the processing time for each page load.

Note 1: Template variables defined or set within the cache block will not be available further down the page, as only the html resulting from the execution of the cache-block is stored. For non-security-critical information, you might use javascript to that effect.

Note 2: The cache-block stores it's content as text fragments, and does not execute any of it content again before the cache has been expired.

Cache keys

The "keys" parameter can be used to define the uniqueness of a cache block. It must be either a string or an array of strings. By default, eZ Publish uses the name of the template and the position of the cache block as keys. This means that if the cache block is common for all cases that use the given template (normally "pagelayout.tpl"), there is no need to define any keys. However, the "keys" parameter is quite handy when it comes to relating a cache block to something specific (for example URLs, users, etc.). Please refer to the examples below for a demonstration of how this parameter can be used.

Time-based expiration

The "expiry" parameter makes it possible to manually specify how long a cache block should live (number of seconds). The default expiration time is two hours (this is hard-coded in the system and can not be configured). If an object is published, all blocks will automatically be expired. A value of zero will produce a cache block that will never expire.

Content expiration

By default, all cache blocks will be expired whenever an object is published. If the "ignore_content_expiry" parameter is used, the cache block will not be expired when an object is published. However, it will still expire after two hours unless an alternative time is specified using the "expiry" parameter.

Subtree expiration

The "subtree_expiry" parameter can be used to bind the expiration of a cache block to a certain part of the content node tree. When this is done, the block will expire if an object is published below the given subtree instead of the entire tree. In addition, it will also expire after two hours unless an alternative time is specified using the "expiry" parameter.

Value can be either node url alias, a node id or system url in the following format: "content/view/full/<node_id>".

Note: Using node id is recommended as it avoids node id look-up by url, avoids potential issues if url is changed and multi-lingual url if you hard code url alias and it's used on a siteaccess with different locale.

Tips and tricks

Since cache blocks themselves also produce some overhead, too many blocks may lead to longer response times than expected. Because of this, only a few cache blocks should be used; and their keys should be as unique as possible. It is often very efficient to have two large cache blocks. One which caches all header information (title, path, etc.) and one which will take care of the bottom/footer of the page. This solution combined with a nested cache block used for the main menu (or several menus, etc.) often leads to good results. Please note that although the cache block mechanism was designed to minimize the processing of the main template, it may also be used in view templates. For example, it is possible to cache a part of a view - this is typically useful when the viewcache is frequently deleted. Another scenario is when the view cache is turned off and there is a need to create a cache on a per-user basis.

Examples

Example 1

...
{include uri='design:page_toppath.tpl'}
 
{cache-block}
    {include uri='design:menu.tpl'}
{/cache-block}
 
{$module_result.content}
 
{include uri='design:page_bottom.tpl'}
...

This example demonstrates how the cache block solution can be used to cache the contents of a menu (which will be the same for all pages) in the page layout.

Example 2

{cache-block expiry=130}
...
{/cache-block}

This example demonstrates how to create a cache block that will expire after 130 seconds.

Example 3

{cache-block keys=$uri_string}
...
{/cache-block}

This example demonstrates how to create a cache block that will be unique for every URL.

Example 4

{cache-block keys=array( $uri_string, $current_user.contentobject_id )}
...
{/cache-block}

This example demonstrates how to create a cache block that is unique for each URL and each user.

Example 5

{cache-block ignore_content_expiry}
...
{/cache-block}

This example demonstrates how to create a cache block that will not expire when new content is published. However, it will expire every second hour unless an alternative "time to live" value is specified using the "expiry" parameter.

Example 6

{cache-block subtree_expiry=44}
...
{/cache-block}

This example demonstrates how to create a cache block that will expire only if something is modified within the subtree of node id '44', for example if sub content is modified or new content is published beneath this node.

Example 7

{cache-block subtree_expiry=$my_node.node_id}
...
{/cache-block}

This example demonstrates how to create a cache block that will expire only if something is modified within the subtree of $my_node. Example demonstrates that node id can come from an dynamic variable.