extract_doc1Add my vote for this tag create new tag
, view all tags

The Dakar Preference Model

This does not include access control

You can set variables in all the following places:

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

You can think of preferences as a stack. Each "context" is a level in the stack. So, for example, let's say you are in the middle of rendering a topic. Your mental image of the stack will look like this

Level Preferences
0 Global - defined in code or Configure
1 Local Site in TWikiPreferences
2 Plugin topic
3 Local Site in %WEBPREFSTOPIC% - normally Main.TWikiPreferences
4 Users own %MAINWEB%Topic
5 WebPreferences
6 Current topic being viewed
7 Session variables

The user view of preferences is that if a setting of a pref is not found at the "session" level 7, then it will be looked up at the "topic" level 6, and then the "web" level 5, and so on.

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.

This is important to notice.


  • An admin defines the ATTACHFILESIZELIMIT to 10 kbytes in Main.TWikiPreferences but does add it to FINALPREFERENCES
  • A user defines the ATTACHFILESIZELIMIT to 1000000 kbytes in his home topic
  • The admin defines ATTACHFILESIZELIMIT to 1000 kbytes in some webs and keeps it undefined in the other webs. In all webs he adds ATTACHFILESIZELIMIT to FINALPREFERENCES
  • The result is that in those webs where the admin defined a value for ATTACHFILESIZELIMIT this limit is the one used. But for the webs where it is not defined, it is the value defined in the users home topic that is used and not the site level value. This is important to notice.
  • In Cairo Users preferences were overriding web preferences which meant that the admin had to remember to add all his web preferences to FINALPREFERENCES. Otherwise the users could override them.
  • Both the TWiki4 and the Cairo model had their pros and cons.

In TWiki 4.1 the Plugin level preferences has been moved from between topic level and session level - to between TWiki.TWikiPreferences and Main.TWikiPreferences. The reasons for this are

  • Preferences defined in plugin topics could not be altered at topic level. This was highly desired by many.
  • Preferences could not be defined in Main.TWikiPreferences to avoid customized default from being constantly overwritten when a plugin was updated.

Additionally 4.1 now allows Plugins to define variable at global level in Configure which is both more efficient and safer for certain types of variables.

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

  • Set VARIABLENAME = value
    • Set VARIABLENAME = 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.
   * 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. Preferences set in this manner are not visible in the topic text, but take effect nevertheless.

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:
   * 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.

-- Contributors: CrawfordCurrie, KennethLavrsen


I dont know what the alternatives are, but this is vaguely insane. 9 places that preferences can come from?

-- MeredithLesly - 21 May 2006

Only nine? No, there's a lot more than that. Consider that constant tags set in the code are also preferences. And each level in the stack can offer local and inherited prefs. I make it at least 17 different places.

Actually, it makes perfect sense, except for the "special case" of access controls, which is where most people become unstuck.

If I was going to start again, I wouldn't do it this way. But that's easy to say.

-- CrawfordCurrie - 21 May 2006

OK, so I undercounted. That definitely doesn't improve things. frown

-- MeredithLesly - 21 May 2006

Updated with the model as it will be working from TWiki4.1.

This topic can service for further discussions and ideas triggered by the discarded Bugs:Item3252.

Note that I am not pushing for a spec change!

-- KennethLavrsen - 17 Dec 2006

Ken, thanks for the update. The 4.1 model is a great step forward. The next thing to do about preferences is to speed it up, not to change the spec. Much performance is still wasted in handling preferences (according to my--unscientific--measurements).

-- ThomasWeigert - 17 Dec 2006

I expect to be adding a TWikiCache api to twiki in 4.2 - it will ne leveraged here too.

-- SvenDowideit - 18 Dec 2006

Edit | Attach | Watch | Print version | History: r6 < r5 < r4 < r3 < r2 | Backlinks | Raw View | Raw edit | More topic actions
Topic revision: r6 - 2006-12-18 - SvenDowideit
  • 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-2017 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.