PerlDoc

See PublishedAPI for packages intended to be used by Plugin and Contrib authors, or browse all packages.
See also Developing plugins, Developer's Bible, Technical Overview

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

• =$key - key to look up

Returns the finalised preference value.

ObjectMethod stringify([$key]) → $text

Generate TML-formatted information about the key (all keys if $key is undef)