Variable Cache Plugin

Overview

This Plugin caches TWiki variables in selected topics for faster page rendering.

Most topics in a typical TWiki 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 TWikiVariables, such as %SEARCH{}% and %INCLUDE{}%.

This Plugin caches all %VARIABLES% located in a topic so that the topic can get rendered as quickly as one without variables. 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 TWiki markup to HTML is not cached. That is, user specific HTML rendering based on skin settings is not affected by the caching.

Syntax Rules and Cache Update Rules

• Add a %VARCACHE{}% variable to the topic you want to cache
  • It supports these parameters:

    Parameter	Description	Default
    "..." or refresh="..."	Cache refresh period in hours, e.g. maximum age of cache	REFRESH Plugin setting
    cachemsg="..."	Message shown when looking at a cached topic Note: Use $age to indicate the age of cache, $link to indicate the refresh URL	CACHEMSG Plugin setting
    updatemsg="..."	Message shown after a cache refresh Note: Use $link to indicate the refresh URL	UPDATEMSG Plugin setting

• The %VARCACHE{}% variable 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 than the cache refresh period (unless refresh if set to 0)
  • the cache is older than 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 than varcache (e.g. to show dynamic content properly, such as table sorting, filtering, searching)
  • the topic is previewed after editing
• Limitations:
  • 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)

Plugin Settings

This plugin can be configured with preferences settings in Main.TWikiPreferences (site level), a WebPreferences (web level) or in a topic (page level). Do not change the settings here, they are here only to illustrate the default values. To overload, copy the settings to one of the aforementioned topics.

• Debug plugin: (See output in data/debug.txt)
  • Set VARCACHEPLUGIN_DEBUG = 0

• Default refresh period in hours. No automatic refresh: 0, default: 24
  • Set VARCACHEPLUGIN_REFRESH = 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_UPDATEMSG = This topic is now cached ([[$link][refresh]])
  • #Set VARCACHEPLUGIN_CACHEMSG =
  • #Set VARCACHEPLUGIN_UPDATEMSG =

Plugin Installation Instructions

Note: You do not need to install anything on the browser to use this plugin. The following instructions are for the administrator who installs the plugin on the TWiki server.

• Download the ZIP file from the Plugin web (see below)
• Unzip VarCachePlugin.zip in your twiki installation directory. Content:

  File:	Description:
  data/TWiki/VarCachePlugin.txt	Plugin topic
  data/TWiki/VarCachePluginTest.txt	Plugin test topic
  data/TWiki/VarVARCACHE.txt	Variable documentation topic
  lib/TWiki/Plugins/VarCachePlugin.pm	Plugin Perl module
  pub/TWiki/VarCachePlugin/cachetopic.gif	Cache icon 16x16

• TWiki 4.0 and up: Run the configure script to enable the Plugin
• Test if the installation was successful:
  • Visit the VarCachePluginTest topic, it contains a nested search
  • Click on the refresh link or append a ?varcache=refresh parameter to the URL

Plugin Info

• One line description, is shown in the TextFormattingRules topic:
  • Set SHORTDESCRIPTION = Cache TWiki variables in selected topics for faster page rendering

Plugin Author:	TWiki:Main.PeterThoeny
Copyright:	© 2004-2011, Peter Thoeny, Twiki, Inc. © 2008-2011 TWiki:TWiki.TWikiContributor
License:	GPL (GNU General Public License)
Plugin Version:	2011-05-25
Change History:
2011-05-25:	TWikibug:Item6701: Small code refactor; adding $SHORTDESCRIPTION that was missing in previous release
2011-05-24:	TWikibug:Item6730: Move cache data from pub directory to working directory; Use proper umask for directories created; Fix to make it better run under mod_perl; Support abbreviated %VARCACHE% syntax; Possible to specify a refresh of 0 (meaning infinite) -- TWiki:Main.TimotheLitt
2011-05-01:	TWikibug:Item6701: Doc improvements
2010-04-25:	TWikibug:Item6433: Doc fix: Changing TWIKIWEB to SYSTEMWEB
2010-04-06:	TWikibug:Item5414: Support for plugins that dynamically add JavaScript and CSS using TWiki::Func::addToHEAD(); added VarVARCACHE variable documentation topic; support nameless parameter for refresh time; fixed typo in UPDATEMSG plugin setting name
2006-01-06:	Small fix for TWiki 4.0
2004-07-16:	Doc improvements (no code change)
2004-07-15:	Initial version
TWiki Dependency:	$TWiki::Plugins::VERSION 1.1 (TWiki 4.0, 2006-02-01)
CPAN Dependencies:	none
Other Dependencies:	none
Perl Version:	5.005
TWiki:Plugins/Benchmark:	GoodStyle 99%, FormattedSearch 99%, VarCachePluginTest 208%
Plugin Home:	http://TWiki.org/cgi-bin/view/Plugins/VarCachePlugin
Feedback:	http://TWiki.org/cgi-bin/view/Plugins/VarCachePluginDev
Appraisal:	http://TWiki.org/cgi-bin/view/Plugins/VarCachePluginAppraisal

Related Topics: VarVARCACHE, VarCachePluginTest, TWikiPlugins, DeveloperDocumentationCategory, AdminDocumentationCategory, TWikiPreferences