Difference: TWikiVariables (88 vs. 89)

Revision 892014-01-20 - TWikiContributor

Line: 1 to 1

META TOPICPARENT	name="WebHome"

Contents:

Line: 49 to 49

You can set variables in all the following places:

Changed:

<
<

system level in TWiki.TWikiPreferences

>
>

system level in TWiki.TWikiPreferences

plugin topics (see TWikiPlugins)
local site level in Main.TWikiPreferences
user level in individual user topics in Main web

Added:

>
>

- 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

web level in WebPreferences of each web
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
topic level in topics in webs
session variables (if sessions are enabled)

Added:

>
>

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.

Line: 89 to 92

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.

Added:

>
>

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:

Parameter from variable call. In above example, %PARAM1% gets expanded to bar.
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%.

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.

Line: 152 to 191

Show all TWiki Variables
Predefined variables can be overridden by preferences variables (except a few such as TOPIC and WEB)

Added:

>
>

- 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 TWiki.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%.

Changed:

<
<

Search or List Variables by Category

>
>

Search or List Variables by Category

View topic | History: r90 < r89 < r88 < r87 | More topic actions...

Copyright © 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.