7.4.2 Caching entire regions

#cache [id=EXPR] [timer=EXPR] [test=EXPR]
#end cache

The #cache directive is used to cache a region of content in a template. The region is cached as a single unit, after placeholders and directives inside the region have been evaluated. If there are any $*<interval>*var placholders inside the cache region, they are refreshed only when both the cache region and the placeholder are simultaneously due for a refresh.

Caching regions offers more flexibility than caching individual placeholders. You can specify the refresh interval using a placeholder or expression, or refresh according to other criteria rather than a certain time interval.

#cache without arguments caches the region statically, the same way as $*var. The region will not be automatically refreshed.

To refresh the region at an interval, use the timer=EXPRESSION argument, equivalent to $*<interval>*. The expression should evaluate to a number or string that is a valid interval (e.g., 0.5, '3m', etc).

To refresh whenever an expression is true, use test=EXPRESSION. The expression can be a method/function returning true or false, a boolean placeholder, several of these joined by and and/or or, or any other expression. If the expression contains spaces, it's easier to read if you enclose it in (), but this is not required.

To refresh whenever you say so, use id=EXPRESSION. Your program can then call .refreshCache(ID) whenever it wishes. This is useful if the cache depends on some external condition that changes infrequently but has just changed now.

You can combine arguments by separating them with commas. For instance, you can specify both id= and interval=, or id= and test=. (You can also combine interval and test although it's not very useful.) However, repeating an argument is undefined.

#cache
This is a static cache.  It will not be refreshed.
$a $b $c
#end cache

#cache timer='30m', id='cache1'
#for $cust in $customers
$cust.name:
$cust.street - $cust.city
#end for
#end cache

#cache id='sidebar', test=$isDBUpdated
... left sidebar HTML ...
#end cache

#cache id='sidebar2', test=($isDBUpdated or $someOtherCondition)
... right sidebar HTML ...
#end cache

We are planning to add a 'varyBy' keyword argument in the future that will allow a separate cache instances to be created for a variety of conditions, such as different query string parameters or browser types. This is inspired by ASP.net's varyByParam and varyByBrowser output caching keywords.