NOTE: This is a SupplementalDocument topic which is not included with the official TWiki distribution. Please help maintain high quality documentation by fixing any errors or incomplete content. Put questions and suggestions concerning the documentation of this topic in the comments section below! Use the Support web for problems you are having using TWiki.

TWiki settings cookie

When user interface elements such as Twisty store their settings in persistent cookies, the limit of 20 cookies per domain is reached soon (see cookie specification).

This topic describes the method TWiki uses to overcome this limit, and how to read and write preference values in an easy and consistent way.

Reading and writing settings

To limit the number of cookies, (as of SVN 8797) TWiki reads and writes settings to one cookie named TWIKIPREF, to be shared amongst core and plugins.

pub/TWikiJavascripts/twiki.js has 2 functions to read and write TWiki settings cookies:

• setPref(inPrefName, inPrefValue) writes a preference value with name inPrefName and value inPrefValue
• getPref(inPrefName) reads a preference value with name inPrefName

Technically, all preferences written to TWIKIPREF are concatenated to one long string, each a key-value pair:

TWIKIPREF = |SHOWATTACHMENTS=1|SHOWFORM=1|somepref=somevalue

The cookie size limit is 4KB - for storing preference values this will suffice.

Usage

Writing a preference

<script type="text/javascript">
setPref('SHOWATTACHMENTS', '1');
</script>

If you write a cookie from a plugin or contrib javascript, add the plugin name:

<script type="text/javascript">
var prefName = "MyPlugin" + "MYSETTING";
var prefValue = "on";
setPref(prefName, prefValue);
</script>

Reading a preference

<script type="text/javascript">
var doShow = getPref("SHOWATTACHMENTS");
</script>

Related: TWiki's session cookie

TWiki's session management also uses a cookie (TWIKISID). This cookie identifies a unique session ID that is then used as the lookup key for all the other session-specific values TWiki uses.

An alternative approach would be to use a REST script on the server to serve this session-specific information on demand. This would allow one to escape the 4KB limit, but would inevitably be slower (and only available if sessions are active).

More info

Links:

• Wikipedia on cookies
• cookies.js - the original js source
• Netcape's cookie specification

-- Contributors: ArthurClemens, CrawfordCurrie

Comments & Questions about this Supplemental Document Topic

This topic should be linked to from a SupplementalDocument. Wondering if this supplemental doc fits into one of the high level topics listed in SupplementalDocument, or if a new top level is appropriate, or if linked from a sub level doc.

-- PeterThoeny - 14 Feb 2006