\documentclass{article} \usepackage{ulem} \usepackage{graphicx} \usepackage{hyperref} \pagestyle{headings} \begin{document} \part{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 \textit{Options} button in the top menu bar. There is also direct access to the individual applications' preference interfaces through the expandable \textit{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 \texttt{config/prefs.php} file. This file contains two sections. \section{Preference groups} The first section which defines the \texttt{\$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 \texttt{\$prefGroups} entry defines one group by setting \begin{itemize} \item the internal (arbitrary) group identifier (the key of the \texttt{\$prefGroups} array, i.e. the "identities" in \texttt{\$prefGroups['identities']} \item the group header ('label') \item the group description ('desc') \item and the preferences that should belong to that group ('members') \end{itemize} You can change any of these settings according to your needs but please note a few things: \begin{itemize} \item Some group identifiers or less arbitrary than others, especially the 'identities'. Only change group identifiers if you really have to. \item 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). \item Preference groups may be empty in the interfaces under certain conditions. You can remove or comment out that \texttt{\$prefGroups} then. \end{itemize} 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. \section{Individual preferences} The second section of the \texttt{prefs.php} files contains the definitions of the individual preferences, as specified in the \texttt{\$\_prefs} variable. Generally each entry in \texttt{\$\_prefs} is associated with a user setting, but there are a few exceptions. The following settings define how a preference work: \begin{itemize} \item The key (e.g. "theme" in \texttt{\$\_prefs['theme']}) is the unique identifier of the preference. This is how the preference will be referenced anywhere in the Horde code. \item '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. \item 'locked' allows to keep users from changing this preference. Set it to \texttt{true} to not show this preference in the interface. This has no effect on 'link' type preferences. \item 'shared' defines whether the preference is available to all Horde applications, see "Scope" below. \item 'type' specifies the type of preference. There is a limited set of types available, see the table below. \item 'enum' provides the list of possible preference values for preferences of the 'enum' type. \item 'escaped' sets for enum or select type preferences whether the keys and values are already html-escaped. Defaults to false if not present. \item 'hook' sets whether a hook function should be called to get the default value for that preference, see Hooks below. \end{itemize} \subsection{Valid preference types} Preference type & Explanation \\ \hline checkbox & Provides a checkbox. \\ \hline enum & Provides a selection list in the UI, list is specified in the associated 'enum' setting. \\ \hline implicit & Provides storage for 'special' types. \\ \hline link & Provides a link to another data entry form. \\ \hline number & Provides a 3-character textbox to enter a natural number; syntaxcheck is performed after data entry. \\ \hline password & Provides a textbox for password entry. \\ \hline select & Provides a selection list in the UI that is built in lib/prefs.php. \\ \hline special & Provides an UI widget. \\ \hline text & Provides a single-line textbox. \\ \hline textarea & Provides a multi-line textbox. \\ \hline
\subsection{Valid default values} Preference type & Value format \\ \hline checkbox & 0 or false for unchecked, 1 or true for checked \\ \hline enum & Preselected item from associated enumeration \\ \hline implicit & Depends on the individual preference \\ \hline link & Not used \\ \hline number & Number value, integer or float \\ \hline password & Should be '' \\ \hline select & Preselected item from associated selection list \\ \hline special & Not used \\ \hline text & Text value, e.g. string in single quotes \\ \hline textarea & Text value, e.g. string in double quotes, lines separated with "\textbackslash\{\}n" \\ \hline
\section{Scope} \section{Preference values} Preference values are cached in the user's session. This means that default value changes in the \texttt{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 \texttt{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 = '' AND pref\_name = ''
\subsection{Default values} \subsection{Hooks} \section{Identities} \section{More information} See CustomizingPreferencesH3 for a number of user-contributed preference settings and hooks. \end{document}