OpenCms documentation
OpenCms documentation

Element settings

Element settings change the formatting of a content with a formatter without changing the content or the formatter itself. The available settings declared and configured in the formatter configuration and an editor can use the settings to adjust the way content is rendered.

In OpenCms contents are rendered by formatters when dropped on a page. If you like to have different formats of a content, you can write and configure different formatters for the same type of content. But, if you want the editor to adjust the behavior of a single formatter, you can use element settings. This is useful for providing, for example, various facets of nearly the same format.

Assume, you have some content type having a title. Now a setting could enable the editor to choose the level in which the headline is shown (h1, h2, h3 ...)—or if it should be shown at all.

The editor can change the element setting directly at the content in the page editor. The chosen value can be evaluated in the content's formatter via special JSP API.

In the page editor, the element options (edit point  at the element) show a gear wheel () that opens the element settings dialog.

The element settings dialog

The dialog has various sections, not all present every time. The settings we talk about here, are the ones in the "Settings" section. These are the ones configured for the formatter. As you see, the developer can configure various widgets for those settings to ease the editors task.

Just for completeness, we provide an overview on the different sections of the settings dialog here:

Template model options

Here you can choose what should happen to the element if the container page is copied. If the single option in this section is checked, the content will be copied with if the page is copied (in a respective copy mode for containerpages).

Formatters

If more than one formatter is available for the content in the container it is placed in, here the formatter to use can be selected. Depending on the selected formatter, the "Settings" section provides different options, i.e., the one supported by the chosen formatter.

Settings

Here the settings supported by the chosen formatter are displayed.

Show in device

This section only appears if a template context provider is configured. Here you can adjust for which devices the content should be displayed at all.

Element settings in the content editor

It is possible to make element settings editable in the form-based content editor instead of accessing the settings via the gear wheel in the page editor. In order to do so, the developer has to check the option "Show element settings in content editor" in the first tab of a formatter configuration.

Formatter configuration: Show element settings in content editor

To provide element settings, they have to be configured in the formatter configuration. In the tab "Supported settings" you can add and configure them:

Configuration of element settings in the formatter configuration
For dynamic functions, element settings can be configured the same way in the functions content's tab "Supported settings".
Setting name

The name of the setting under which it can be accessed in the formatter

Include name

Optional reference to a pre-configured setting in the common settings provided via the "Setting defaults" editor field. See the topic about common settings for more information.

Display name

The name shown to the editor in the settings dialog. This can be localized using the %(key.) macro referencing a message key in a workplace bundle. See the localization topic for more information.

Description

An additional description of the setting for the editor. If set, a question mark symbol appears in the settings dialog and the editor can see the description when hovering over it. The description can be localized using the %(key.) macro referencing a message key in a workplace bundle. See the localization topic for more information.

Visibility

For default formatters you can ignore this option. Only for display formatters it becomes relevant. See the topic on element settings for display formatters for more information.

Widget

Select the widget that should be used for displaying the element setting in the settings dialog. Dependent on your OpenCms version, differently many widgets are available. Widgets are very similar to the widgets in the content editor. Hence, see the topic about these widgets to get more information on the widgets and there configuration.

Widget configuration

Dependent on the selected widget, configuration options can or must be provided. See the topic about widgets for more information.

Rule regex

The values allowed for the setting can be restricted by a (Java) regular expression. If a rule regex is provided, the value entered by the editor has to match the expression.

Rule type

If a "Rule regex" is specified, it can be handled as warning or error. Warnings are only displayed and can be ignored. For errors, the editor is forced to change the value.

Error

The error message displayed if the "Rule regex" is not matched. The value can be localized using the %(key.) macro.

Whilst the approach of defining element settings directly in the formatter is a viable way for smaller templtes, it is highly recommended for larger templates to define element settings in a reusable way by means of Shared element settings.