Caution: This documentation is for eZ Publish legacy, from version 3.x to 5.x.
For 5.x documentation covering Platform see eZ Documentation Center, for difference between legacy and Platform see 5.x Architecture overview.

cache-block

Summary

Caches the contents of a template block to static content for fast retrieval. Useful to avoid fetching content over and over from database when it is possible to cache it within a set of parameters. Note: cache-blocks also introduces some overhead, so do not have too many of them on a page, let them span parts of your page like e.g. header, footer and left menu.

Usage

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

...

{/cache-block}

Parameters

NameTypeDescriptionRequired
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 or integer A subtree that expires the cache block, either node url alias or node id. no. 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.

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.

Note: Please be aware that backend preview will take into account cache-blocks, that might result in undesired cached content. This is the intended behavior. To prevent this from happening, make sure anything related to $node is coded outside of the cache blocks.

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.

Balazs Halasy (06/02/2004 1:19 pm)

Sarah Haïm-Lubczanski (26/09/2014 11:46 am)

Balazs Halasy, Geir Arne Waaler, Sarah Haïm-Lubczanski


Comments

  • $uri_string case sensitive

    $uri_string is case sensitive, so that

    {cache-block keys=$uri_String} {/cache-block} equals {cache-block}{/cache-block}. Remember to use {cache-block key=$uri_string} .

    • Re: $uri_string case sensitive

      All variable names are case sensitive!
  • If you're wondering why your cache block dont behave like they should

    Try setting {set-block scope=root variable=cache_ttl}0{/set-block} in the first line of the template.

    For reference, for example, http://ez.no/community/forum/developer/view_cache_trouble/
    • Re: If you're wondering why your cache block dont behave like they should

      This is wrong, that won't have any effect on cache blocks, only on view cache!
      • Re: Re: If you're wondering why your cache block dont behave like they should

        If you're trying to make use of cache blocks in the template for content/view then this is not wrong at all ;)
  • variable scope inside cache block

    maybe obvious, but if you write

      {cache-block}
        {def $nose="black"}
      {/cache-block}
      {$nose}
    


    it will print "black" the first time you load a page,
    and nothing the second time you load it

    iow, variables are always scoped inside a cache-block.

    $2c,
    *pike



  • doc update for subtree_expiry

    Hi,

    just studied the source code:

    subtree_expiry could be also a numeric value, the node_id.

    The path_identification_string is using the old url schema.

    Best wishes,
    Georg.
    • node_id not working for me

      Sorry, but for me, node_id is not working.

      subtree_expiry=$module_result.node_id
      


      does not work...
      • Re: node_id not working for me

        $module_result.node_id is only set on content/view pages, could that be the reason?
    • Re: doc update for subtree_expiry

      to be more precise: giving a node id means that the block will expire when something is published below the node or when the node itself is published (the subtree root is included, that is).
  • Pitfall when using cache-block combined with both hostname and URI matching

    You might get into problem if using both hostname and URI matching when using URI as key in cache-block

    More information is available here:
    http://svn.projects.ez.no/ezsiteaccessoperator/trunk/README.txt
    http://projects.ez.no/ezsiteaccessoperator
  • No reaction using this

    Hi!

    I've set up EZ Publish with the ezflow-extention, but i need some parts of the templates to not be cached. Using this doesnt give any results.

    Are there any other ways to disable cache for a section of a template? like {dont-cache} somecode {/dont-cache}

    I tried putting:

    {set-block scope=root variable=cache_ttl}0{/set-block}

    On the very top of event_view_calendar_tpl for instance. But it still caches the template. Is there any pitfalls on this topic?

    Thanks!

    John
    • Re: No reaction using this

      Check any template that calls event_view_calendar.tpl for their own set-block.
    • Re: No reaction using this

      Always use:
      {set-block scope=global variable=cache_ttl}0{/set-block}
      When you want to disable view cache.

      But this has no effect for cache-blocks.