Home | Gifts
Contents:

TWiki Variables

Special text strings expand on the fly to display dynamic content, such as user data or system info

TWikiVariables are text strings - %VARIABLE% or %VARIABLE{ parameter="value" }% - that expand into content whenever a topic is rendered for viewing. There are two types of variables:

  1. Preferences variables: Can be defined and changed by the user.
    Example: %T% renders as TIP
  2. Predefined variables: Defined by the TWiki system or by extensions.
    Example: %CALCULATE{}% is handled by the SpreadSheetPlugin

See list of all TWiki Variables currently defined in this TWiki installation.

TWiki Variables Wizard — to Find and Compose Variables

Categories:
Arrow right
Variables:
Arrow down

Select a category and a variable
Arrow down
Build Your Variable:
Pre-load image: processing-bar-wide.gif

Using Variables

To use a variable type its name. For example,

Note:

Variable Names

Variable names must start with a letter, optionally followed by letters, numbers and underscore '_' characters. Both upper-case and lower-case characters can be used, %MYVAR%, %MyVar%, %My2ndVar%, and %My_Var% are valid names. Variables are case sensitive, e.g. %MyVAR% and %MYVAR% are not the same.

By convention all settings, predefined variables and variables handled by extensions are always UPPER-CASE.

Preferences Variables

Unlike predefined variables, preferences variables can be defined by the user in various places.

Setting Preferences Variables

You can set variables in all the following places:

  1. system level in TWiki.TWikiPreferences
  2. plugin topics (see TWikiPlugins)
  3. local site level in Main.TWikiPreferences
  4. user level in individual user topics in Main web
  5. web level in WebPreferences of each web
  6. If EXTRAPREFERENCES is defined at this point, it's regarded as having comma separated list of topics. Those topics are read in the listed order as if they were WebPreferences
  7. topic level in topics in webs
  8. session variables (if sessions are enabled)
  9. user level preferences are set at this point if $TWiki::cfg{DemoteUserPreferences} is true as mentioned at the step 4

Settings at higher-numbered levels override settings of the same variable at lower numbered levels, unless the variable was included in the setting of FINALPREFERENCES at a lower-numbered level, in which case it is locked at the value it has at that level.

If you are setting a variable and using it in the same topic, note that TWiki reads all the variable settings from the saved version of the topic before it displays anything. This means you can use a variable anywhere in the topic, even if you set it somewhere inconspicuous near the end. But beware: it also means that if you change the setting of a variable you are using in the same topic, preview will show the wrong thing, and you must save the topic to see it correctly.

The syntax for setting variables is the same anywhere in TWiki (on its own TWiki bullet line, including nested bullets):
[multiple of 3 spaces] * [space] Set [space] VARIABLENAME [space] = [space] value

Examples: 

   * Set VARIABLENAME1 = value
      * Set VARIABLENAME2 = value

Spaces between the = sign and the value will be ignored. You can split a value over several lines by indenting following lines with spaces - as long as you don't try to use * as the first character on the following line.

Example: 

   * Set VARIABLENAME = value starts here
     and continues here

Whatever you include in your variable will be expanded on display, exactly as if it had been entered directly.

Example: Create a custom logo variable 

      * Set MYLOGO = %PUBURL%/%WEB%/LogoTopic/mylogo.gif

You can also set preferences variables on a topic by clicking the link Edit topic preference settings under More topic actions. Use the same * Set VARIABLENAME = value syntax. Preferences set in this manner are not visible in the topic text, but take effect nevertheless.

Controlling User Level Preferences Override

By default, user level variables are set at the step 4 as stated in the previous section. That means a user can finalise some preferences variables so that web level or topic level setting cannot override it. This may result in a situation the web or page owner doesn't expect. $TWiki::cfg{DemoteUserPreferences} has been introduced to avoid it. If it's set to true, user level variables are set at the last step instead of the step 4.

But this is not enough. To guarantee a certain result, you need to finalise critical preferences variables set at the web or topic level, which is cumbersome. So preferences variables DENYUSERPREFEENCES and ALLOWUSERPREFERENCES have been introduced.

For example, if you don't allow overriding at the user level at all: 
   * Set DENYUSERPREFERENCES = all
If you allow INYMCEPLUGIN_DISABLE and SKIN to be set at the user level: 
   * Set ALLOWUSERPREFERENCES = TINYMCEPLUGIN_DISABLE, SKIN
If you allow user preferences to set anything other than TINYMCEPLUGIN_DISABLE or SKIN: 
   * Set DENYUSERPREFERENCES = TINYMCEPLUGIN_DISABLE, SKIN
Please note DENYUSERPREFEENCES and ALLOWUSERPREFERENCES affect user preferences regardless of $TWiki::cfg{DemoteUserPreferences}. You can set those variables at the site level while $TWiki::cfg{DemoteUserPreferences} setting to false. If you do so, you should finalise DENYUSERPREFEENCES and ALLOWUSERPREFERENCES. Otherwise, they might be overridden by user preferences.

You will get the most benefit of DENYUSERPREFEENCES and ALLOWUSERPREFERENCES by setting $TWiki::cfg{DemoteUserPreferences} to true. That way, each web can specify how much user level preferences overriding is allowed.

Parameterized Variables (Macros)

It is possible to pass parameters to TWiki variables. This is called a macro in a programming language.

To define a parameterized variable, set a variable that contains other variables, such as: 

   * Set EXAMPLE = Example variable using %DEFAULT%, %PARAM1% and %PARAM2%
   * Set DEMO = Demo using %DEFAULT{ default="(undefined)" }%,
                %PARAM1{ default="(undefined)" }% and %PARAM2{ default="(undefined)" }%

A special %DEFAULT% variable denotes the default (nameless) parameter of the calling variable. Variables optionally may list a default="..." parameter that gets used in case the calling variable does not specify that parameter.

To use a parameterized variable (or call a macro), add parameters within the curly brackets, such as: 

   * %EXAMPLE{ "foo" PARAM1="bar" PARAM2="baz" }%
   * %DEMO{ "demo" PARAM2="parameter 2" }% -- note that PARAM1 is missing
which resolves to:

Parameters in the variable definition are expanded using the following sequence:

  1. Parameter from variable call. In above example, %PARAM1% gets expanded to bar.
  2. Session variable and preferences settings

Example

Define variables: 

   * Set DRINK = red wine
   * Set FAVORITE = My %DEFAULT{default="favorite"}% dish is %DISH{default="steak"}%,
                    my %DEFAULT{default="favorite"}% drink is %DRINK%.
TIP The default can be defined with a default parameter (%DISH{default="steak"}%), or as a preferences setting (Set DRINK = ...).

Use Variables: 

%FAVORITE{ DISH="Sushi" DRINK="Sake" }%
Returns:
My favorite dish is Sushi, my favorite drink is Sake. 

%FAVORITE{}%
Returns:
My favorite dish is steak, my favorite drink is red wine. 

%FAVORITE{ "preferred" }%
Returns:
My preferred dish is steak, my preferred drink is red wine.

Access Control Variables

These are special types of preferences variables to control access to content. TWikiAccessControl explains these security settings in detail.

Local values for variables

Certain topics (a users home topic, web site and default preferences topics) have a problem; variables defined in those topics can have two meanings. For example, consider a user topic. A user may want to use a double-height edit box when they are editing their home topic - but only when editing their home topic. The rest of the time, they want to have a normal edit box. This separation is achieved using Local in place of Set in the variable definition. For example, if the user sets the following in their home topic: 

   * Set EDITBOXHEIGHT = 10
   * Local EDITBOXHEIGHT = 20
Then when they are editing any other topic, they will get a 10 high edit box. However when they are editing their home topic, they will get a 20 high edit box. Local can be used wherever a preference needs to take a different value depending on where the current operation is being performed.

Use this powerful feature with great care! %ALLVARIABLES% can be used to get a listing of the values of all variables in their evaluation order, so you can see variable scope if you get confused.

Frequently Used Preferences Variables

The following preferences variables are frequently used. They are defined in TWikiPreferences#Miscellaneous_Settings:

There are additional useful preferences variables defined in TWikiPreferences, in Main.TWikiPreferences, and in WebPreferences of every web.

Predefined Variables

Most predefined variables return values that were either set in the configuration when TWiki was installed, or taken from server info (such as current username, or date and time). Some, like %SEARCH%, are powerful and general tools.

Search or List Variables by Category

   Show all

Category

All TWiki Variables: ACTIVATEDPLUGINS, ADDTOHEAD, ALLVARIABLES, AQUA, ATTACHURL, ATTACHURLPATH, AUTHREALM, BASETOPIC, BASEWEB, BB, BB2, BB3, BB4, BLACK, BLUE, BR, BROWN, BUBBLESIG, BULLET, CALC, CALCULATE, CARET, CHILDREN, COLORPICKER, COMMENT, CONTENTMODE, COPY, DASHBOARD, DATE, DATEPICKER, DISPLAYTIME, DISPLAYTIME2, EDITACTION, EDITFORM, EDITFORMFIELD, EDITTABLE, ENCODE, ENDBG, ENDCOLOR, ENDCOLUMNS, ENDSECTION, ENTITY, ENV, EXAMPLEVAR, FAILEDPLUGINS, FORM, FORMFIELD, FOURCOLUMNS, GET, GMTIME, GMTIME2, GRAY, GREEN, GROUPS, H, HEADLINES, HIDE, HIDEINPRINT, HOMETOPIC, HTTP, HTTPHOST, HTTPS, I, ICON, ICONURL, ICONURLPATH, IF, INCLUDE, INCLUDINGTOPIC, INCLUDINGWEB, JQENDTAB, JQENDTABPANE, JQTAB, JQTABPANE, LANGUAGE, LANGUAGES, LAQUO, LIME, LOCALSITEPREFS, LOGIN, LOGINURL, LOGOUT, LOGOUTURL, M, MAINWEB, MAKETEXT, MAROON, MDREPO, META, METASEARCH, N, NAVY, NBSP, NOP, NOTIFYTOPIC, OLIVE, ORANGE, P, PARENTBC, PARENTTOPIC, PINK, PLUGINDESCRIPTIONS, PLUGINVERSION, PUBURL, PUBURLPATH, PURPLE, Q, QUERYPARAMS, QUERYSTRING, RAQUO, RED, REDBG, REG, REMOTEADDR, REMOTEPORT, REMOTEUSER, RENDERLIST, REVINFO, REVINFO2, S, SCRIPTNAME, SCRIPTSUFFIX, SCRIPTURL, SCRIPTURL2, SCRIPTURLPATH, SCRIPTURLPATH2, SEARCH, SERVERTIME, SERVERTIME2, SESSIONID, SESSIONVAR, SESSIONVARIABLE, SET, SETGETDUMP, SILVER, SITENAME, SITESTATISTICSTOPIC, SLIDESHOWEND, SLIDESHOWSTART, SPACEDTOPIC, SPACEOUT, STARTINCLUDE, STARTSECTION, STATISTICSTOPIC, STOPINCLUDE, SYSTEMWEB, T, TABLE, TEAL, THREECOLUMNS, TM, TOC, TOC2, TOPIC, TOPICLIST, TOPICTITLE, TOPICURL, TWIKISHEET, TWIKIWEB, TWISTY, TWOCOLUMNS, U, URLPARAM, USERINFO, USERNAME, USERREPORT, USERSIG, USERSWEB, VAR, VBAR, WEB, WEBLIST, WEBPREFSTOPIC, WHITE, WIKIHOMEURL, WIKILOGOALT, WIKILOGOIMG, WIKILOGOURL, WIKINAME, WIKIPREFSTOPIC, WIKITOOLNAME, WIKIUSERNAME, WIKIUSERSTOPIC, WIKIVERSION, WIKIWEBMASTER, WIKIWEBMASTERNAME, WIP, X, Y, YELLOW, total 190 variables

Documenting TWiki Variables

This section is for people documenting TWiki variables of the TWiki core and TWiki extensions.

Each variable is documented in a topic named Var<name> in the TWiki web. For example, a %LIGHTSABER% variable has a documentation topic called VarLIGHTSABER. The topic is expected to have a specific format so that reports in this TWikiVariables topic, in TWikiVariablesSearch and in category topics work as expected.

Basic structure of a variable documentation topic:

Example content of a VarLIGHTSABER topic: 

#VarLIGHTSABER
---+++ LIGHTSABER -- laser sword to fend of unethical competition
   * The =%<nop>LIGHTSABER{}%= variable is handled by the LightsaberPlugin.
   * Syntax: =%<nop>LIGHTSABER{ _parameters_ }%=
   * Parameters:
     | *Parameter* | *Description* | *Default* |
     | =color="..."= | Color: =red=, =glue=, =green= | =white= |
     | =sound="..."= | Sound: =none=, =standard=, =loud= | =none= |
   * Example: =%<nop>LIGHTSABER{ color="red" }%= shows a red Lightsaber
   * Expands to: =%LIGHTSABER{ color="red" }%=
   * Note: The Lightsaber is a fictional weapon in the Star Wars universe, a "laser sword."
   * Category: FormattingAndRenderingVariables, UIAndVisualizationVariables
   * Related: [[%IF{"'%INCLUDINGTOPIC%'='TWikiVariables'" then="#"}%VarPLASMA][PLASMA]], LightsaberPlugin

Related Topics: UserDocumentationCategory, TWikiVariablesWizard, TWikiVariablesSearch, TWikiVariablesQuickStart, ParameterizedVariables

Revision r91 - 2016-07-11 - 06:26:28 - TWikiContributor Edit