Summary

Caches the contents of a template block.

Usage

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

...

{/cache-block}

Parameters

Name	Type	Description	Required
keys	string or array	Cache key(s) - either as a string or an array of strings.	No.
expiry	integer	The number of seconds that the cache should be allowed to live.	No.
ignore_content_expiry	-	Disables cache expiry when new content is published.	No.
subtree_expiry	string	A subtree that expires the cache block.	No.

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.

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

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

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='products/'}
...
{/cache-block}

This example demonstrates how to create a cache block that will expire only if something is modified within the "products/" subtree, for example if a product is modified or a new product is published.

---