Sitemap Attributes

Modular and highly configurable templates like the standard OpenCms template Mercury provide an overwhelming set of configuration options, not only for developers, but also for editors.

If you create a website with such a modular template, a good preset for options has to be choosen by developers and a limited set of the options might be left for responsibility of the editors. That configuraiton is what sitemap attributes are made for. Via sitemap attributes can change editor widgets, element settings and formatter behavior. Moreover, you can choose if editors should be able to change a setting, or if only developers can.

Motivation

A modular template like the OpenCms template Mercury is highly adjustable to specific needs and easily extendable. If used for multiple websites for different customers, configuration canges according to the customers needs are necessary. For example:

The template's contents feature an element setting ("CSS selectors") for adding classes to the class attribute of the HTML output's surrounding tag. For one customer, one set off classes should to selectable, for the next another set and for the it should be possible to type in class names as plain string. Maybe even the setting "CSS selectors" should be renamed, e.g. to "Background color" for a specific use case.
The template's contents are partly editable via an WYSIWYG editor. The editor has a configurable set of options. One customer wants one option set, the next another. So technically the widget configuration in the content's XSD needs to be adjusted.
Mercury by default is upgradable. But this means that third-party CSS and JavaScript add-ons must be limited. What if a customer needs such adjustments? He can get it, trading the options against updateability. A sitemap attribute can switch to the variant of the template and the template JSP's code will allows to include third-party styles and JavaScript into the template.

Adding Sitemap Attributes

Sitemap attributes are just key-value pairs added in master sitemap configurations or sitemap configurations. Open the configuration in the Attributes tab and just enter them. The values can be lengthy, dependent on there use case.

By now, only key-value pairs are defined. Values defined in a master configuration are inherited and can be overwritten in the sitemap configuration.

The master configuration should provide the defaults. Most of the configuration is done here. Keep in mind that you can also have multiple (stacked) master configurations if you need different preconfigured template variants.

The sitemap configuration should only be used for adjustments that are really site specific or that should be left to the editors of the site.

In master sitemap configurations, an additional option is available: Attribute editor configuration. Here you link to a configuration file that allows to expose some sitemap attributes to editors for editing without editing the sitemap configuration directly. Instead, an additional dialog for editing the attributes values is configured. Details on the attribute editor are found below.

Up to now, we have only configured key-value pairs. What makes the attributes effective, is how we access and use them in schemas, formatter configurations and JSPs. That's what we see next.

Accessing sitemap attributes

OpenCms provides easy access to sitemap attributes in

JSPs
schemas of content types
formatter configurations.

Sitemap attributes in JSPs

Here's how you can access the sitemap attributes in template JSPs or formatter JSPs. We check for the template.variant attribute and save it's value with a default in the variable templateVariant:

<%-- Get the sitemap attributes map --%>
<c:set var="siteAttribute"   value="${cms.sitemapConfig.attribute}" />
<%-- access a sitemap attribute --%>
<c:set 
	var="templateVariant" 
	value="${siteAttribute['template.variant'].isSetNotNone 
				? siteAttribute['template.variant'].toString 
				: 'default'}"
/>

Sitemap attributes in XSDs

XML schema definitions (XSD) in OpenCms define not only the structure of a content, but also how the content is shown in the content editor, e.g. which widgets are used, which default values are added, how input is checked for errors etc. The behavior can be configured in the XSD via field settings.

In most of the configuration options, macros are allowed and OpenCms supports the macro %(attribute:name:default) to access sitemap attributes. If, in the current context, the sitemap attribute with the given name is present, it resolves to the value of this attribute. If it is not present, the default value is taken. The default value is optional, but recommended here. Note that the sitemap attribute's value again can hold another macro.

Here's an example where the HTML widget for the Text editor field is configured. The macro is used in the <WidgetConfig> node:

<!-- ... Fieldsetting configuration for the Text element in an XSD -->
<Setting>
	<PropertyName>Text</PropertyName>
	<DisplayName>%(key.label.Text)</DisplayName>
	<Widget>html</Widget>
	<Default>%(key.msg.default.new.Text)</Default>
	<WidgetConfig>%(attribute:editorConfigFull:%(param:editorConfigFull))</WidgetConfig>
</Setting>
<!-- ... -->

In the example, the fallback valud for the sitemap attribute is another macro: %(param:editorConfigFull). The %(param) macro is part of a mechanism to provide configuration values globally to your OpenCms installation and works similar to the %(attribute) macro.

Sitemap attributes in formatter configurations

In formatter configurations, element settings for formatters can be configured. For the configuration, sitemap attributes can be accessed in via the same macro as used in XSDs. Here's an example from the Mercury template, as configured in the shared settings and used for each content type provided with the template:

Here the macro %(attribute:name:default) is used in multiple editor fields. Here it is especially important the the attributes value can hold macros again to get for example localized display names even when using the attribute.

The sitemap attribute editor

Sitemap attributes are a very powerful tool and not all of them should be changeable by normal editors. But for some attributes it would be beneficial if editors can change them. Of course, in an easy way.

In the recommended OpenCms configuration, the sitemap configuration can only be edited by users with the role template developer. But this would prohibit editing of sitemap attributes completely for normal editors.

To make sitemap attribute editable by editors, you have to create a file of type "Sitemap attribute editor configuration" and link to it under "Attribute editor configuration" in the master sitemap configurations tab "Attributes", as you can see in the screenshot in the section about adding sitemap attributes.

Once at minimum one of the attributes is configured in the linked configuration, the sitemap editor will show a context menu option "Sitemap attributes":

If you click the option, a dialog, similar to the element settings or properties dialog, opens, where configured sitemap attributes can be edited.

In the Mercury template as configured for the default OpenCms demo you can choose the default icon set:

Sitemap attribute editor configuration

The sitemap attribute editor configuration is best placed directly besides the master sitemap configuration it is linked to. The content consists of a series of attribute configurations.

Here's the example from the Mercury template that corresponds to the dialog shown above:

Configuration is similar to the configuration of element settings.

Note that, if you stack master configurations where multiple such configurations link to sitemap attribute editor configurations, the configurations are not combined, but replaced.