OpenCms documentation
OpenCms documentation

Element Setting Overrides

In the last chapters we have seen how chaining techniques can be used in master configurations to customize formatter definitions and dynamic function definitions for sites.

In the area of reusable template variants, similar variation techniques are available on the level of element settings, called Element setting overrides.

Element setting overrides are introduced in OpenCms 13 and build upon the techniques of Element settings and Element setting defaults (Shared Element settings) available before OpenCms 13, 

Element settings define the configurable aspects of a content formatter.

An HTML section formatter, for example, might sometimes display an image left of the text and sometimes on the right.

The option to display an image on the left or on the right is a typical element setting.

Note that element settings are stored per content ocurrence on a page. This means, even if one and the same content occurs multiple times on one page, each content on this page can store its own element settings.

Element settings are explained in more detail here.

The following figure shows the element settings as available for Mercury's Text and image formatter that renders a Mercury section content.

Available Element Settings of Mercury's Text Image Formatter

Regarding template variants, Element setting defaults are the equivalent of Sitemap master configurations on the level of formatters:

  • you define the configurable aspects of a whole template with a Sitemap master configuration and you can reuse master configurations in sites
  • you define the configurable aspects of content formatters with Element setting defaults and you can share Element setting defaults between content formatters

Element setting defaults are a helpful tool. Although different contents such as sections, FAQs, events, or contact information express different structures and semantics, they all follow a uniform design when displayed on a page. Element setting defaults help to reach a unique display for diverse content types.

Read more about the technical background of Shared element settings here.

With Element setting overrides you can maximize reusability of content formatters. You can take over all the Element setting defaults of a modular template and change only those details you like to be different in your template variant.

The overrides technique is similar to those of master configuration chaining since you can reduce, extend, or vary element setting definitions.

Element Setting overrides has actually the same content type Shared Settings as Element setting defaults. They differ in where they are included. Whilst element settings defaults are included by a formatter, Element setting overrides are included in master configurations.

The figure below shows the place where to include an Element setting overrides file in a sitemap master configuration.

Element Setting Overrides in the Master Configuration Editor

Here are some examples what you can do with Element setting overrides.

As one can see in the figure above showing the element settings of the Mercury Text image formatter, the list of element settings available can be very long in modular templates.

Depending on your project, you might want to create a template variant, where the number of choices is drastically reduced.

You can disable an element setting with an Element setting overrides file by choosing the hidden value for a specific Widget field.

An element setting can be disabled for all formatters at once or for selected formatters only. If the override shall apply for selected formatters only, select them with the Formatter key field in the Shared element settings file.

Hidden widget configuration in an Element setting overrides file

As with whole element settings, also element setting values can be reduced.

Mercury, for example, allows to display links in section contents as text or as buttons. You might create a template variant where it is not possible for content editors to select the button option.

In this case, use the Widget configuration field in your Shared settings file to redefine element setting values for your template variant.

As with all element setting overrides, the values can be overwritten globally for all formatters or for selected formatters only

Mercury in many situations makes more or less arbitrary design decisions, for example, in displaying links by default as a button when given in a section content.

In order to define standard element setting values in a template variant from the outset, use the Default value field in the Element setting overrides file to change the default display behaviour.

Adding CSS wrapper classes to content elements

The probably most flexible Element setting overrides technique is to introduce new CSS wrapper classes to formatters.

It is common practice that a formatter wraps its content with one outer HTML DIV element that additionally holds HTML class names informing about the start of a specific content element type.

Mercury's section content, for example, is wrapped by an outer HTML DIV element including the element and type-section classes.

<div class="element type-section">
...
</div>

By referencing Mercury's cssWrapper.default element setting one can extend the list of class names, for example, to:

<div class="element type-section type-section-variant">
...
</div>

The additional class names can then be used to introduce individual CSS designs or additional JavaScript functionality for content formatters.

In this chapter we have shown how to build template variants with Element setting overrides.

The possibilities of how you can unify or vary the display of a site with Element setting overrides are manifold.

Four typical examples were shown: reducing the element setting definitions of a modular template, reducing defined element setting values, changing element setting default values and introducing CSS wrapper classes.