OpenCms Documentation

Sitemap Master Configurations

Sitemap master configurations are reusable configuration files that bundle information about all configurable aspects of a template (available content elements, formatters, element settings, etc.).

With Sitemap master configurations you can create template variants, where you start with one generic template configuration that suits for all your customers sites, and further create variants that are optimized for the needs of singular or groups of customer sites.

It is especially possible to start with Mercury as the generic template and create Mercury variants with the help of master configurations.

Sitemap Master Configurations vs. Sitemap Configurations

Sitemap master configurations are very similar to standard sitemap configurations. They define which

  • content elements
  • formatters
  • dynamic functions
  • property definitions
  • attributes

are available on a site.

The following figure shows a sitemap master configuration opened in the editor.

Fig. [sitemap-master-configuration]: Sitemap master configuration opened in the editor

While sitemap configurations are stored below the /.content/.config path of a site, sitemap master configurations typically are part of a template module and therein by convention are stored in a subfolder configuration/.

The following overview shows the locations of sitemap configurations and sitemap master configurations in comparison.

├── sites
│   ├── site1
│   │   └── .content
│   │       └── .config (Sitemap configuration)
└── system
    └── modules
        └── my
            └── module
                ├── configuration
                │   └── sitemap.master.xml (Sitemap master configuration)
                ├── elements
                ├── formatters

You create a new sitemap master configuration like any other content in OpenCms. Choose the Sitemap master configuration content type in the create new resource dialog and store it in the configuration/ path of your module.

Fig. [add-resource-dialog]: Screenshot of the Create new resource dialog

Once created, a sitemap master configuration can be reused for any site.

In order to use a sitemap master configuration in a site, enter the VFS path of the master configuration at the very first position of the content elements tab in a sitemap configuration like shown in the next figure.

Fig. [sitemap-configuration]: Screenshot of a site configuration that includes the Mercury master configuration

Sample configuration

The example below shows a sample setup to demonstrate the usage of sitemap master configurations.

├── sites
│   ├── site1
│   │   └── .content
│   │       └── .config (group1)
│   ├── site2
│   │   └── .content
│   │       └── .config (group2)
│   └── site3
│       └── .content
│           └── .config (all)
└── system
    └── modules
        └── my
            └── module
                └── configuration
                    ├── sitemap.master.content.common.xml
                    ├── sitemap.master.content.domain.xml
                    ├── sitemap.master.content.customer.xml
                    ├── sitemap.master.formatter.bootstrap.xml
                    ├── sitemap.master.formatter.foundation.xml
                    ├── sitemap.master.formatter.tailwind.xml
                    ├── sitemap.master.group1.xml
                    ├── sitemap.master.group2.xml
                    └── sitemap.master.all.xml
  • sitemap.master.content.common defines a set of generic content elements as provided by Mercury and relevant for many sites (article, section, FAQ, etc.)
  • sitemap.master.content.domain and sitemap.master.content.customer define domain specific and customer specific content elements

These three master configuration files provide basic content elements – generic elements as well as domain specific elements – but it is not yet specified how the defined content elements will be rendered.

For this purpose, the sample shows three master configurations defining formatters

  • sitemap.master.formatter.bootstrap
  • sitemap.master.formatter.foundation
  • sitemap.master.formatter.tailwind

where each formatter uses its own CSS framework.

The last three master configurations sitemap.master.group1, sitemap.master.group2, and sitemap.master.all of the sample do not define any formatters nor content elements but are grouping master configurations. They combine a set of content elements and formatters defined in other master configurations into one and provide the combination as a ready to use and reusable template variant for sites.

The following figure shows, as an example, the Group 1 Master Configuration sitemap.master.group1, which combines common content elements and domain specific content elements with the bootstrap sample formatters.

Fig. [sample-master-configuration]: Sample Master Configuration

Summary

This chapter explains the basic usage of master configurations, especially:

  • define sets of content elements, formatters or dynamic functions independent of each other
  • combine the definitions of multiple master configuration files into one and reuse it in sites

In the next chapter, we will learn about advanced chaining techniques of master configurations that go beyond the possibilites shown here:

  • include another master configuration and limit it's definitions (reduction by chaining)
  • include another configuration and extend it's definitions (extension by chaining)
  • include another configuration and overwrite one or more of its definitions (variation by chaining)