Master Configuration Chaining

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

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.

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.

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.

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.

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.

• Figure A 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.
• Figure B 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.
• The variation formatter is referenced in the master configuration of the Burger menu variant, see figure C, and in that overwrites the corresponding standard formatter.
• In order to make the Burger menu work, also a special dynamic function header-config  is needed as one can see in figure D. 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 in figure D. Plugins are described in one of the next chapters.

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 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.

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:

• advanced usage of element settings with Element setting overrides
• add additional CSS resources and JavaScript resources for individual sites with the help of Site plugins
• simplify page editing for users with the Add content restrictions technique