%VARIABLE%
or %VARIABLE{ parameter="value" }%
- that expand into content whenever a topic is rendered for viewing. There are two types of variables:
%T%
renders as
%CALCULATE{}%
is handled by the SpreadSheetPlugin
Categories:
|
Variables:
|
%T%
to get (a preferences variable)
%TOPIC%
to get TWikiVariables
(a predefined variable)
%CALCULATE{ "$UPPER(Text)" }%
to get TEXT
(a variable defined by a plugin)
!%TOPIC%
to get %TOPIC%
%ALLVARIABLES%
to get a full listing of all variables defined for a particular topic
%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.
%USERPREFSTOPIC%
in the user's subweb is read instead
$TWiki::cfg{DemoteUserPreferences}
is true, this step is deferred to a later step. On this TWiki installation, $TWiki::cfg{DemoteUserPreferences}
is false
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
$TWiki::cfg{DemoteUserPreferences}
is true as mentioned at the step 4
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 = valueSpaces 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 hereWhatever you include in your variable will be expanded on display, exactly as if it had been entered directly. Example: Create a custom logo variable
%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.gifYou 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.
$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. DENYUSERPREFEENCES
and ALLOWUSERPREFERENCES
may have comma separated list of variable names
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
ALLOWUSERPREFERENCES
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 ALLOWUSERPREFERENCES
has the same effect
DENYUSERPREFEENCES
takes precedence over ALLOWUSERPREFERENCES
. If a variable is listed on both, it cannot be overridden. If DENYUSERPREFEENCES
is "all", the value of ALLOWUSERPREFERENCES
doesn't matter.
* Set DENYUSERPREFERENCES = allIf you allow
INYMCEPLUGIN_DISABLE
and SKIN
to be set at the user level:
* Set ALLOWUSERPREFERENCES = TINYMCEPLUGIN_DISABLE, SKINIf you allow user preferences to set anything other than
TINYMCEPLUGIN_DISABLE
or SKIN
:
* Set DENYUSERPREFERENCES = TINYMCEPLUGIN_DISABLE, SKINPlease 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.
* 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 missingwhich resolves to:
%PARAM1%
gets expanded to bar
.
* Set DRINK = red wine * Set FAVORITE = My %DEFAULT{default="favorite"}% dish is %DISH{default="steak"}%, my %DEFAULT{default="favorite"}% drink is %DRINK%.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:
%FAVORITE{}%Returns:
%FAVORITE{ "preferred" }%Returns:
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 = 20Then 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.
%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 icon
%I%
- Idea icon
%M%
- Moved to icon
%N%
- New icon
%P%
- Refactor icon
%Q%
- Question icon
%S%
- Pick icon
%T%
- Tip icon
%U%
- Updated icon
%X%
- Alert icon
%Y%
- 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%
)
%SEARCH%
, are powerful and general tools.
%IF{...}%
, %SCRIPT{...}%
, and %INCLUDE{...}%
can be overridden
OVERRIDABLEPREDEFINEDVARIABLES
having a comma separated list of predefined variables specifies which predefined variables are overridable
*Set OVERRIDABLEPREDEFINEDVARIABLES =
DATE
and LANGUAGE
predefined variables can be overridden but all the other predefined variables cannot*Set OVERRIDABLEPREDEFINEDVARIABLES = DATE, LANGUAGE
%INCLUDINGTOPIC%
, %INCLUDE%
, and the mighty %SEARCH%
.
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:
#VarLIGHTSABER
---+++
(level 3) heading with variable name, --
, short description
Syntax:
bullet with example syntax
Parameters:
bullet with a table explaining the parameters (optional)
Example:
bullet or two with examples
Expands to:
bullet with expanded variable (optional)
Note:
bullet with notes (optional)
Category:
bullet with one or more of the TWiki variables categories:Related:
bullet with related links. Links have conditional IF so that links work properly locally in variable documentation topics and in the TWikiVariables topic
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]], LightsaberPluginRelated Topics: UserDocumentationCategory, TWikiVariablesWizard, TWikiVariablesSearch, TWikiVariablesQuickStart, ParameterizedVariables