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.
Motivation
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
Formatter Keys
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.
Prerequisites
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.
Reduction by Chaining
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.
Extension 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.
Variation 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
- define and implement a new formatter that realizes the alternative HTML rendering
- give the new formatter the same content type and the same formatter key as the formatter you want to overwrite
- 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
- 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 keym/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
andm/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.
Alias Formatter Keys
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:
Summary
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