Tags:
dev_essential1Add my vote for this tag structured_wiki1Add my vote for this tag twiki_application1Add my vote for this tag create new tag
, view all tags
Get Involved!
TWiki is an open source project with 10+ years of history, built by a team of volunteers from around the world, and used by millions of people in over 100 countries. The community is focusing on building the best collaboration platform for the workplace. We invite you to get involved!

ALERT! NOTE: This is a DistributionDocument. Please help maintain high quality documentation: This is a wiki, please fix the documentation if you find 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 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

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,

  • type %T% to get TIP (a preferences variable)
  • type %TOPIC% to get TWikiVariables (a predefined variable)
  • type %CALCULATE{ "$UPPER(Text)" }% to get TEXT (a variable defined by a plugin)

Note:

  • To leave a variable unexpanded, precede it with an exclamation point, e.g. type !%TOPIC% to get %TOPIC%
  • Variables are expanded relative to the topic they are used in, not the topic they are defined in
  • Type %ALLVARIABLES% to get a full listing of all variables defined for a particular topic

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 TWiki06x00.TWikiPreferences
  2. plugin topics (see TWikiPlugins)
  3. local site level in Main.TWikiPreferences
  4. user level in individual user topics in Main web
    • If UserSubwebs is in effect, the topic specified by %USERPREFSTOPIC% in the user's subweb is read instead
    • If $TWiki::cfg{DemoteUserPreferences} is true, this step is deferred to a later step. On this TWiki installation, $TWiki::cfg{DemoteUserPreferences} is false
  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

  • To place a logo anywhere in a web by typing %MYLOGO%, define the Variable on the web's WebPreferences topic, and upload a logo file, ex: mylogo.gif. You can upload by attaching the file to WebPreferences, or, to avoid clutter, to any other topic in the same web, e.g. LogoTopic. Sample variable setting in WebPreferences:
      * 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 ALLOWUSERPREFEENCES have been introduced.

  • DENYUSERPREFEENCES and ALLOWUSERPREFEENCES may have comma separated list of variable names
  • If a preferences variable is listed in DENYUSERPREFEENCES, the variable cannot be overridden at the user level. There is a special value "all", which means no preferences variables can be overridden at the user level
  • If ALLOWUSERPREFEENCES is set and not empty, only the listed preferences variables can be overridden. There is a special value "all", which means any preferences variable can be overridden at the user level. But actually, "all" is not necessary since a blank value or not setting ALLOWUSERPREFEENCES has the same effect
  • DENYUSERPREFEENCES takes precedence over ALLOWUSERPREFEENCES. If a variable is listed on both, it cannot be overridden. If DENYUSERPREFEENCES is "all", the value of ALLOWUSERPREFEENCES doesn't matter.
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 ALLOWUSERPREFEENCES 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 ALLOWUSERPREFEENCES. Otherwise, they might be overridden by user preferences.

You will get the most benefit of DENYUSERPREFEENCES and ALLOWUSERPREFEENCES 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:
  • Example variable using foo, bar and baz
  • Demo using demo, (undefined) and parameter 2 -- note that PARAM1 is missing

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:

  • %BB% - line break and bullet combined
  • %BB2% - level 2 bullet with line break
  • %BB3% - level 3 bullet with line break
  • %BB4% - level 4 bullet with line break
  • %BR% - line break
  • %BULLET% - bullet sign
  • %CARET% - caret symbol
  • %VBAR% - vertical bar
  • %H% - HELP Help icon
  • %I% - IDEA! Idea icon
  • %M% - MOVED TO... Moved to icon
  • %N% - NEW New icon
  • %P% - REFACTOR Refactor icon
  • %Q% - QUESTION? Question icon
  • %S% - PICK Pick icon
  • %T% - TIP Tip icon
  • %U% - UPDATED Updated icon
  • %X% - ALERT! Alert icon
  • %Y% - DONE Done icon
  • %RED% text %ENDCOLOR% - colored text (also %YELLOW%, %ORANGE%, %PINK%, %PURPLE%, %TEAL%, %NAVY%, %BLUE%, %AQUA%, %LIME%, %GREEN%, %OLIVE%, %MAROON%, %BROWN%, %BLACK%, %GRAY%, %SILVER%, %WHITE%)
  • %REDBG% text %ENDBG% - colored background (also %YELLOWBG%, %ORANGEBG%, %PINKBG%, %PURPLEBG%, %TEALBG%, %NAVYBG%, %BLUEBG%, %AQUABG%, %LIMEBG%, %GREENBG%, %OLIVEBG%, %MAROONBG%, %BROWNBG%, %BLACKBG%, %GRAYBG%, %SILVERBG%, %WHITEBG%)

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.

  • Show all TWiki Variables
  • Predefined variables can be overridden by preferences variables (except a few such as TOPIC and WEB)
    • This has long been the case but may not be desirable since even something as fundamental as %IF{...}%, %SCRIPT{...}%, and %INCLUDE{...}% can be overridden
    • So TWiki-6.0.1 has introduced a way to protect predefined variables from being overridden by preferences variables
    • The preferences variable OVERRIDABLEPREDEFINEDVARIABLES having a comma separated list of predefined variables specifies which predefined variables are overridable
    • By default, it's set to "all" (set at TWiki06x00.TWikiPreferences), which means any predefined variable can be overridden, which is for compatibility with prior releases. You can set it to a different value in Main.TWikiPreferences and you may finalise it
    • If it's set as below, all predefined variables are protected
         * Set OVERRIDABLEPREDEFINEDVARIABLES =
      
    • If it's set as below, DATE and LANGUAGE predefined variables can be overridden but all the other predefined variables cannot
         * Set OVERRIDABLEPREDEFINEDVARIABLES = DATE, LANGUAGE
      
  • Extensions may extend the set of predefined variables (see individual extension topics for details)
  • Take the time to thoroughly read through ALL preference variables. If you actively configure your site, review variables periodically. They cover a wide range of functions, and it can be easy to miss the one perfect variable for something you have in mind. For example, see %INCLUDINGTOPIC%, %INCLUDE%, and the mighty %SEARCH%.

Search or List Variables by Category

TWiki Variables » Search TWiki Variables

   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, COMMENT, CONTENTMODE, COPY, DASHBOARD, DATE, DATETIME, DISPLAYTIME, DISPLAYTIME2, EDITACTION, EDITFORM, EDITFORMFIELD, EDITTABLE, ENCODE, ENDBG, ENDCOLOR, ENDCOLUMNS, ENDSECTION, ENTITY, ENV, FAILEDPLUGINS, FORM, FORMFIELD, FOURCOLUMNS, GAUGE, GEOLOOKUP, 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, QRCODE, 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, SHAREME, SILVER, SITENAME, SITESTATISTICSTOPIC, SLIDESHOWEND, SLIDESHOWSTART, SPACEDTOPIC, SPACEOUT, STARTINCLUDE, STARTSECTION, STATISTICSTOPIC, STOPINCLUDE, SYSTEMWEB, T, TABLE, TEAL, THREECOLUMNS, TM, TOC, TOC2, TOPIC, TOPICLIST, TOPICTITLE, TOPICURL, TWIKIWEB, TWISTY, TWOCOLUMNS, U, URLPARAM, USERINFO, USERNAME, USERREPORT, USERSIG, USERSWEB, VAR, VARCACHE, VBAR, WEB, WEBLIST, WEBPREFSTOPIC, WHITE, WIKIHOMEURL, WIKILOGOALT, WIKILOGOIMG, WIKILOGOURL, WIKINAME, WIKIPREFSTOPIC, WIKITOOLNAME, WIKIUSERNAME, WIKIUSERSTOPIC, WIKIVERSION, 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 TWiki06x00 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:

  • Parent set to TWikiVariables
  • An anchor named the same like the topic, such as #VarLIGHTSABER
  • A ---+++ (level 3) heading with variable name, --, short description
  • A bullet with description of the variable (optional)
  • A Syntax: bullet with example syntax
  • A Parameters: bullet with a table explaining the parameters (optional)
  • An Example: bullet or two with examples
  • An Expands to: bullet with expanded variable (optional)
  • A Note: bullet with notes (optional)
  • A Category: bullet with one or more of the TWiki variables categories:
    AdministrationVariables, ApplicationsAndComponentsVariables, AttachmentsAndFilesVariables, ChartingAndDrawingVariables, DatabaseAndFormsVariables, DateAndTimeVariables, DevelopmentVariables, EditingAndContentUpdateVariables, EmailAndNotificationVariables, ExportAndPublishingVariables, FormattingAndRenderingVariables, ImportVariables, LinkingAndNavigationVariables, SearchingAndListingVariables, SecurityAndAccessControlVariables, SkinsAndTemplatesVariables, SystemInformationVariables, TablesAndSpreadsheetsVariables, UIAndVisualizationVariables, UsersAndAuthenticationVariables, WorkflowAndAutomationVariables
  • A Related: bullet with related links. Links have conditional IF so that links work properly locally in variable documentation topics and in the TWikiVariables 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



Comments & Questions about this Distribution Document Topic

Contributors: MikeMannix, PeterThoeny, MikeMaurer, JohnRouillard, GrantBow, WernerZirngibl, SamHasler, MartinGregory, CrawfordCurrie

(CrawfordCurrie removed older comments on 16 May 2004)

It might be useful to add a section on top with groups of related variables (also linked)

-- PeterThoeny - 08 May 2004

Perhaps, if the list is going to grow larger. Personally I find that the TOC list is short enough - and the variable names mnemonic enough - that it can be scanned very quickly (great refactor, BTW, thanks!). I made some spelling/grammatical corrections and added the Expands To: column to the table in Preferences variables.

-- CrawfordCurrie - 16 May 2004

Crawford split up this topic into included TWikiVariablesAtoM and TWikiVariablesNtoZ.

-- PeterThoeny - 26 Jul 2004

Should %ACTIVATEDPLUGINS% and %PLUGINDESCRIPTIONS% be documented here?

-- SamHasler - 18 Aug 2004

Logically yes.

-- PeterThoeny - 20 Aug 2004

What about the topic template variabes in TWikiTemplates#Edit_Template_Topics_and_Variabl or the variables used in skin templates?

I can understand why they perhaps shouldn't be documented here but there should at least be a link to the documentation for them as this is the first place many will look.

-- SamHasler - 05 Sep 2004

QUESTION? regarding WIKIHOMEURL. The explanation here says: "The base URL of TWiki, is the link of the Home icon in the upper left corner, defined in TWiki.cfg"

  • But TWikiPreferences indicates that WIKILOGOURL instead is responsible for the URL the logo links to.
  • Additionally lib/TWiki.cfg marks $wikiHomeUrl as obsolete.
So I guess, TWikiVariables is wrong and needs an update.

-- DanielKabs - 23 Aug 2005

Good catch. Please feel free to update inaccurate docs, it's a Wiki smile

-- PeterThoeny - 24 Aug 2005

Peter, I changed TWikiVariablesNtoZ. Now I wonder, how do changes on TWiki.org permeate into a release version? Please see my question "How changes in Twiki propagate" in CoffeeBreak.

-- DanielKabs - 23 Sep 2005

fixed VarWEBLIST dropdown example which was hardcoded to select the TWiki web rather than the current web. Also needed to be wrapped in form and select tags.

-- MattWilkie - 01 Mar 2007

Thanks Matt, is now merged into svn MAIN and patch branch.

-- PeterThoeny - 02 Mar 2007

When discussing how to define a variable, it would be nice if you could mention, by reference of course, how one creates a variable that takes arguments. That reference can mention MacrosPlugin, TWikiFns, TWikiApplications, etc. as appropriate. I searched high and low to find information on this. Those of you that know should be able to create some useful information easily. -- Thank you

-- RobStewart - 06 Sep 2007

The docs for what INCLUDE actually does are too sparse. It needs another bullet at the top with something like:

  • merges the content of a specified page into this one before rendering

-- ThomasErskine - 16 Jan 2009

The description for BASETOPIC is confusing.

The name of the topic where a single or nested INCLUDE started

Does that mean the leaf or the root? In other words if A includes B and B includes C, what is the value of BASETOPIC in A, B, or C?

-- JoshuaTharp - 2012-12-05

BASETOPIC will be set to A for A, B and C. I'll update the docs with an example.

-- PeterThoeny - 2012-12-06

I have a question w.r.t backgrounds applied. Whenever I apply a background to content in the

middle of the paragraph
, it starts and ends in a new line. Is there any reason why this happens? This does not happen when I change the font color

-- Bala Mahadevan - 2014-07-31

The most important question is there any way this can be avoided?

-- Bala Mahadevan - 2014-07-31

Bala, please ask support questions in the Support web.

-- Peter Thoeny - 2014-07-31

Please use the Support forum if you have questions about TWiki features. This comment section is about the documentation of this topic.
Edit | Attach | Watch | Print version | History: r145 < r144 < r143 < r142 < r141 | Backlinks | Raw View | Raw edit | More topic actions
Topic revision: r145 - 2014-12-16 - PeterThoeny
 
  • 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-2015 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.