OpenCms documentation
OpenCms documentation

User preferences dialog

Via preferences, users can configure OpenCms according to their 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 one's 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.

Since OpenCms 9.5, the context menu of page and sitemap editor provide a "Preferences" item. Clicking it, the following preferences dialog opens:

The user 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 users to change their 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 extendable: New settings can be added and will be shown directly in the dialog
  • It is easier to access for content editors: It is integrated in the ADE surface and it is unnecessary to open the traditional workplace .

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>

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:

basic

The preferences in the basic tab are shown in the "Basic preferences" tab of the preferences dialog. Here is 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 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.

For a single preference name, a nice name, a description, the default value, the used widget plus configuration, a validation for values and an appropriate error message can be specified. While the preference's name is mandatory, the other options are optional.

name (required)

Name of the preference. The name is used internally as an 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 name attribute 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.

TODOs: Improve - does the interface maybe change?

The default user preferences are used by OpenCms to configure its behaviour according to the user's choices. At least when you add your own preference, you may want 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 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 in the same way, i.e., via the constructor CmsWorkplace(PageContext context, HttpServletRequest req, HttpServletResponse res).

OpenCms provides user information and settings at two different places. One place is 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.

In 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 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 a 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