%META:TOPICINFO{author="JensRoeder" date="1150053426" format="1.0" version="1.7"}%
---+ Cache Chooser Add-On

	* creates cache from Topics and decides, if a Topic needs to be rerendered. TWiki users can have an influence on the caching time. !CacheChooserAddOn takes account to TWikis content security.

---++ Usage
	* After installation invisible for TWiki users.
	* Users may need to use a refresh button to rerender a Topic with content genereated by variables.
	* Users may set the NOCACHE variable to refuse caching of topics with no static content.
	* User can set the _timeout_ of a page to be automatically be rerendered after time T or request a page with calender rerendered once a day.

---++ How does it work
	* The chooser decides by the following facts, when to render a Topic to cache:
		* date of original Topic file is newer than file in cache
		* in Topic =DENYTOPICVIEW= or =ALLOWTOPICVIEW= are empty
		* in =WebPreferences= of a web, =DENYWEBVIEW= and =ALLOWWEBVIEW= are empty.
		* the =NOCACHE= variable is NOT set, neither in the Topic nor in =WebPreferences=
		* the =CACHE= variable is set with a value.
		* No QUERY_STRING options are specified, excepting =?skin=plain=

---++ Advantages - Disadvantages - When better not using caching
	* Caching is ideal for static content
	* In all other Topics and Webs which contain content that is generated by variables from actual TWiki content and require to be most actuell, caching shoud be disabled by setting the NOCACHE variable or at least set a short refresh-time with the CACHE  variable.
	* Caching cannot and is not supported when User Authentication is used by restricting viewing Topics or Webs.
	* Caching is not supported, when QUERY_STRING options are specified to avoid conficts.

---++ Speed Advantages
 | *Time* | *Experiment* |
 |  40 ms | cached Topic with no CACHE variable in |
 |  76 ms | cached Topic with CACHE variable in |
 |||
 |||
 |  3358 ms | rerended Topic with cache chooser |
 |  3276 ms | directly rendered Topic without cache chooser |
 |||
 |  82 ms | overhead through cache chooser programm |

The measurement was done on a 700 MHz PC. In fact the little overhead of about 80 ms when rendering via the cache chooser does really not take much into account of the over 3 seconds rendering time, while the speed of Topics from cache is relatively really fast, especially for Topics which need not processed for variables again. 


---++ Stop Caching of a Topic or Web
	* For a Topic:
		* include the exact string: =Set NOCACHE= somewhere in the document.
		* You may hide it by =&lt;!-- Set NOCACHE --&gt;=
	* For a entire Web:
		* include the exact string: =Set NOCACHE= in the =WebPreferences= of that web.

---++ Forcing Caching of a Topic in a Non-Cached Web
	* Include in the Topic:
		* =Set CACHE = cache=
That overwrites the NOCACHE variable in the Web, but will not overwrite User Authentication.

---++ Cache Timeout of Topics
	* To define in =WebPrefrerences= in each Web
	* To define in each Topic
	* Order is: Topic beats Web

If the CACHE variable has a time information included instead of the word =cache=, it will rerender the Topic after timeout is reached. The format includes one string after the equal sign that has to be separated by one space on each sides! The format includes m=minutes, h=hours, d=days, w=weeks and M=months. Several time settings can be set together and are separated by " =-= " to build up one string! The letters follow directly after the number of time. Examples:

	* Set CACHE = 1d
	* Set CACHE = 5d-2w
	* Set CACHE = 1h-30m
	* Set CACHE = 1M-2w-5d-6h-3m

There are limitations in specifiable numbers:
	* m = 1-59
	* h = 1-29
	* d = 1-6
	* w = 1-9
	* M = 1-19

Especially for the CalendarPlugin the option =daily= will cause the Topic rerendered for the actual day to display the calendar properly, so set:
	* Set CACHE = daily

Refreshing via QUERY_STRING is now also supported:
	* =?refresh=daily-cachetime=  for once a day
	* =?refresh=12h-cachetime=  every 12 hours
	* =?refresh=2d-12h-cachetime=  every 2 and a half days
	* =?refresh=1M-cachetime=  once a month
Please take attention to *close* the time setting with *-cachetime*.

Refresh cache:
	* =?refresh=cache=

Use no cache:
	* =?cache=none=

---++ Setting up Rss Feeds Cache
Since this version, caching rss feeds is also supported, but *requires* setting up a cache time or they will not actualize. You can choose between two places:
	* *Each WEBs !WebRss Topic*: Simply define with the =Set CACHE= variable the time, after the feeds should  be recreated, e.g.:
	* =&lt;!-- Set CACHE = daily --&gt;=  for once in a day
	* =&lt;!-- Set CACHE = 4h --&gt;=  after 4 hours
	* =&lt;!-- Set NOCACE --&gt;= no caching at all
	* *TWiki wide in TWikis !TWikiPreferences*: Define a default for all WEBs. Look for HTTP_EQUIV_ON_VIEW and point your attention to the end with the =&refresh=daily-cachetime=, you could also set =&refresh=3h-cachetime= for a 3 hours refresh or =&refresh=cache= with no caching

		* =Set HTTP_EQUIV_ON_VIEW =  &lt;link rel="alternate" type="application/rss+xml" title="RSS Feed" href="%<nop>SCRIPTURL%/view%<nop>SCRIPTSUFFIX%/%<nop>WEB%/<nop>WebRss?skin=rss&amp;contenttype=text/xml&refresh=daily-cachetime" /&gt;=


---++ User Authentication
	* Due to security reasons, caching is disabled, when User Authentication is used in a Web or Topic.
	* When in a Topic =Set ALLOWTOPICVIEW = Main. ...= or =Set DENYTOPICVIEW = Main. ...= is set or
	* when in the the =WebPreferences= of a web =Set ALLOWWEBVIEW = Main. ...= or =Set DENYWEBVIEW = Main. ...= is set, followed by a user or group, caching is disabled. If activated later, the copy in the cache will be removed.
	* *Attention!* %T%: _Be aware to keep the exact syntax as above! There has to be exact one space before and after the equal sign, otherwise_ __Security may fail!__
		* Wrong would be =Set ALLOWTOPICVIEW =Main.TWikiGuest=
		* Correct is: =Set ALLOWTOPICVIEW = !Main.TWikiGuest=

---++ Add-On Installation Instructions

__Note:__ You do not need to install anything on the browser to use this add-on. The following instructions are for the administrator who installs the add-on on the server where TWiki is running. 

	* Download ==%TOPIC%.zip== ZIP file from TWiki:Plugins.%TOPIC%
	* Unzip ==%TOPIC%.zip== in your twiki installation directory. Content:
	  | *File:* | *Description:* |
	  | ==data/TWiki/%TOPIC%.txt== | Add-on topic |
	  | ==data/TWiki/%TOPIC%.txt,v== | Add-on topic repository |
	  | ==bin/cache== | Add-on script |
	  | ==bin/render== | original view script |
	  | ==bin/view== | link to cache |
	  | ==bin/refresh== | link to cache |
	  | ==cache/.htcacherr.log== | log file of wrong CACHE variable entries |
	* Installationsteps:
		* copy cache to TWiki bin/
		* mv view to render
		* ln -s cache view
		* ln -s cache refresh
		* mkdir cache in TWiki directory, if web-server has no writing permissions there.
		* Add in your TWiki-skin a refresh button, e.g.: 
		* Change =/your/twiki/template/view.tmpl= to have a refresh function,
			 e.g. next to the the "More" link:<br>
			 =%<nop>TMPL:P{"sep"}% &lt;a href="%<nop>SCRIPTURLPATH%/refresh%<nop>SCRIPTSUFFIX%/%<nop>WEB%/%<nop>TOPIC%">Refresh&lt;/a>=
		* *Update* %T%: =302 Moved= messages cause wrong =Localisation= redirect, when view script is called with different name. Workaround is to use the =?refresh=cache= option instead of the link =refresh= for the refresh button, e.g.: =%<nop>TMPL:P{"sep"}% &lt;a href="%<nop>SCRIPTURLPATH%/view%<nop>SCRIPTSUFFIX%/%<nop>WEB%/%<nop>TOPIC%?refresh=cache">Refresh&lt;/a>=

	* Test if the installation was successful:
		* open Topics in your TWiki web and check, if directory tree and Topic-cache pages are created in the cache directory.
	* Protect cache dir in httpd.conf or with .htaccess by =deny from all=

---++ Add-On Info

|  Add-on Author: | TWiki:Main/JensRoeder |
|  Add-on Version: | 30 Mar 2005 (v1.000) |
|  Change History: | <!-- versions below in reverse order -->&nbsp; |
|  30 Mar 2005: | Initial version |
|  CPAN Dependencies: | none |
|  Other Dependencies: | none |
|  Perl Version: | 5.005 |
|  License: | GPL |
|  Add-on 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 Topic:__ %TWIKIWEB%.TWikiAddOns

-- TWiki:Main/JensRoeder - 30 Mar 2005

	* [[%ATTACHURL%/CacheChooserAddOn.zip][CacheChooserAddOn.zip]]: Version 2006-06-10

