OpenCms Documentation

Common element settings

 Show GitHub edit links  Hide GitHub edit links
In OpenCms since: 11.0.0 Valid for OpenCms: 11.0.0

Since OpenCms 11 it is not necessary to configure frequently used element settings in every formatter, which they are used in. Once described in one configuration file, all element settings are accessible by calling their setting names.

Some element settings are needed in a number of formatters without any or little changes. To avoid the work to configure each time they are used, OpenCms allows you to define the element settings in one configuration file. Then, you can call the settings from your formatter in a few easy steps.

An often used element setting

It is very convenient to configure elaborated element settings only once. Here, we provide to choose the wanted date format in the element settings. Then, this element setting can be used by any formatter.

Create a configuration file

First, you need to create a configuration file for the common element settings. This can be done in the explorer view. There you can add via  "Add-Wizard" a new resource of the type "Predefined element settings" under the item "Configurations" in the dropdown list.

Fig. [commonsettings_addwizard]: Add a new resource via Add Wizard

In this file you can add a new element setting as described here.

Fig. [commonsettings_configurationfile]: Configuration file with one element setting (dateFormat)

Usage of the common element settings

Now the element setting can be used in the tab "Supported settings" of any formatter configuration simply by using the Setting name. Remember to link to the configuration file to make the default element settings available.

Note: The other fields are not required, unless you want to change the default values as shown in the demo.
Fig. [commonsettings_formatterconfiguration]: Tab "Supported Settings" in a formatter configuration

Now the configured element setting is available in the "Element settings" window, which you can open at the gear wheel , which appears when you hover over the edit point .

Fig. [commonsettings_elementsettings]: Window of the element settings

Field "Include name"

Sometimes, it is desired to have two slightly different element settings. But for reasons of consistency they shall have the same Setting namein the formatter configuration, with which you call them in your JSP. Applied to the example above, you can limit the number of date formats to select, and still call the shortened list with the same EL annotation. This is enabled by the field Include name in the formatter configuration.

At first, the alternative element setting is added to the configuration file.

Fig. [commonsettings_modconfigurationfile]: Configuration file with modified element setting added

The modified element setting can now be included to the formatter configuration by setting its name to the field Include name.

The setting name given in the formatter configuration determines how the element setting is called in your JSP. Note, that in this case, it is the same as the one above.
Fig. [commonsettings_modformatterconfiguration]: Include name to use modified element setting

The dropdown menu for the date format in the window "Element settings" now shows less options to choose, but in both cases, in the JSP the element setting is called by the annotation ${cms.element.settings.dateFormat}.

Fig. [commonsettings_modelementsettings]: Element settings with a limited number of choices

You can improve this page

Please contribute your suggestions or comments regarding this topic on our wiki. For support questions, please use the OpenCms mailing list or go for professional support.