\documentclass{article}
\usepackage{ulem}
\pagestyle{headings}
\begin{document}
\tableofcontents

\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 \textsl{Options} button in the top menu bar. There is also direct access to the individual applications' preference interfaces through the expandable \textsl{Options} menu entry in the left menu bar. Whether these buttons appear and under which condition can be configured by the administrator in Horde&#039;s configuration\footnote{http://example.com/index.php?page=Doc/Admin/Config/Horde}. 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}
\begin{tabular}{|l|l|}
\hline
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
\end{tabular}
\subsection{ Valid default values}
\begin{tabular}{|l|l|}
\hline
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 "\\n"\\
\hline
\end{tabular}
\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:

\begin{verbatim}

DELETE FROM horde_prefs WHERE pref_scope = '<application_name>' AND pref_name = '<preference_name>'
\end{verbatim}

\subsection{ Default values}
\subsection{ Hooks}
\section{ Identities}
\section{ More information}
See CustomizingPreferencesH3\footnote{http://example.com/index.php?page=CustomizingPreferencesH3} for a number of user-contributed preference settings and hooks.

\end{document}
