Difference: TWikiVariables (87 vs. 88)

Revision 882013-04-24 - TWikiContributor

Line: 1 to 1
 
META TOPICPARENT name="WebHome"
Added:
>
>
 

TWiki Variables

Changed:
<
<		Special text strings expand on the fly to display user data or system info
>
>		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:
Changed:
<
<
  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)
>
>
  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

 
Changed:
<
<
On this page:
>
>
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)
Changed:
<
<
  • type %CALC{ "$UPPER(Text)" }% to get TEXT (a variable defined by a plugin)
>
>
  • 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
Changed:
<
<

Variable Names

>
>

Variable Names

 
Changed:
<
<		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.
>
>		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.
 
Changed:
<
<		By convention all settings, predefined variables and variables used by plugins are always UPPER-CASE.
>
>		By convention all settings, predefined variables and variables handled by extensions are always UPPER-CASE.
 
Line: 45 to 54
 
  1. local site level in Main.TWikiPreferences
  2. user level in individual user topics in Main web
  3. web level in WebPreferences of each web
Added:
>
>
  1. 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
 
  1. topic level in topics in webs
  2. session variables (if sessions are enabled)
Line: 82 to 93
 

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.

View topic | History: r91 < r90 < r89 < r88 | More topic actions...
 
This site is powered by the TWiki collaboration platform Powered by PerlCopyright © 1999-2025 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback
Note: Please contribute updates to this topic on TWiki.org at TWiki:TWiki.TWikiVariables.