[PHPTAL] 1.1.9 phptal:cache documentatioin

[Kornel Lesinski]

phptal:cache (note that's not tal:cache) caches element's HTML (processed  
output) for a given time. Time is a number with 'd', 'h', 'm' or 's'  
suffix, e.g.:

<div phptal:cache="3h">...</div>

This will cause this <div> to be evaluated at most once per 3 hours.


* Shared vs per-page cache

There's optional parameter that defines how cache should be shared. By  
default cache is not sensitive to template's context at all - it's shared  
between all pages that use that template.

You can add "per url" to have separate copy of given element for every  
URL, e.g.

<ul phptal:cache="10m per url">...</ul>

<ul> will be evaluated at most every 10 minutes and will have separate  
copy for each page/URL.

You can add "per expression" to have different cache copy for every  
different value of an expression. Expression must evaluate to a string  
(arrays/objects are not supported!). Expression cannot refer to variables  
defined using tal:define on the same element, because cache caches  
tal:define as well.

<p phptal:cache="1d per user/id">...</p>

<p> will be cached for one day and will have separate copy for every user  
id, so it can contain private user-specific data.


* Caveats

phptal:cache blocks can be nested, but outmost block will cache other  
blocks regardless of their freshness.
metal:fill-slot will behave erratically inside cached blocks. You must  
avoid caching elements that use it.

----

Cache is stored in the same directory as compiled templates.


To get most of the cache, you should pass objects to template that  
"lazily" fetch data only when asked. This way you can avoid needlessly  
preparing data for fragments of template that won't be evaluated, e.g.  
instead of:

$phptal->some_list = fetch_data_from_the_database();

use:

class Foo
{
	function get_list() {return fetch_data_from_the_database();}
}

$phptal->some_list = new Foo();

-- 
regards, Kornel