With the introduction of nested containers in OpenCms 9.5 it became possible to build up a website from layout elements and "real" content element, that render text or images. In particular in combination with responsive design frameworks this technique proved to be very powerful. But to wrap the full flexibility of a responsive design framework in your template, you either had to write very complex formatters, or dissect your contents into very tiny snippets and loose semantical relations, or force the editor to place the same content several times but rendered with different formatters on the same page. Macro formatters takle that problem. They allow to write several "normal" formatters that only render parts of a content and glue them together in the macro formatter.
Macro formatters are a special content type introduced in OpenCms 10. They allow to build a new formatter from existing ones. Macro formatters basically glue "normal" formatters together by arranging their output in an HTML structure, referencing each individual formatter via a macro. Moreover, they accumulate all element settings of the individual formatters and support additional settings as well.
We assume a content with image, text and headline. Moreover, we have three basic formatters. One solely outputs the headline, one the image, one the text. All three formatters are disabled by default, such that they can not be used directly. The only formatters we want to use are macro formatters. These can combine one up to all three of the basic formatters.
For basic configuration and supported settings, refer to documentation of the formatter configuration. The options from the macro tab, we discuss below.
Fig. [macro_tab] shows the tab for the macro definition.
To define the macro, wee add the formatters that we want to use in the macro and declare a name for them - here it's one for headline, one for text and one for image. Then you write the macro HTML snippet with a
%(formatter_name) used whereever the formatter with name
formatter_name should be rendered. Additionally to
%(formatter_name), we can use
%(settings.settingname) to read element settings defined in the "Supported settings" tab.
<div>or other block element to be displayed correctly.
Macro formatters build a new layer of abstraction. The target is to reduce development complexity. Once suitable formatters for special content parts (text, image, headline, ...) are defined, they can easily be combined. Writing JSPs is only necessary for that basic formatters - and even these will become less complex. The combination of the basic formatters requires solely HTML and some macros. Hence it can be done by differently skilled persons as well. Thus, you are enabled to define the set of customer specific formatters easily from a set of basic formatters that may be reused.
Hiding basic formatters bears an advantage. Basic formatters do not need a surrounding <div> if not used directly. Hence, output is even more flexible. You may benefit from that flexibility when writing the macro formatters.
Name element settings of the basic formatters suitable. All element settings of the basic formatters will also be available in the macro formatter. So name them suitably, e.g., prefixing them with "Headline", "Image", "Text" etc. An example for suitable naming is shown in Fig. [element_settings].