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. local site 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:
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

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

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-6.1.0, Mon, 16 Jul 2018, build 30610

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

BUBBLESIG -- show bubble box and user signature with profile picture icon

BULLET -- bullet character

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

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

CARET -- caret symbol

CHILDREN -- find children of a topic

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

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

CONTENTMODE{web="WEB"} -- content mode

COPY -- Copyright symbol

DASHBOARD -- build a dashboard with banner and boxes

DATE -- signature format date

DATEPICKER{} -- pop-up calendar to select a date for use in HTML forms

DISPLAYTIME -- display date and time

DISPLAYTIME{"format"} -- formatted display time

EDITACTION -- Selects an edit template

EDITFORM{} -- render a TWiki form for edit

EDITFORMFIELD{"fieldname" form=""} -- render an input field specified in a form template topic

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

ENDCOLUMNS -- end a responsive multi-column page layout

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

ENTITY{string} -- encode a string to HTML entities

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

EXAMPLEVAR -- example variable

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

FORM{} -- render a TWiki form for view

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

FOURCOLUMNS -- responsive four-column page layout

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{text} -- hide content in topic view

HIDEINPRINT{text} -- hide content when printing

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

LAQUO -- left double angle quote

LIME -- start lime colored text

LOCALSITEPREFS -- web.topicname of site preferences topic

LOGIN -- present a full login link

LOGINURL -- present a login link

LOGOUT -- present a full logout link

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

MDREPO -- retrieve data from metadata repository

META -- displays meta-data

METASEARCH -- special search of meta data

N -- "new" icon

NAVY -- start navy blue colored text

NBSP -- non-breaking space

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

PARENTBC -- parent breadcrumbs for headings

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

Sequence: Expands To:
$name Name of the parameter
$value String value of the parameter. Multi-valued parameters will have a "row" for each value.
$n or $n() New line. Use $n() if followed by alphanumeric character, e.g. write Foo$n()Bar instead of Foo$nBar
$nop or $nop() Is a "no operation". This variable gets removed; useful for nested search
$quot Double quote (") (\" also works)
$percnt Percent sign (%)
$dollar Dollar sign ($)

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

RAQUO -- right double angle quote

RED -- start red colored text

REDBG -- start red colored background section

REG -- Registered Trademark symbol

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 variables

SILVER -- start silver colored text

SITENAME -- the current site name

SITESTATISTICSTOPIC -- name of site statistics topic

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

THREECOLUMNS -- responsive three-column page layout

TM -- Trademark symbol

TOC -- table of contents of current topic

TOC{"Topic"} -- table of contents

TOPIC -- name of current topic

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

TOPICTITLE -- title of a topic

TOPICURL -- shortcut to viewing the current topic

TWIKISHEET{} -- enable TWiki Sheet (spreadsheet) and set options

TWIKIWEB -- synonym for SYSTEMWEB

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

TWOCOLUMNS -- responsive two-column page layout

U -- "updated" icon

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

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

USERNAME -- your login username

USERREPORT -- show user reports with profile pictures

USERSIG -- show user signature with profile picture icon

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

WIKIWEBMASTER -- email address of the administrator

WIKIWEBMASTERNAME -- name of the administrator

WIP -- work in progress icon

X -- warning icon

Y -- "yes" icon

YELLOW -- start yellow colored text

Related Topics: UserDocumentationCategory, TWikiVariablesSearch, TWikiVariablesQuickStart