Preferences

Preferences

Preferences (or short "Prefs") is Horde's name for user settings, i.e. any settings that can be changed by users individually. Preferences are available for almost all Horde applications and may be accessed by users clicking on the Options button in the top menu bar. There is also direct access to the individual applications' preference interfaces through the expandable Options menu entry in the left menu bar. Whether these buttons appear and under which condition can be configured by the administrator in Horde's configuration. Users can switch between the different applications' preferences by either using the entries in the left menu, or by picking an application in the top right drop down list inside the preference interface.

If you set up a Horde installation for more than a few individuals you might want to go through all available preferences to check whether the default values make sense for your kind of organization, or to even hide preferences that don't make sense for your users or might confuse them.

Preferences are organized in preference groups that are again divided into columns in the preference interface. All preferences, their descriptions, default values, groups, and columns are defined in the application's config/prefs.php file. This file contains two sections.

Preference groups

The first section which defines the $prefGroups variable, is responsible for grouping individual preferences into groups. The result is the overview page that users will see if accessing the preference interface. Each $prefGroups entry defines one group by setting

the internal (arbitrary) group identifier (the key of the $prefGroups array, i.e. the "identities" in $prefGroups['identities']
the group header ('label')
the group description ('desc')
and the preferences that should belong to that group ('members')

You can change any of these settings according to your needs but please note a few things:

Some group identifiers or less arbitrary than others, especially the 'identities'. Only change group identifiers if you really have to.
You should not simply remove preferences from the 'members' setting if you don't want your users to change those preferences. Lock those preferences instead (see below).
Preference groups may be empty in the interfaces under certain conditions. You can remove or comment out that $prefGroups then.

If there is only a single preference group for an application, the user will get directly to that preference group when he accesses the preference interface, skipping the overview page altogether.

Individual preferences

The second section of the prefs.php files contains the definitions of the individual preferences, as specified in the $_prefs variable. Generally each entry in $_prefs is associated with a user setting, but there are a few exceptions. The following settings define how a preference work:

The key (e.g. "theme" in $_prefs['theme']) is the unique identifier of the preference. This is how the preference will be referenced anywhere in the Horde code.
'value' will hold the default preference value, i.e. the value that will be used for any users that didn't overwrite the preference with their own value. The kind of value that has to be entered there depends on the preference type, see the table below.
'locked' allows to keep users from changing this preference. Set it to true to not show this preference in the interface. This has no effect on 'link' type preferences.
'shared' defines whether the preference is available to all Horde applications, see "Scope" below.
'type' specifies the type of preference. There is a limited set of types available, see the table below.
'enum' provides the list of possible preference values for preferences of the 'enum' type.
'escaped' sets for enum or select type preferences whether the keys and values are already html-escaped. Defaults to false if not present.
'hook' sets whether a hook function should be called to get the default value for that preference, see Hooks below.

Valid preference types

Preference type	Explanation
checkbox	Provides a checkbox.
enum	Provides a selection list in the UI, list is specified in the associated 'enum' setting.
implicit	Provides storage for 'special' types.
link	Provides a link to another data entry form.
number	Provides a 3-character textbox to enter a natural number; syntaxcheck is performed after data entry.
password	Provides a textbox for password entry.
select	Provides a selection list in the UI that is built in lib/prefs.php.
special	Provides an UI widget.
text	Provides a single-line textbox.
textarea	Provides a multi-line textbox.

Valid default values

Preference type	Value format
checkbox	0 or false for unchecked, 1 or true for checked
enum	Preselected item from associated enumeration
implicit	Depends on the individual preference
link	Not used
number	Number value, integer or float
password	Should be ''
select	Preselected item from associated selection list
special	Not used
text	Text value, e.g. string in single quotes
textarea	Text value, e.g. string in double quotes, lines separated with "\n"

Scope

Preference values

Preference values are cached in the user's session. This means that default value changes in the prefs.php configuration file don't have any effect until the user logs in the next time. Changes to the "cosmetic" settings that influence the interface like descriptions or grouping are applied immediately.

Preference values stored in the preference backend take precedence over the default settings defined in prefs.php, even if the preferences are locked. The idea is that you can override preferences for individual user by setting values for them in the backend. As a consequence, you have to delete existing values in backend, if you change the default value and want it to be applied to all users, even those that already changed that setting. This could be done with a SQL preference with the following query for example:

DELETE FROM horde_prefs WHERE pref_scope = '<application_name>' AND pref_name = '<preference_name>'

Default values

Hooks

Identities

More information

See CustomizingPreferencesH3 for a number of user-contributed preference settings and hooks.

Table of Contents