OpenCms documentation
OpenCms documentation

Master Configuration Chaining

Sitemap master configurations provide sets of content element definitions and formatter definitions and make these definitions available as ready to use and reusable template variants for sites.

With the principle of master configuration chaining inheritance-like techniques get possible for master configurations. It is possible to start with one single master configuration file or even with a combination of several master configuration files and after that reduce, extend or vary selected definitions therein.

Generic templates like Mercury provide diverse possibilities and functionalities that cover the widest possible range of projects. 

For some sites and users the range of possibilites provided might be too much. On the other hand, there is propably no website project where all requirements are covered by a generic template.

With the techniques of master configuration chaining one can customize templates on a granular level. Especially, you can customize the following definitions:

  • content element definitions
  • formatter definitions
  • dynamic function definitions
  • plugin definitions
With the techniques of configuration chaining, you reach a higher degree of compatibility with a generic template. You can especially update to the latest Mercury version at any time while at the same time developing your own Mercury customizations.

A particularly powerful chaining technique is variation by chaining, which depends on the concept of formatter keys introduced in OpenCms 12.

Formatter keys are a replacement for the former formatter IDs and are activated by default since OpenCms 12. 

The idea behind is the following:

There might be projects where a lot of contents already exist in sites and the requirements in respect to HTML Markup rendering are changing over time or diverge completely between sites. In this case it would be inefficient to introduce a new formatter and go through all pages of all sites to re-configure all existing contents using the new formatter.

With formatter keys it is possible to introduce alternative HTML markup rendering for existing contents per site without content re-configuring.

Before chaining gets possible, you have to create a new sitemap master configuration file and have to define the master configuration definitions to start with. You can either start with one master configuration, e.g., with the Mercury standard master configuration as shown below, or with a combination of several master configurations as shown in the example of the last chapter.

Customized Mercury Master Configuration

The master configurations at the very beginning of the Content elements tab represent the stock of definitions to which chaining techniques can be applied.

With the technique of chaining, you can reduce, extend, or vary definitions provided in master configurations.

Reduce the number of formatters provided by adding a formatter to the list of Formatters to be removed in the Formatters tab. The same works for dynamic functions and for plugins in the Dynamic functions tab.

Reduction by Chaining

Extend the number of formatters provided by adding a formatter to the list of Formatters to be added in the Formatters Tab. The same works for dynamic functions and for plugins in the Dynamic functions tab.

Extension by Chaining

Provide an alternative HTML rendering for content elements and apply the rendering to already existing contents of individual sites.

In order to overwrite the standard HTML rendering provided by a template, you have to

  1. define and implement a new formatter that realizes the alternative HTML rendering
  2. give the new formatter the same content type and the same formatter key as the formatter you want to overwrite
  3. in your Sitemap master configuration, add the new formatter to the list of Formatters to be added in the Formatters Tab as described above; this will overwrite the original formatter
  4. include the Sitemap master configuration in the Site configuration where you intend to have the alternative HTML rendering available

The figures below show an already advanced example of variation by chaining from the Mercury template, the Burger Menu variant.

Whilst in Mercury's standard variant, the main menu is rendered in a traditional way with a horizontal bar and vertical drop-down menus, the Burger Menu variant shows the main menu in the form of a fold-out burger menu on the left.

The following figure shows the original formatter of type m-layout-group-simple with key m/layout/group as defined in the master configuration of the Mercury standard variant.

Standard Layout Group Formatter of the Mercury Template

The next figure shows the Burger menu variant formatter. Note that the formatter of the variation has the same type and the same key, m-layout-group-simple and m/layout/group as the standard formatter.

Master Configuration of the Burger Menu Variant

The variation formatter is referenced in the master configuration of the Burger menu variant, see the figure below, and in that overwrites the corresponding standard formatter.

Formatters Tab of the Burger Menu Variant

In order to make the Burger menu work, also a special dynamic function header-config  is needed as one can see in the last figure. The dynamic function of the standard variant is explicitely removed and the dynamic function of the burger menu variant is added.

The Burger menu variant finally needs some extra CSS and JavaScript, which is included with the help of plugins as shown below. Plugins are described in one of the next chapters.

Dynamic Functions Tab of the Burger Variant

Formatter keys in Mercury, e.g. m/layout/group, follow a convention in taking up the path where formatters are stored in the module. Although the path-like structure of Mercury's formatter keys is just a convention, it is common practice that a formatter key bears some sort of semantics.

Semantics are a helpful tool to keep the overview but lead to problems if the name of a formatter key changes over time. Especially if the formatter key is already used by many contents in many sites.

Alias formatter keys are a convenience method if the variation by chaining technique is used frequently and if the names of formatter keys change over time.

Alias formatter keys provide two utilities:

  • contents that configure an old deprecated formatter key, can be rendered with a formatter identified by a new formatter key
  • if contents referencing an old formatter key are saved, the old formatter key is automatically replaced (and saved) by the new one

This chapter explains how to combine, reduce, extend, or vary definitions provided by sitemap master configurations with the techniques of master configuration chaining.

Note that all chaining techniques are not only available for formatter definitions but are available in full also for dynamic function definitions.

We have also shown how one can reach compatibility with alias formatter keys if the names of formatter keys change over time.

In the next chapters we finally introduce some more template variant techniques: