data/TWiki/TWikiPrefsDotPm.txt,v
author Colas Nahaboo <colas@nahaboo.net>
Sat, 26 Jan 2008 15:50:53 +0100
changeset 0 414e01d06fd5
permissions -rw-r--r--
RELEASE 4.2.0 freetown
     1 head	1.6;
     2 access;
     3 symbols;
     4 locks; strict;
     5 comment	@# @;
     6 
     7 
     8 1.6
     9 date	2008.01.22.03.21.31;	author TWikiContributor;	state Exp;
    10 branches;
    11 next	1.5;
    12 
    13 1.5
    14 date	2007.01.16.04.11.58;	author TWikiContributor;	state Exp;
    15 branches;
    16 next	1.4;
    17 
    18 1.4
    19 date	2006.10.25.00.21.56;	author TWikiContributor;	state Exp;
    20 branches;
    21 next	1.3;
    22 
    23 1.3
    24 date	2006.06.25.16.26.33;	author TWikiContributor;	state Exp;
    25 branches;
    26 next	1.2;
    27 
    28 1.2
    29 date	2006.04.01.05.55.40;	author TWikiContributor;	state Exp;
    30 branches;
    31 next	1.1;
    32 
    33 1.1
    34 date	2006.02.01.12.01.25;	author TWikiContributor;	state Exp;
    35 branches;
    36 next	;
    37 
    38 
    39 desc
    40 @new-topic
    41 @
    42 
    43 
    44 1.6
    45 log
    46 @buildrelease
    47 @
    48 text
    49 @---+ Package =TWiki::Prefs=
    50 
    51 The Prefs class is a singleton that implements management of preferences.
    52 It uses a stack of TWiki::Prefs::PrefsCache objects to store the
    53 preferences for global, web, user and topic contexts, and provides
    54 the means to look up preferences in these.
    55 
    56 Preferences from different places stack on top of each other, so there
    57 are global preferences, then site, then web (and subweb and subsubweb),
    58 then topic, included topic and so on. Each level of the stack is tagged with
    59 a type identifier.
    60 
    61 The module also maintains a separate of the preferences found in every topic
    62 and web it reads. This supports the lookup of preferences for webs and topics
    63 that are not on the stack, and must not be chained in (you can't allow
    64 a user to override protections from their home topic!)
    65 
    66 
    67 %TOC%
    68 
    69 ---++ ClassMethod *new* <tt>($session[,$cache])</tt>
    70 
    71 Creates a new Prefs object. If $cache is defined, it will be
    72 pushed onto the stack.
    73 
    74 
    75 
    76 ---++ ObjectMethod *finish* <tt>()</tt>
    77 Break circular references.
    78 
    79 
    80 
    81 ---++ ObjectMethod *pushPreferences* <tt>($web,$topic,$type)</tt>
    82    * =$web= - web to read from
    83    * =$topic= - topic to read
    84    * =$type= - DEFAULT, SITE, USER, SESSION, WEB, TOPIC or PLUGIN
    85    * =$prefix= - key prefix for all preferences (used for plugins)
    86 Reads preferences from the given topic, and pushes them onto the
    87 preferences stack.
    88 
    89 
    90 
    91 ---++ ObjectMethod *pushWebPreferences* <tt>($web)</tt>
    92 
    93 Pushes web preferences. Web preferences for a particular web depend
    94 on the preferences of all containing webs.
    95 
    96 
    97 
    98 ---++ ObjectMethod *pushGlobalPreferences* <tt>()</tt>
    99 Add global preferences to this preferences stack.
   100 
   101 
   102 
   103 ---++ ObjectMethod *pushPreferencesValues* <tt>($type,\%values)</tt>
   104 Push a new preference level using type and values given
   105 
   106 
   107 
   108 ---++ ObjectMethod *mark* <tt>()</tt>
   109 Return a marker representing the current top of the preferences
   110 stack. Used to remember the stack when new web and topic preferences
   111 are pushed during a topic include.
   112 
   113 
   114 
   115 ---++ ObjectMethod *restore* <tt>($mark)</tt>
   116 Resets the preferences stack to the given mark, to recover after a topic
   117 include.
   118 
   119 
   120 
   121 ---++ ObjectMethod *getPreferencesValue* <tt>($key) -> $value</tt>
   122    * =$key - key to look up
   123 
   124 Returns the value of the preference =$key=, or undef.
   125 
   126 Looks up local preferences when the level
   127 topic is the same as the current web,topic in the session.
   128 
   129 
   130 
   131 ---++ ObjectMethod *isFinalised* <tt>($key)</tt>
   132 Return true if $key is finalised somewhere in the prefs stack
   133 
   134 
   135 
   136 ---++ ObjectMethod *getTopicPreferencesValue* <tt>($key,$web,$topic) -> $value</tt>
   137 
   138 Recover a preferences value that is defined in a specific topic. Does
   139 not recover web, user or global settings.
   140 
   141 Intended for use in protections mechanisms, where the order doesn't match
   142 the prefs stack.
   143 
   144 
   145 
   146 ---++ getTextPreferencesValue( $key, $text, $meta, $web, $topic ) -> $value
   147 Get a preference value from the settings in the text (and/or optional $meta).
   148 The values read are *not* cached.
   149 
   150 
   151 ---++ ObjectMethod *getWebPreferencesValue* <tt>($key,$web) -> $value</tt>
   152 
   153 Recover a preferences value that is defined in the webhome topic of
   154 a specific web.. Does not recover user or global settings, but
   155 does recover settings from containing webs.
   156 
   157 Intended for use in protections mechanisms, where the order doesn't match
   158 the prefs stack.
   159 
   160 
   161 
   162 ---+++ setPreferencesValue($name, $val)
   163 
   164 Set a preferences value. The preference is set in the context at the
   165 top of the preference stack, whatever the current state may be.
   166 
   167 The preference is not serialised.
   168 
   169 
   170 ---++ObjectMethod stringify() -> $text
   171 
   172 Generate a TML-formatted version of the current preferences
   173 
   174 @
   175 
   176 
   177 1.5
   178 log
   179 @buildrelease
   180 @
   181 text
   182 @d28 2
   183 a29 5
   184 ---++ ObjectMethod *finish* <tt></tt>
   185 Complete processing after the client's HTTP request has been responded
   186 to. 
   187    1 breaking circular references to allow garbage collection in persistent
   188      environments
   189 d67 1
   190 a67 1
   191 ---++ ObjectMethod *resetTo* <tt>($mark)</tt>
   192 d114 8
   193 @
   194 
   195 
   196 1.4
   197 log
   198 @buildrelease
   199 @
   200 text
   201 @a35 5
   202 ---++ ObjectMethod *pushGlobalPreferences* <tt>()</tt>
   203 Add global preferences to this preferences stack.
   204 
   205 
   206 
   207 d53 5
   208 @
   209 
   210 
   211 1.3
   212 log
   213 @buildrelease
   214 @
   215 text
   216 @d101 3
   217 a103 3
   218 ---++ getTextPreferencesValue( $key, $text, $web, $topic ) -> $value
   219 Get a preference value from the settings in the text. The values are
   220 *not* cached.
   221 @
   222 
   223 
   224 1.2
   225 log
   226 @buildrelease
   227 @
   228 text
   229 @d28 8
   230 @
   231 
   232 
   233 1.1
   234 log
   235 @buildrelease
   236 @
   237 text
   238 @d94 2
   239 a95 2
   240 Get a preference value from the settings in the text. The parsed
   241 values are cached against the web, topic.
   242 @