(r1) VarCachePlugin

Tags: view all tags
---+!! Variable Cache Plugin 
<!--
   Contributions to this plugin are appreciated. Please update the plugin page at
   http://twiki.org/cgi-bin/view/Plugins/VarCachePlugin or provide feedback at
   http://twiki.org/cgi-bin/view/Plugins/VarCachePluginDev.
   If you are a TWiki contributor please update the plugin in the SVN repository.
-->
<sticky><div style="float:right; background-color:#EBEEF0; margin:0 0 20px 20px; padding: 0 10px 0 10px;">
%TOC{title="Page contents"}%
</div></sticky>
%SHORTDESCRIPTION%

---++ 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 %SYSTEMWEB%.TWikiVariables, such as =%<nop>SEARCH{}%= and =%<nop>INCLUDE{}%=. 

This Plugin caches all =%<nop>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 cache of affected topics can be invalidated based on parent relationship, backlinks and topic includes.

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 =%<nop>VARCACHE{}%= variable to the topic you want to cache
      * It supports these parameters:
        | *Parameter* | *Description* | *Default* |
        | ="..."= or%BR% =refresh="..."= | Cache refresh period in hours, e.g. maximum age of cache | =REFRESH= Plugin setting |
        | =cachemsg="..."= | Message shown when looking at a cached topic %BR% __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 %BR% __Note:__ Use =$link= to indicate the refresh URL | =UPDATEMSG= Plugin setting |
   * The =%<nop>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 =%<nop>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 <u>refresh</u> link in the cache message)
   * The topic is rendered dynamically without caching when:
      * the topic has URL parameters other than =varcache= and =topic= (e.g. to show dynamic content properly, such as table sorting, filtering, searching)
      * the topic is previewed after editing
   * Exclude variables from getting cached:
      * Prefix any variable with =VARCACHE_EXCLUDE_= and it will be excluded from caching. For example, to exclude =%<nop>WIKIUSERNAME%= write =%<nop>VARCACHE_EXCLUDE_WIKIUSERNAME%=. Make sure to escape all variables that depend on an escaped variable. For example, escape a FORMFIELD variable if it encloses an escaped WIKIUSERNAME:
        %BR% =%<nop>VARCACHE{"24"}%=
        %BR% =%<nop>VARCACHE_EXCLUDE_FORMFIELD{ "FirstName" topic="%<nop>VARCACHE_EXCLUDE_WIKIUSERNAME%" }%=
      * Or, use =&lt;varcache_exclude&gt; ... &lt;/varcache_exclude&gt;= to exclude sections of a page from caching. Example:
        %BR% =%<nop>VARCACHE{"24"}%=
        %BR% =Cached: %<nop>SEARCH{ "." nonoise="on" format="$topic" separator=", " limit="10" }%=
        %BR% =&lt;varcache_exclude&gt;=
        %BR% =Not cached: %<nop>SEARCH{ "%<nop>WIKINAME%" nonoise="on" format="$topic" separator=", " limit="10" }%=
        %BR% =&lt;/varcache_exclude&gt;=
        %BR% =Cached: %<nop>WEBLIST{}%=

---++ Plugin Settings

This plugin can be configured with preferences settings in [[%LOCALSITEPREFS%]] (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. On a large site having many webs, it's recommended to set VARCACHEPLUGIN_INVALIDATEONUPDATE =none= at the site level to prevent save slowness from happening unknowingly. The current site level setting is %IF{"'%VAR{VARCACHEPLUGIN_INVALIDATEONUPDATE}%' != ''"
 then="=%VARCACHEPLUGIN_INVALIDATEONUPDATE%="
 else="undefined, which is the same as =include="
}%.

   * 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

   * On topic creation and topic update, invalidate cache of affected topics: =parent= (its parent topic), =parent(32)= (its parent topics on parent path up to 32 levels), =backlinks= (its backlink topics in current web), =include= (its including topics in current web), =none= (no invalidation), or a comma-list thereof. %BR% __Note:__ Invalidating affected topics can slow down topic save in very large webs; it is recommended to set this to =none= for webs that have 10K+ topics.
      * Set VARCACHEPLUGIN_INVALIDATEONCREATE = parent
      * <nop>Set VARCACHEPLUGIN_INVALIDATEONUPDATE = include, parent

   * 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 ([<nop>[$link][refresh]])
      * Set VARCACHEPLUGIN_UPDATEMSG = This topic is now cached ([<nop>[$link][refresh]])
      * #Set VARCACHEPLUGIN_CACHEMSG = <a href="$link"><img src="%ATTACHURLPATH%/cachetopic.gif" title="This topic was cached $age ago. Click the icon to refresh." alt="Refresh cache" width="16" height="16" border="0" /></a>
      * #Set VARCACHEPLUGIN_UPDATEMSG = <a href="$link"><img src="%ATTACHURLPATH%/cachetopic.gif" title="This topic is now cached. Click the icon to refresh." alt="Refresh cache" width="16" height="16" border="0" /></a>

---++ Limitations

   * __Users:__ The cache is not user specific. For example, all users see the expanded =%<nop>WIKIUSERNAME%= of the person who refreshed the cache (on demand or by looking at a topic with an expired cache) unless the variable is specifically excluded from caching.
      * To exclude a user specific variable such as =%<nop>WIKIUSERNAME%= write =%<nop>VARCACHE_EXCLUDE_WIKIUSERNAME%=. 
      * The =&lt;varcache_exclude&gt; ... &lt;/varcache_exclude&gt;= tags can't be used in included topics; use the =VARCACHE_EXCLUDE_= variable prefix in included topics.

   * __Cache invalidation:__ Invalidating affected topic caches can slow down topic saves in very large webs.
      * Set =VARCACHEPLUGIN_INVALIDATEONUPDATE= to =none= for webs that have 10K+ topics.

---++ 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.
%TWISTY{
 mode="div"
 showlink="Show details %ICONURL{toggleopen}% "
 hidelink="Hide details %ICONURL{toggleclose}% "
}%

   * For an __automated installation__, run the [[%SCRIPTURL{configure}%][configure]] script and follow "Find More Extensions" in the in the __Extensions__ section.

   * Or, follow these __manual installation__ steps:
      * Download the ZIP file from the Plugins home (see below).
      * Unzip ==%TOPIC%.zip== in your twiki installation directory. Content:
        | *File:* | *Description:* |
        | ==data/TWiki/%TOPIC%.txt== | Plugin topic |
        | ==data/TWiki/%TOPIC%Test.txt== | Plugin test topic |
        | ==data/TWiki/VarVARCACHE.txt== | Variable documentation topic |
        | ==lib/TWiki/Plugins/%TOPIC%.pm== | Plugin Perl module |
        | ==pub/TWiki/%TOPIC%/cachetopic.gif== | Cache icon 16x16 |
      * Set the ownership of the extracted directories and files to the webserver user.
      * Make sure the dependencies listed in the table below are resolved.
        None

   * Plugin __configuration and testing__:
      * Run the [[%SCRIPTURL{configure}%][configure]] script, enable the plugin in the __Plugins__ section
      * Configure the plugin: See plugin settings above.
      * Test if the installation was successful:
         * Visit the %TOPIC%Test topic, it contains a nested search.
         * Click on the <u>refresh</u> link or append a =?varcache=refresh= parameter to the URL.

%ENDTWISTY%

---++ Plugin Info

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

%TABLE{ tablewidth="100%" columnwidths="170," }%
|  Plugin Author: | TWiki:Main.PeterThoeny |
|  Copyright: | &copy; 2013-2015 Wave Systems Corp. %BR% &copy; 2004-2018 Peter Thoeny, [[http://twiki.org/][TWiki.org]] %BR% &copy; 2008-2018 TWiki:TWiki.TWikiContributor |
|  Sponsor: | [[http://www.wave.com/][Wave Systems Corp.]] for VARCACHE_EXCLUDE_ variable prefix and cache invalidation logic |
|  License: | GPL ([[http://www.gnu.org/copyleft/gpl.html][GNU General Public License]]) |
|  Plugin Version: | 2018-07-08 |
%TWISTY{
 mode="div"
 showlink="Show Change History %ICONURL{toggleopen}%"
 hidelink="Hide Change History %ICONURL{toggleclose}% "
}%
%TABLE{ tablewidth="100%" columnwidths="170," }%
|  2018-07-08: | TWikibug:Item7841: Copyright update to 2018 |
|  2016-12-14: | TWikibug:Item7764: May cause an error on a subweb |
|  2016-01-14: | TWikibug:Item7708: Copyright update to 2016 |
|  2015-03-16: | TWikibug:Item7625: Invalidate parent topics on parent path up to indicated level |
|  2015-01-09: | TWikibug:Item7568: Document limitation of slow topic saves in very large webs; remove VARCACHE if found in an INCLUDE |
|  2014-02-22: | TWikibug:Item7438: Add cache invalidation logic for parents, backlinks and includes |
|  2013-12-29: | TWikibug:Item7396: Doc update on limitation of variable excludes |
|  2013-12-09: | TWikibug:Item7396: Cache topic also if topic parameter is used |
|  2013-12-04: | TWikibug:Item7396: VARCACHE_EXCLUDE_ variable prefix to disable caching of selected variables |
|  2012-11-14: | TWikibug:Item7020: Categorize TWiki Variable VARCACHE |
|  2012-09-07: | TWikibug:Item6837: Doc fixes |
|  2012-04-27: | TWikibug:Item6871: New =&lt;varcache_exclude&gt;= tag to exclude parts of page from getting cached |
|  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 %<nop>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 |
%ENDTWISTY%
%TABLE{ tablewidth="100%" columnwidths="170," }%
|  TWiki Dependency: | $TWiki::Plugins::VERSION 1.1 (TWiki 4.0, 2006-02-01) |
|  CPAN Dependencies: | none |
|  Other Dependencies: | none |
|  Perl Version: | 5.008 |
|  [[TWiki:Plugins.Benchmark][Benchmarks]]: | %SYSTEMWEB%.GoodStyle 99%, %SYSTEMWEB%.FormattedSearch 99%, %TOPIC%Test 208% |
|  Plugin Home: | http://TWiki.org/cgi-bin/view/Plugins/%TOPIC% |
|  Feedback: | http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Dev |
|  Appraisal: | http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Appraisal |

__Related Topics:__ VarVARCACHE, VarCachePluginTest, %SYSTEMWEB%.TWikiPlugins, %SYSTEMWEB%.DeveloperDocumentationCategory, %SYSTEMWEB%.AdminDocumentationCategory, %SYSTEMWEB%.TWikiPreferences
Topic revision: r1 - 2018-07-08 - TWikiContributor
Account
- Log In
~~Edit~~
~~Attach~~
Copyright &© 1999-2025 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback
Note: Please contribute updates to this topic on TWiki.org at TWiki:TWiki.VarCachePlugin.