Via preferences, a user can configure OpenCms according to his needs. For example, workplace language, project, site and folder displayed on login can be configured. But also various other settings are available. Since OpenCms 9.5, the context menu of page and sitemap editor provide access to a dialog for changing the preferences.
The preferences available can be configured for each OpenCms installation separately. This allows for example to add own user preferences. Here we explain how to configure user preferences and how to access them in a JSP. We explain differences between user preferences and the additional information that can be attached to a user account.
1 The preferences dialog
Since OpenCms 9.5, the context menu of page and sitemap editor provide a point "Preferences". Clicking it, the following preferences dialog opens:
Tabs of the preferences dialog
- Basic preferences
Holds the most important user preferences.
- Extended preferences
Holds preferences that solely affect the traditional workplace. For content editors this workplace is more and more redundant and thus the settings are not important for most users. Furthermore, they can typically also be set via the preferences dialog of the traditional workplace.
- Account
Shows account information and allows a user to change his password.
Most of the settings that are available in the default configuration are also available via the preferences dialog of the traditional workplace. But the new dialog provides several advantages:
- It is configurable: Settings can be sorted and the tab in which they appear can be choosen
- It is extendible: New settings can be added and will directly be shown in the dialog
- It is easier to access for content editors: It is integrated in the ADE surface and it is unneccessary to open the traditional workplace .
2 Configuration of user preferences
User preferences are configured in the opencms-workplace.xml in the sub-folder WEB-INF/config of the OpenCms webapp's main folder on the RFS. The main configuration node is called <default-preferences>. Here's the interesting snippet from the configuration file:
<opencms>
<workplace>
<!-- ... -->
<default-preferences>
<preference-tab name="basic">
<preference name="locale" value="en"
nice-name="%(key.GUI_LABEL_LANGUAGE_0)" />
<!-- ... -->
</preference-tab>
<preference-tab name="extended">
<preference name="allowBrokenRelations" value="false"
widget="checkbox" />
<!-- ... -->
</preference-tab>
<preference-tab name="hidden">
<preference name="workplaceButtonStyle" value="textimage" />
<!-- ... -->
</preference-tab>
</default-preferences>
<!-- ... -->
</workplace>
</opencms>2.1 The tab configuration
The <default-preferences> node has three children of type <preference-tab>. You should know:
- The tab configuration must not be changed.
- The order of the
<preference>nodes inside a<preference-tab>specifies in which order the preferences are displayed.
Since the tab configuration does not directly correspond to the tabs of the preferences dialog, here is some info about the different tabs:
The different preference tabs
-
basic The preferences in the basic tab are shown in the "Basic preferences" tab of the preferences dialog. Here it the right place for preferences that are likely to be adjusted by a user.
-
extended The preferences in the extended tab are shown in the "Extended preferences" tab of the preferences dialog. Here is the right place for preferences that should be adjustable by each user, but who are needed only in rare circumstances.
-
hidden Preferences configured in this tab are not shown in the preferences dialog. Here is the right place for preferences that should not be adjusted directly by a user. The preferences may be necessary to configure the default behaviour of the system. They may also be adjusted automatically for each user.
2.2 Preference configuration
For a single preference name, a nice name, a description, the default value, the used widget plus configuration, a validation for values and an according error message can be specified. While the preference's name is mandatory, the other options are optional.
Attributes of a preference node
-
name (required) Name of the preference. The name is used interally as identifier for the preference.
-
value (optional) Default value of the preference.
-
nice-name (optional) A nice name for the preference. It is displayed in the preference dialog. If not given, the
nameattribute is displayed-
description (optional) Additional information on the preference. It is displayed when hovering over the preference's (nice) name in the preference dialog.
-
widget (optional) The widget used for the preference in the preference dialog. If not configured, the String widget is used. (There are some settings where special widgets are used, e.g., language, project, site and folder selection. These widgets are chosen dependent on the preference
name.)-
widget-configuration (optional) Configuration of the used widget. See here for information on widget configuration.
-
rule-regex (optional) A regular expression, that the value of the preference must match. If another value is chosen, the specified error message is shown.
-
error (optional) The message displayed if the value chosen for the preference is invalid.
In the values of the attributes value, nice-name, description, widget-configuration and error the macro %(key.<MESSAGE-KEY>) can be used for localization. Messages can be placed in any workplace message bundle. So, for your own preferences, you might ship them with one of your own modules.
3 Accessing user preferences
The default user preferences are used by OpenCms to configure its behaviour according to the users choices. At least when you add your own preference, you may want to access to trigger some user specific customization. But you can also use the default preferences and change things depending on their values.
Access to user preferences is gained via an object of type org.opencms.workplace.CmsWorkplace. Call the method getSettings() and the getUserSettings to obtain an object of type org.opencms.db.CmsUserSettings. The object provides getters for all the default user preferences and via getAdditionalPreference(String name, boolean useDefault), additional preferences can be read.
At the moment, scriptlet code is necessary to access user preferences in a JSP. CmsWorkplace is a subclass of the CmsJspActionElement and can be initialized as the same way, i.e., via the constructor CmsWorkplace(PageContext context, HttpServletRequest req, HttpServletResponse res).
4 Preferences vs. additional information at the user object
In OpenCms provides user information and settings at two different places. One place are the user preferences as described above. The other place is the user object with information like name, address, etc., and arbitrary additional information.
While the user object holds the information specific to the user - and usually independent from OpenCms, the preferences hold information about how OpenCms should be configured for the user.
For some cases, it might not be clear where to store user specific information. In particular, the "Additional information" that can be attached to a user and the user defined preferences seem to be equally suitable for some tasks. To help you making the appropriate decision, here are some differences between the two ways of storing user information:
When storing settings in the "Additional information" field of the user object:
- The setting can be edited via the administration view of the workplace
- The user itself typically can neither see, nor change the setting (as long as you don't build your own interface to expose it)
- By default, there are no explicit defaults that can be configured system wide.
Storing information as user preference
- If wanted, the setting is directly integrated in the preferences dialog and the user can change it
- A system-wide default value can be configured easily