TWiki/TWikiPrefsDotPm.mdwn

   1 # <a name="Package &lt;code&gt;TWiki::Prefs="></a> Package =TWiki::Prefs
   2
   3 The Prefs class is a singleton that implements management of preferences. It uses a stack of TWiki::Prefs::PrefsCache objects to store the preferences for global, web, user and topic contexts, and provides the means to look up preferences in these.
   4
   5 Preferences from different places stack on top of each other, so there are global preferences, then site, then web (and subweb and subsubweb), then topic, included topic and so on. Each level of the stack is tagged with a type identifier.
   6
   7 The module also maintains a separate of the preferences found in every topic and web it reads. This supports the lookup of preferences for webs and topics that are not on the stack, and must not be chained in (you can't allow a user to override protections from their home topic!)
   8
   9 <div>
  10   <ul>
  11     <li><a href="#Package =TWiki::Prefs="> Package TWiki::Prefs</a><ul>
  12         <li><a href="#ClassMethod <strong>new</strong> ($session[,$ca"> ClassMethod new <tt>($session[,$cache])</tt></a></li>
  13         <li><a href="#ObjectMethod <strong>finish</strong> ()"> ObjectMethod finish <tt>()</tt></a></li>
  14         <li><a href="#ObjectMethod <strong>pushPreferences</strong> ("> ObjectMethod pushPreferences <tt>($web,$topic,$type)</tt></a></li>
  15         <li><a href="#ObjectMethod *push_WebPreference"> ObjectMethod pushWebPreferences <tt>($web)</tt></a></li>
  16         <li><a href="#ObjectMethod *push_GlobalPrefere"> ObjectMethod pushGlobalPreferences <tt>()</tt></a></li>
  17         <li><a href="#ObjectMethod *push_PreferencesVa"> ObjectMethod pushPreferencesValues <tt>($type,\%values)</tt></a></li>
  18         <li><a href="#ObjectMethod <strong>mark</strong> ()"> ObjectMethod mark <tt>()</tt></a></li>
  19         <li><a href="#ObjectMethod <strong>restore</strong> ($mark)"> ObjectMethod restore <tt>($mark)</tt></a></li>
  20         <li><a href="#ObjectMethod *get_PreferencesVal"> ObjectMethod getPreferencesValue <tt>($key) -&gt; $value</tt></a></li>
  21         <li><a href="#ObjectMethod <strong>isFinalised</strong> ($key"> ObjectMethod isFinalised <tt>($key)</tt></a></li>
  22         <li><a href="#ObjectMethod *get_TopicPreferenc"> ObjectMethod getTopicPreferencesValue <tt>($key,$web,$topic) -&gt; $value</tt></a></li>
  23         <li><a href="#get_TextPreferencesValue( $key,"> getTextPreferencesValue( $key, $text, $meta, $web, $topic ) -&gt; $value</a></li>
  24         <li><a href="#ObjectMethod *get_WebPreferences"> ObjectMethod getWebPreferencesValue <tt>($key,$web) -&gt; $value</tt></a><ul>
  25             <li><a href="#set_PreferencesValue($name, $val"> setPreferencesValue($name, $val)</a></li>
  26           </ul>
  27         </li>
  28         <li><a href="#ObjectMethod stringify() -> $tex">ObjectMethod stringify() -&gt; $text</a></li>
  29       </ul>
  30     </li>
  31   </ul>
  32 </div>
  33
  34 ## <a name="ClassMethod &lt;strong&gt;new&lt;/strong&gt; ($session[,$ca"></a> [[ClassMethod]] **new** `($session[,$cache])`
  35
  36 Creates a new Prefs object. If $cache is defined, it will be pushed onto the stack.
  37
  38 ## <a name="ObjectMethod &lt;strong&gt;finish&lt;/strong&gt; ()"></a> [[ObjectMethod]] **finish** `()`
  39
  40 Break circular references.
  41
  42 ## <a name="ObjectMethod &lt;strong&gt;pushPreferences&lt;/strong&gt; ("></a> [[ObjectMethod]] **pushPreferences** `($web,$topic,$type)`
  43
  44 - `$web` - web to read from
  45 - `$topic` - topic to read
  46 - `$type` - DEFAULT, SITE, USER, SESSION, WEB, TOPIC or PLUGIN
  47 - `$prefix` - key prefix for all preferences (used for plugins)
  48
  49 Reads preferences from the given topic, and pushes them onto the preferences stack.
  50
  51 ## <a name="ObjectMethod &lt;strong&gt;push_WebPreference"></a> [[ObjectMethod]] \*pushWebPreferences `($web)`
  52
  53 Pushes web preferences. Web preferences for a particular web depend on the preferences of all containing webs.
  54
  55 ## <a name="ObjectMethod &lt;strong&gt;push_GlobalPrefere"></a> [[ObjectMethod]] \*pushGlobalPreferences `()`
  56
  57 Add global preferences to this preferences stack.
  58
  59 ## <a name="ObjectMethod &lt;strong&gt;push_PreferencesVa"></a> [[ObjectMethod]] \*pushPreferencesValues `($type,\%values)`
  60
  61 Push a new preference level using type and values given
  62
  63 ## <a name="ObjectMethod &lt;strong&gt;mark&lt;/strong&gt; ()"></a> [[ObjectMethod]] **mark** `()`
  64
  65 Return a marker representing the current top of the preferences stack. Used to remember the stack when new web and topic preferences are pushed during a topic include.
  66
  67 ## <a name="ObjectMethod &lt;strong&gt;restore&lt;/strong&gt; ($mark)"></a> [[ObjectMethod]] **restore** `($mark)`
  68
  69 Resets the preferences stack to the given mark, to recover after a topic include.
  70
  71 ## <a name="ObjectMethod &lt;strong&gt;get_PreferencesVal"></a> [[ObjectMethod]] \*getPreferencesValue `($key) -> $value`
  72
  73 - =$key - key to look up
  74
  75 Returns the value of the preference `$key`, or undef.
  76
  77 Looks up local preferences when the level topic is the same as the current web,topic in the session.
  78
  79 ## <a name="ObjectMethod &lt;strong&gt;isFinalised&lt;/strong&gt; ($key"></a> [[ObjectMethod]] **isFinalised** `($key)`
  80
  81 Return true if $key is finalised somewhere in the prefs stack
  82
  83 ## <a name="ObjectMethod &lt;strong&gt;get_TopicPreferenc"></a> [[ObjectMethod]] \*getTopicPreferencesValue `($key,$web,$topic) -> $value`
  84
  85 Recover a preferences value that is defined in a specific topic. Does not recover web, user or global settings.
  86
  87 Intended for use in protections mechanisms, where the order doesn't match the prefs stack.
  88
  89 ## <a name="get_TextPreferencesValue( $key,"></a><a name="get_TextPreferencesValue( $key, "></a> getTextPreferencesValue( $key, $text, $meta, $web, $topic ) -&gt; $value
  90
  91 Get a preference value from the settings in the text (and/or optional $meta). The values read are **not** cached.
  92
  93 ## <a name="ObjectMethod &lt;strong&gt;get_WebPreferences"></a> [[ObjectMethod]] \*getWebPreferencesValue `($key,$web) -> $value`
  94
  95 Recover a preferences value that is defined in the webhome topic of a specific web.. Does not recover user or global settings, but does recover settings from containing webs.
  96
  97 Intended for use in protections mechanisms, where the order doesn't match the prefs stack.
  98
  99 ### <a name="set_PreferencesValue($name, $val"></a> setPreferencesValue($name, $val)
 100
 101 Set a preferences value. The preference is set in the context at the top of the preference stack, whatever the current state may be.
 102
 103 The preference is not serialised.
 104
 105 ## <a name="ObjectMethod stringify() - $text"></a> [[ObjectMethod]] stringify() -&gt; $text
 106
 107 Generate a TML-formatted version of the current preferences