Variable Cache Plugin

Caches the results of expanding macros in selected topics for improved server performance

Most topics in a typical Foswiki installation are rendered within a small deviation in terms of speed. Exceptions are topics that contain a lot of dynamic content. This is mainly caused by CPU or I/O intensive Macros, such as %SEARCH{}% and %INCLUDE{}%.

This plugin caches all %MACROS% located in a topic so that the topic can get rendered as quickly as one without macros. An outdated cache gets refreshed when a user is looking at a topic; in which case it will take longer to render the page. Time-based refresh can also be disabled in favor of an on-demand cache update.

The rendering of Foswiki topic markup to HTML is not cached. That is, user specific HTML rendering based on skin settings is not affected by the caching.

ALERT! This plugin assumes topics are stored in files on disk. As such it will work with the standard Foswiki store implementations; it will not, however, work any non-caching database store.

Syntax Rules and Cache Update Rules

Add a %VARCACHE{}% variable to the topic you want to cache

  • Syntax: %VARCACHE{ "24" }%
  • Supported attributes:
    Attribute Comment Default
    "..." or
    Cache refresh period in hours (maximum age of cache). Accepts decimals, such as 0.25 24
    cachemsg="..." Message shown when looking at a cached topic. Use $age to indicate the age of cache, $link to indicate the refresh URL This topic was cached $age ago ([[$link][refresh]])
    updatemsg="..." Message shown after a cache refresh. Use $link to indicate the refresh URL This topic is now cached ([[$link][refresh]])
  • Example: %VARCACHE{"168"}% caches the current page for 7 days
  • The standard Foswiki format tokens are supported in cachmsg and updatemsg.

%VARCACHE{}% gets:
  • replaced with the cachemsg message when looking at a cached topic
  • replaced with the updatemsg message if the cache has just been updated
  • removed if caching is not active, e.g. when the topic gets rendered dynamically
The cache gets updated on topic view if:
  • the cache does not exist (e.g. after adding the %VARCACHE{}% variable)
  • the cache is older then the cache refresh period (unless refresh if set to 0)
  • the cache is older then the topic (e.g. the topic has been updated)
  • the topic is accessed with a ?varcache=refresh URL parameter (usually by following the refresh link in the cache message)
The topic is rendered dynamically without caching when:
  • the topic has URL parameters other then varcache (e.g. to show dynamic content properly, such as table sorting, filtering, searching)
  • the topic is previewed after editing
  • The cache is not user specific. For example, all users see the expanded %WIKIUSERNAME% of the person who refreshed the cache (on demand or by looking at a topic with an expired cache)


Settings are stored as preferences values. You can override the defaults for these preferences in SitePreferences, the WebPreferences topic of the current web, or in individual topics that use the plugin.

ALERT! Changing them here will have no effect!

  • One line description, is shown in the TextFormattingRules topic:
    • Set VARCACHEPLUGIN_SHORTDESCRIPTION = Cache Foswiki macros in selected topics for faster page rendering

  • Default refresh period in hours. No automatic refresh: 0, default: 24

  • Cache help messages. Use $age to indicate age of cache, $link to indicate the refresh URL
    • Set VARCACHEPLUGIN_CACHEMSG = This topic was cached $age ago ([[$link][refresh]])
    • Set VARCACHEPLUGIN_CACHEMSG = This topic was cached $age ago. Click icon to refresh.
    • Set VARCACHEPLUGIN_UPDATEMSG = This topic is now cached ([[$link][refresh]])
    • Set VARCACHEPLUGIN_UPDATEMSG = This topic is now cached. Click icon to refresh.

Installation Instructions

You do not need to install anything in the browser to use this extension. The following instructions are for the administrator who installs the extension on the server.

Open configure, and open the "Extensions" section. Use "Find More Extensions" to get a list of available extensions. Select "Install".

If you have any problems, or if the extension isn't available in configure, then you can still install manually from the command-line. See for more help.


Author: Design and original implementation: PeterThoeny
Copyright: © 2004-2007, TWIKI.NET and TWiki Contributors
© 2008-2012 Foswiki Contributors
License: GPL (GNU General Public License)
Plugin Release: 1.2
Plugin Version: 14435 (2012-03-23)
Change History:  
1.2 (23 Mar 2012) Foswikitask:Item5414: support header zones -- Foswiki:Main.CrawfordCurrie
1.1 (28 Jul 2011) Minor bugfix -- Foswiki:Main.CrawfordCurrie
1.0 (05 May 2011) Foswikitask:Item10713: cache is now stored in the plugins work area, not under pub
Foswikitask:Item10712: No longer read preferences from plugin topic -- Foswiki:Main.AndrewJones
29 Jan 2009: Foswiki version -- Foswiki:Main.KennethLavrsen
Plugin Home:
Topic revision: r1 - 06 Mar 2006, ProjectContributor
This site is powered by FoswikiCopyright © CC-BY-SA by the contributing authors. All material on this collaboration platform is copyrighted under CC-BY-SA by the contributing authors unless otherwise noted.
Ideas, requests, problems regarding Foswiki? Send feedback