Foswiki::Prefs
internal package
Foswiki::Prefs
Preferences are set in topics, using either 'Set' lines embedded in the
topic text, or via PREFERENCE meta-data attached to the topic. A preference
value has four
scopes:
- Global scope
- Local scope
- Web scope
- Topic scope
In
global scope, the value of a preference is determined by examining
settings of the variable at different levels; default preferences, site level,
parent web level, web level, user level, and topic level. To determine a
preference value in global scope, you have to know what topic the topic is
referenced in, to provide the scope for the request.
A preference may be optionally defined in
Local scope, in which case the
topic definition of the variable is always taken when it is referenced in the
topic where it is defined. This is a special case to deal with the case where a
preference has to have a different value in the defining topic.
Values in global and local scope are accessed using =getPreference=/
Web scope is used by web access controls. Subwebs inherint access controls
from parent webs and only from parent webs. Global and Local scopes are
disconsidered.
The final scope is
topic scope. In this scope, the value of the preference is
taken directly from the contents of the topic, and is not overridden by wider
scopes. Topic scope is used for topic access controls.
Because the highest cost in evaluating preferences is reading the individual
topics, preferences read from a topic are cached.
An object of type
Foswiki::Prefs is a singleton that provides an interface to
this cache. Normally the cache is repopulated for each request, though it would
be feasible to cache it on disc if some invalidation mechanism were available
to deal with topic changes.
This mechanism is composed by a front-end (implemented by this class) that
deals with preferences logic and back-end objects that provide access to
preferences values. There is one back-end for each topic (Web preferences are
back-ends correspondind to the
WebPreferences topic). Additionaly, there is a
back-end object for session preferences. Each context has its own session
preferences and thus its own session back-end object.
Preferences are like a stack: there are many levels and higher levels have
precedence over lower levels. It's also needed to push a context and pop to the
earlier state. It would be easy to implement this stack, but then we would have
a problem: to get the value of a preference we would need to scan each level
and it's slow, so we need some fast mechanism to know in which level a
preference is defined. Or we could copy the values from lower leves to higher
ones and override the preferences defined at that level. This later approach
wastes memory. This implementation picks the former and we use bitstrings and
some maths to accomplish that. It's also flexible and it doesn't matter how
preferences are stored.
ClassMethod
new( $session )
Creates a new Prefs object.
ObjectMethod
finish()
Break circular references.
ObjectMethod
loadPreferences( $topicObject ) → $back
Invoked from
Foswiki::Meta to load the preferences into the preferences
cache. used as part of the lazy-loading of preferences.
Web preferences are loaded from the {WebPrefsTopicName}.
ObjectMethod
pushTopicContext( $web, $topic )
Reconfigures the preferences so that general preference values appear
to come from $web.$topic. The topic context can be popped again using
popTopicContext.
popTopicContext()
Returns the context to the state it was in before the
pushTopicContext
was last called.
ObjectMethod
setPluginPreferences( $web, $plugin )
Reads preferences from the given plugin topic and injects them into
the plugin preferences cache. Preferences cannot be finalised in
plugin topics.
ObjectMethod
setUserPreferences( $wikiname )
Reads preferences from the given user topic and pushes them to the preferences
stack.
ObjectMethod
loadDefaultPreferences()
Add default preferences to this preferences stack.
ObjectMethod
loadSitePreferences()
Add local site preferences to this preferences stack.
ObjectMethod
setSessionPreferences( %values )
Set the preference values in the parameters in the SESSION stack.
ObjectMethod
setInternalPreferences( %values )
Designed specifically for imposing the value of preferences on a short-term
basis in the code, internal preferences override all other definitions of
the same tag. This function should be used with great care.
For those who are used to the old code, internal preferences replace the old
SESSION_TAGS field from the Foswiki object.
ObjectMethod
getPreference( $key ) → $value
Returns the finalised preference value.
ObjectMethod
stringify([$key]) → $text
Generate TML-formatted information about the key (all keys if $key is undef)