The Caboteria / TWiki Web / TWikiVariables (27 Mar 2011, TWikiContributor)

TWiki Variables

Special text strings expand on the fly to display 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
  2. Predefined variables: Defined by the TWiki system or by plugins (for example, the SpreadSheetPlugin introduces a %CALC{}% variable)

On this page:

Using Variables

To use a variable type its name. For example,

Note:

Variable Names

Variable names must start with a letter. The following characters can be letters, numbers and the underscore '_'. You can use both upper-case and lower-case letters and you can mix the characteres. E.g. %MYVAR%, %MyVar%, %My2ndVar%, and %My_Var% are all valid variable names. Variables are case sensitive. %MyVAR% and %MYVAR% are not the same variable.

By convention all settings, predefined variables and variables used by plugins 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. topic level in topics in webs
  7. session variables (if sessions are enabled)

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.

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%,
                %PARAM1% and %PARAM2%

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% dish is %DISH%,
                    my %DEFAULT% 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 predefined variables

List of all predefined variables

This TWiki: - TWiki-5.1.4, Sat, 16 Feb 2013, build 25114

ACTIVATEDPLUGINS -- list of currently activated plugins

ADDTOHEAD -- add HTML to the HTML head section of the current page

ALLVARIABLES -- list of currently defined TWikiVariables

AQUA -- start aqua colored text

ATTACHURL -- full URL for attachments in the current topic

ATTACHURLPATH -- path of the attachment URL of the current topic

AUTHREALM -- authentication realm

BASETOPIC -- base topic where an INCLUDE started

BASEWEB -- base web where an INCLUDE started

BB -- bullet with line break

BB2 -- level 2 bullet with line break

BB3 -- level 3 bullet with line break

BB4 -- level 4 bullet with line break

BLACK -- start black colored text

BLUE -- start blue colored text

BR -- line break

BROWN -- start brown colored text

BULLET -- bullet sign

CALC{"formula"} -- add spreadsheet calculations to tables

CALCULATE{"formula"} -- handle spreadsheet calculations outside tables

CARET -- caret symbol

COLORPICKER{} -- color picker for use in HTML forms for TWiki applications

COMMENT{ attributes } -- insert an edit box into the topic to easily add comments.

DATE -- signature format date

DISPLAYTIME -- display date and time

DISPLAYTIME{"format"} -- formatted display time

EDITACTION -- Selects an edit template

EDITTABLE{ attributes } -- edit TWiki tables using edit fields and other input fields

ENCODE{"string"} -- encodes a string to HTML entities

ENDBG -- end background color section

ENDCOLOR -- end colored text

ENDSECTION{"name"} -- marks the end of a named section within a topic

ENV{"varname"} -- inspect the value of an environment variable

EXAMPLEVAR -- example variable

FAILEDPLUGINS -- debugging for plugins that failed to load, and handler list

FORMFIELD{"fieldname"} -- renders a field in the form attached to some topic

GET{"name"} -- get a variable

GMTIME -- GM time

GMTIME{"format"} -- formatted GM time

GRAY -- start gray colored text

GREEN -- start green colored text

GROUPS -- a formatted list of groups

H -- help icon

HEADLINES{"url"} -- show RSS and ATOM feeds in TWiki pages

HIDE -- hide content in topic view

HOMETOPIC -- home topic in each web

HTTP -- get HTTP headers

HTTP_HOST -- environment variable

HTTPS -- get HTTPS headers

I -- idea icon

ICON{"name"} -- small documentation graphic or icon of common attachment types

ICONURL{"name"} -- URL of small documentation graphic or icon

ICONURLPATH{"name"} -- URL path of small documentation graphic or icon

IF{"condition" ...} -- simple conditionals

INCLUDE{"page"} -- include other topic or web page

INCLUDINGTOPIC -- name of topic that includes current topic

INCLUDINGWEB -- web that includes current topic

JQENDTAB -- end a JQuery tab within a tab pane

JQENDTABPANE -- end a JQuery tab pane

JQTAB -- start a JQuery tab within a tab pane

JQTABPANE -- start a JQuery tab pane

LANGUAGE -- current user's language

LANGUAGES -- list available TWiki languages

LIME -- start lime colored text

LOCALSITEPREFS -- web.topicname of site preferences topic

LOGIN -- present a full login link to non-authenticated user

LOGINURL -- present a login link

LOGOUT -- present a full logout link to authenticated user

LOGOUTURL -- present a logout link

M -- moved to... icon

MAINWEB -- synonym for USERSWEB

MAKETEXT -- creates text using TWiki's I18N infrastructure

MAROON -- start maroon colored text

META -- displays meta-data

METASEARCH -- special search of meta data

N -- "new" icon

NAVY -- start navy blue colored text

NOP -- template text not to be expanded in instantiated topics

NOTIFYTOPIC -- name of the notify topic

OLIVE -- start olive green colored text

ORANGE -- start orange colored text

P -- pencil icon

PARENTTOPIC -- parent of current topic

PINK -- start pink colored text

PLUGINDESCRIPTIONS -- list of plugin descriptions

PLUGINVERSION -- the version of a TWiki Plugin, or the TWiki Plugins API

PUBURL -- the base URL of attachments

PUBURLPATH -- the base URL path of attachments

PURPLE -- start purple colored text

Q -- question icon

QUERYPARAMS -- show paramaters to the query

QUERYSTRING -- full, unprocessed string of parameters to this URL

RED -- start red colored text

REDBG -- start red colored background section

REMOTE_ADDR -- environment variable

REMOTE_PORT -- environment variable

REMOTE_USER -- environment variable

RENDERLIST -- render bullet lists in a variety of formats

REVINFO -- revision information of current topic

REVINFO{"format"} -- formatted revision information of topic

S -- red star icon

SCRIPTNAME -- name of current script

SCRIPTSUFFIX -- script suffix

SCRIPTURL -- base URL of TWiki scripts

SCRIPTURL{"script"} -- URL of TWiki script

SCRIPTURLPATH -- base URL path of TWiki scripts

SCRIPTURLPATH{"script"} -- URL path of TWiki script

SEARCH{"text"} -- search content

SERVERTIME -- server time

SERVERTIME{"format"} -- formatted server time

SESSIONID -- unique ID for this session

SESSIONVAR -- name of CGI and session variable that stores the session ID

SESSION_VARIABLE -- get, set or clear a session variable

SET{"name" value="..."} -- set a variable

SETGETDUMP{...} -- dump persistent variables

SILVER -- start silver colored text

SLIDESHOWEND -- end slideshow

SLIDESHOWSTART -- convert a topic with headings into a slideshow

SPACEDTOPIC -- topic name, spaced and URL-encoded deprecated

SPACEOUT{"string"} -- renders string with spaces inserted in sensible places

STARTINCLUDE -- start position of topic text if included

STARTSECTION -- marks the start of a section within a topic

STATISTICSTOPIC -- name of statistics topic

STOPINCLUDE -- end position of topic text if included

SYSTEMWEB -- name of TWiki documentation web

T -- tip icon

TABLE{ attributes } -- control attributes of tables and sorting of table columns

TEAL -- start teal colored text

TOC -- table of contents of current topic

TOC{"Topic"} -- table of contents

TOPIC -- name of current topic

TOPICLIST{"format"} -- topic index of a web

TOPICURL -- shortcut to viewing the current topic

TWIKIWEB -- synonym for SYSTEMWEB

TWISTY{ attributes } -- dynamically open and close sections of content

U -- "updated" icon

URLPARAM{"name"} -- get value of a URL parameter

USERINFO{"name"} -- retrieve details about a user

USERNAME -- your login username

USERSWEB -- name of users web

VAR{"NAME" web="Web"} -- get a preference value from another web

VBAR -- vertical bar

WEB -- name of current web

WEBLIST{"format"} -- index of all webs

WEBPREFSTOPIC -- name of web preferences topic

WHITE -- start white colored text

WIKIHOMEURL -- site home URL

WIKILOGOALT -- site logo tooltip message

WIKILOGOIMG -- site logo image URL

WIKILOGOURL -- site logo home URL

WIKINAME -- your Wiki username

WIKIPREFSTOPIC -- name of site-wide preferences topic

WIKITOOLNAME -- name of your TWiki site

WIKIUSERNAME -- your Wiki username with web prefix

WIKIUSERSTOPIC -- name of topic listing all registers users

WIKIVERSION -- the version of the installed TWiki engine

X -- warning icon

Y -- "yes" icon

YELLOW -- start yellow colored text

Related Topics: UserDocumentationCategory, TWikiVariablesSearch, TWikiVariablesQuickStart, ParameterizedVariables

Edit | Attach | Print version | History: r87 < r86 < r85 < r84 < r83 | Backlinks | Raw View | Raw edit | More topic actions
Copyright © 1999-2024 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding The Caboteria? Send feedback
Note: Please contribute updates to this topic on TWiki.org at TWiki:TWiki.TWikiVariables.