The idea of element settings
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.
Dealing with element settings as editor
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:
Sections of the element settings dialog
- 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).
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.
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
Configuration of element settings
To provide element settings, they have to be configured in the formatter configuration. In the tab "Supported settings" you can add and configure them:
Options for a single element setting
- 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.
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.
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.
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.
The error message displayed if the "Rule regex" is not matched. The value can be localized using the %(key.) macro.
Advanced topics on element settings
Besides the configuration of element settings explained here, you might be interested in:
- Using common element settings just included for various formatter configurations.
- Showing element settings of display formatters with the settings of the list, showning the contents.
Moreover, above a feature to show element settings in the content editor is mentioned. It is configured in the formatter configuration's first tab by checking the option "Show element settings in the content editor".