[cvs] [Wiki] changed: Doc/Admin/Preferences

Mon Sep 21 12:38:08 UTC 2009

jan  Mon, 21 Sep 2009 08:38:08 -0400

Modified page: http://wiki.horde.org/Doc/Admin/Preferences
New Revision:  1.1
Change log:  More content

@@ -1,10 +1,72 @@
+[[toc]]
+
  + 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  
((Doc/Dev/Admin/Config/Horde|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.
+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  
((Doc/Admin/Config/Horde|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.

-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.
-[...]
+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:
@@ -12,7 +74,13 @@
  <code type="sql">
  DELETE FROM horde_prefs WHERE pref_scope = '<application_name>' AND  
pref_name = '<preference_name>'
  </code>

-[identities]
++++ Default values
+
++++ Hooks
+
+++ Identities
+
+++ More information

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

