create new tag
, view all tags

Making TWiki variables consistent


A TWiki variable is a sequence of characters embedded in TWiki source text which, when seen by TWiki, may be expanded in the output into a different string.

The source of that string may be several:

  1. URL parameters
  2. Parameters to a %INCLUDE%
  3. Set/Local statements in various TWiki topics or templates
  4. Code in the TWiki core and contribs
  5. Code in plugins

Because the way TWiki evolved over time, there are a number of different ways of recovering TWiki variables, besides simply quoting them in text:

  • %URLPARAM% - recovers url parameters, and is able to establish defaults
  • %INCLUDE% - supports passing parameters into included topics, where they are expanded like normal TWiki variables
  • %QUERYSTRING% - lists the string used in the query used to view a page
  • %QUERYPARAMS% - formatted display of parameters to the query
  • %VAR% - bypass normal scoping mechanisms to get a type 3 value
While these mechanisms cover many of the cases where a TWiki variable value is to be recovered, there is little consistency and some glaring holes. For example, as highlighted in DocumentedDefaultParameterValuesForInclude, there is no way to establish a default for %INCLUDE parameters.

It is long overdue to simplify all this, and provide a single consistent mechanism for obtaining TWiki variable values and providing defaults.

There seem to me to be a number of requirements here:

  1. A set of simple scoping rules (INCLUDE param overrides SESSION overrides USER etc)
  2. Consistent mechanisms for referencing values in alternative scopes
  3. Maintain compatibility with existing content

Scoping rules

The preferences mechanism already maintains a stack that enforces scoping rules. The rules are:
  1. Code
  2. defaults in %SYSTEMWEB%.TWikiPreferences
  3. plugin topics
  4. local site level in %USERSWEB%.TWikiPreferences
  5. user level in individual user topics in %USERSWEB% web
  6. web level in WebPreferences of each web
  7. topic level in topics in webs
  8. session variables (if sessions are enabled)
  9. INCLUDE parameters


Generic syntax extension

User-defined TWiki Variables currently accept, but ignore, the parameters in {}. This fact can be used to extend TWiki Variable syntax to support parameters. For example %BURBLE{web="Nonsense" topic="GibberGibber" default="Mumble"}%

Out-of-scope Access

While simply citing the variable name %VARIABLE% can return the value according to the scoping rules above, we also need a way to short-circuit those scoping rules. At the moment, we use %VAR to achieve this. Following on from the lead so established, there would appear to be two requirements:
  1. Access variable value in another level in the scope stack. There is some doubt in my mind as to whether this is actually a requirement or not. If it is, then a parameter which changes the scope of the variable could be used: %BURBLE{scope="USER"}%. Scope names (such as USER, WEB, PLUGIN etc are already used to identify stack levels in the preferences code, so this extension is quite natural.
  2. Access variable value in an alternative stack. This is currently partially available using %VAR, which references a value in another web. The proposal is to replace %VAR with a simpler, more intuitive syntax, and deprecate %VAR. For example, %VAR{"BURBLE" web="Nonsense"}% would be replaced with %BURBLE{web="Nonsense"}%. An additional topic parameter would support access to topic variables %BURBLE{web="Nonsense" topic="GibberGibber"}%

Provision of defaults

At the moment if a TWiki variable is used without having a value, then it is not expanded, i.e. %BURBLE% appears %BURBLE% in output if BURBLE is not defined. It is frequently desireable to change this behaviour to expand the undefined variable to a default value. The only way to do this at present is using an %IF statement, for example %IF{"$BURBLE" then="%BURBLE%" else="burble"}% which is very clumsy. A much neater syntax would use a parameter to the variable: %BURBLE{default="burble"}%


A simple extension to TWiki variable syntax could be used to provide alternate scope and defaults instructions, and allow deprecation of clumsy %VAR and %IF syntaxes.

-- Contributors: CrawfordCurrie - 16 Nov 2006

See also DocumentedDefaultParameterValuesForInclude, ContentAccessSyntax for related discussions.


I want to raise this proposal again, so I've refactored the discussion into the proposal. Please check http://twiki.org/cgi-bin/view/Codev/CanonicalTWikiVariables?rev=12 for the background discussion. Some of that discussion is related to the setting of variable values in included topics; please don't discuss that here, this topic is about reading values, not about setting them.

While the original proposal included extension of the namespace to URL paramaters, there have been concerns raised (PeterThoeny, HaraldJoerg) about namespace pollution. Another related issue is the potential for using such URL parameters to launch XSS attacks, so however logical it may be, we cannot simply include URL parameters in the stack.

-- CrawfordCurrie - 01 Feb 2008

What place in the stack do variables set in spec files have?

-- ArthurClemens - 01 Feb 2008

Just to clarify. The current VAR implementation only works for variables defined in WebPreferences. AddTopicAttributeToVAR was raised but never committed or implemented. So there is no easy way to read the value of a variable from another topic.

Naturally I support this proposal but I guess that would also mean death to the AddTopicAttributeToVAR proposal.

-- KennethLavrsen - 01 Feb 2008

@Arthur: not sure what you mean. You can't define TWiki Variables in spec files.

@Kenneth: correct

-- CrawfordCurrie - 02 Feb 2008

I am confusing plugin variables. Probably because "plugin topics" is number 3 in the list.

-- ArthurClemens - 02 Feb 2008

It would be useful to consider adding contexts and spec values to this API too - so that all TWiki accessible settings can be accessed in the same way.

It can be suggested that FormField values are also a form of setting.... smile

-- SvenDowideit - 05 Feb 2008

Edit | Attach | Watch | Print version | History: r18 < r17 < r16 < r15 < r14 | Backlinks | Raw View | Raw edit | More topic actions
Topic revision: r18 - 2008-02-05 - SvenDowideit
  • Learn about TWiki  
  • Download TWiki
This site is powered by the TWiki collaboration platform Powered by Perl Hosted by OICcam.com Ideas, requests, problems regarding TWiki? Send feedback. Ask community in the support forum.
Copyright © 1999-2017 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.