Path
ez.no / ezpublish / documentation / development / kernel / cache block optimization
Cache block optimization
These documentation pages are no longer maintained. Please visit the new documentation site.
When building a site you normally have several dynamic elments 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 eZ publish 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.
Example (pagelayout.tpl): <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>
In this example we've added a cache-block around the left menu navigation code. This means that the first time the page is loaded this code is executed and the result is stored in a text file. On the successive pageloads this text file will be loaded and no left menu code is executed. This will happen until the cache block is expired ( which is default 2 hours ).
Parameters
The cache-block function takes four parameters: keys and expiry, ignore_content_expiry and subtree_expiry.
Keys
The keys parameter can be used to define the uniqueness of the cache block. By default eZ publish 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 or as an array.
Example (unique per url): {cache-block keys=$uri_string} ... tpl code {/cache-block}
Example (unique per url and per user): {cache-block keys=array($uri_string,$current_user.contentobject_id)} ... tpl code {/cache-block}
Expiry
If you don't specify the expiry parameter eZ publish will automatically expire the cache block in two hours or if any content is published. This means that if you publish anything on your site all cache-blocks will be expired.
If this expiry does not fit your needs you can specify the expiry time manually in seconds.
Example (expire after 120s): {cache-block expiry=120} ... tpl code {/cache-block}
Ignore Content Expiry
only available in 3.3 or higher
Sometimes you do not want your cache blocks to expire when content is publish. For example expiring the footer containing the copyright doesn't make any sense, as it won't be affected by new content. With the "ignore_content_expiry" parameter you can disable the expiration when content is published:
{cache-block ignore_content_expiry} Cached content, even if an object is published. {/cache-block}
Subtree Expiry
only available in 3.4 or higher
Something inbetween the default policy of always expiring the cache blocks when content is published, and the functionality of "ignore_content_expiry" is the Subtree Expiry parameter. With this parameter you can control the expiration of a cache block when content in a specific subtree (like /products) is published. A real-life example might be where there is a block inside the pagelayout template which contains a list of the five last added products; in the following example the cache-block will be expired when there is something published in the /products/bargain subtre, or after 30 minutes:
{cache-block expiry=1800 subtree_expiry=/producs/bargain} ... tpl code {/cache-block}
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 of nested cache-blocks (pagelayout.tpl): {cache-block keys=$uri_string} <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} {/cache-block} {$module_result.content} {cache-block} {include uri="design:page_copyright.tpl"} </body> </html> {/cache-block}
Note: when using nested cache-blocks the outter most block will not know if a sub cache-block has/should have expired. This means that expiry needs to be set shortest for the outter most block.
Comments
role_id
Georg Franz
Wednesday 17 December 2003 12:47:36 am
Question 1:
Yes.
Question 2:
Nested cache-blocks make sense if the outer cache-block expires before the inner block does and if it's not necessary for the inner block to run again.
Example:
A static menu which is the same on all pages is the inner block, the outer block contains content which should be changed every 2h.
By the way, it makes no sense to set the inner block expires before the outer block because if the outer block is loaded from cache, the inner won't be rendered.
The $current_user is set in the pagelayout.tpl and contains informations about the "current user".
The $current_user is only set in pagelayout.tpl - as far as I know - not in the other tpls.
To get the $current_user in other templates use:
{default current_user=fetch('user','current_user')}
...
{/default}
$current_user.role_id_list is an array which keeps all role id's assigned to the current user. So my idea was: If you have dynamic content inside a cache-block (e.g. a menu) which doesn't contain personal user-information, the role-id-list should be enough for the cache-block-key.
If you use the current-user object id in the cache-key, a cache-block file for each user is produced which doesn't make sense in most cases.
cache-block keys: I give every cache-block at least one key (like "my_cache_block" - I don't know if it's necerssary.
Questions about cache-blocks
Marco Zinn
Saturday 13 December 2003 1:49:02 pm
First:
Using {cache-block} without keys result in exactly ONE cache-block-file (for that one location in the pagelayout.tpl). Right? That means, that this is only sensible for things, that never change (ie. footer).
So, i was confused by this block in the first code example:
{cache-block}
{include uri="design:left_menu.tpl"}
{/cache-block}
This will do no good, when the Menu is NOT the same all the time. Usually, it's different, depending on which page or "site area" you are, as explained later. Is this correct?
Question 2:
How do keys work when cache-blocks are nested?
What is nesting good for?
Example:
{cache-block keys=$uri_string}
[..]
{cache-block}
{include uri="design:left_menu.tpl"}
{/cache-block}
{/cache-block}
Does the inner cache-block user the same key(s) as the outer? If so, why should i declare another cache-block?
If it uses no key (in this example), it would make no sense to me to include it in a block with keys!
If it "inherits" the key from the outer block, can i declare additional keys? How deep can we nest blocks?
BTW: Please look at these comments, update the docu and remove this afterwards.
Thanks for the initial clarification.
To Emil: Thanks for the comments, but can you explain the $current_user.role_id_list|implode(',') key? Is this an array of the role ID, which you implode to get indivual keys for caching?
And why do you use "names" like 'my_cache_block' as the first key? I never saw this before.
cache-block, tip 2
Georg Franz
Friday 12 December 2003 4:18:46 pm
another tip for the cache-block usage:
If you allow visitors to create own user-accounts and you have elements which are changed dynamically based on the current user and other rules you have to create many cache-blocks to get the desired output. So the system creates a huge amount of cache-block files.
In most cases, around 80% to 90% of the visits of a site are produced by an 'anonymous user'.
So to speed up the caching, you can put something like this in your pagelayout.tpl:
{section show=$current_user.is_logged.in}
{cache-block keys=array('menu', ...)}
your code ...
{/cache-block}
{cache-block keys=array('user_information',...)}
your code ...
{/cache-block}
...
{section-else}
only one cache-block, because the content is the same for all users who are not logged in.
{cache-block keys=array('anonym',$uri_string)}
...
{/cache-block}
{/section}
Kind regards,
Emil.
cache-block - tip
Georg Franz
Thursday 04 December 2003 1:39:37 pm
thanx for the doc. I didn't know that it's possible using nested cache-blocks.
The cache-block feature is really fine and speeds up the page load a lot.
Another tip for using the cache-block feature:
------------------------------------------------
If you have many registered users at your site, don't use the user-id in the cache-block-keys if it's not needed. (e.g. you have 10.000 users, 50 are logged in and view the homepage - so 50 versions (files) of the homepage cache-blocks are created.)
It's a better idea to use the role-id list as key.
eg.
{cache-block keys=array('my_cache_block',$uri_string,$current_user.role_id_list|implode(',')) expiry=86400}
... content which is cachable ...
{/cache-block}
Kind regards,
Emil.