Cache Macro

Last modified by Admin on 2024/05/11 02:02

cogCache the content of the macro for some time
Developed by

XWiki Development Team

Active Installs1
0 Votes
LicenseGNU Lesser General Public License 2.1
Bundled With

XWiki Standard

Installable with the Extension Manager


Renders the cache macro content as wiki syntax once, then caches the result (the Abstract Syntax Tree (a.k.a XDOM) of the content is cached, after Macros have been executed) for some time and when this time expires, the content is recomputed again and put in cache again, and the cycle repeats.


{{cache id="..." timeToLive="..." maxEntries="..."}}
content to cache here...
Parameter NameMandatory?Default ValueDescription
idcancelThe macro content itselfIf specified use the id as the key to the cache. If not defined then the macro uses its content as the id. However this doesn't guarantee unicity since the same content could be located on several pages with different results. Also note that the id can contain wiki syntax; this is done so that the user can use script macros to generate the id.
timeToLivecancel300 seconds (5 minutes)Set the cache duration for entries, in seconds. It's the number of seconds after which the cache entry will expire (since the last time it was used in 7.4M2 and since its insertion in the cache in 7.4M2).
Currently the max time to live you can specify is 2147483647 seconds which corresponds roughly to 24855 days, i.e. 68 years. See the documentation for the maxEntries below for performance considerations. Since 3.3M1
maxEntriescancel1000The maximum number of cached entries in a given cache. Since 3.3M1


If you use script macros in the content of the cache macro then the scripts will be executed only once (just before they are cached). Thus if those scripts do some dynamic actions they'll be executed only once (just before the content is cached).

Some examples:

  • If you get the current user in a script and display it, you'll always get the same value during the caching period even if another user is logged in.
  • If you call some Skin Extension APIs (JSX, SSX) from within your script, then those Skin Extensions won't be called again during the caching period and thus you won't see their effects.


Force the usage of an id:

{{cache id="myuniqueid"}}
content to cache here...

Compute the id based on some script evaluation:

#set ($myid="somecomputeduniqueid")

{{cache id="~{~{velocity~}~}$myid~{~{/velocity~}~}"}}
content to cache here...

Compute the id based on some URL parameter:

{{cache id="~{~{velocity~}~}${~{/velocity~}~}"}}
content to cache here...

Use a different time to Live (1 hour):

{{cache id="id" timeToLive="3600"}}
content to cache here...

A cache that auto-refreshes when the document's content is changed and a timeout of 1 day:

{{cache id="~{~{velocity~}~}$doc.fullName#${~{/velocity~}~}" timeToLive="84600"}}
content to cache here...

Prerequisites & Installation Instructions

We recommend using the Extension Manager to install this extension (Make sure that the text "Installable with the Extension Manager" is displayed at the top right location on this page to know if this extension can be installed with the Extension Manager).

You can also use the manual method which involves dropping the JAR file and all its dependencies into the WEB-INF/lib folder and restarting XWiki.


Dependencies for this extension (org.xwiki.platform:xwiki-platform-rendering-macro-cache 16.3.1):

Get Connected