OpenCms documentation
OpenCms documentation

Mappings and defaults with macros

Sometimes, it is useful, to

  • set the default value of a content element similar to another element or
  • use information from the page where the content is placed to set the default.

A particular use case is an element that is mapped to the title property or the gallery name of some content. Usually, it suffices to choose the headline of a piece of "text" content, or some information about the page where the content is placed. But sometimes the title property should be set manually.

We explain which macros are available to set default values in an XSD and state a use case, mapping the default values to the title property and the gallery name of some content.

To identify content in the "Add wizard" of the page editor or in the workplace, a meaningful gallery name (used in the "Add wizard") and a title property (shown in the workplace) are essential. To obtain suitable values, it is common to map a content element to the title property (and the gallery name. Note: We will say only title property below, but we also mean gallery name.).

For example, in an article with a headline, the headline may be a good title property. But, sometimes the headline is not meaningful enough. For example, you may have a page named "My great experiment" and another page "My other great experiment". On both pages you place an article with the headline "Most suprising insights". Mapping only this headline to the title property is not satisfactory in this particular setting. Another solution is preferable: OpenCms allows you to place the page title in front of the heading. Here is an example XSD that demonstrates it:

<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified">
	
  <xsd:include schemaLocation="opencms://opencms-xmlcontent.xsd"/>

  <xsd:element name="Textblocks" type="OpenCmsTextblocks"/>
	
  <xsd:complexType name="OpenCmsTextblocks">
    <xsd:sequence>
      <xsd:element name="Textblock" 
                   type="OpenCmsTextblock" 
                   minOccurs="0" maxOccurs="unbounded"/>
    </xsd:sequence>
  </xsd:complexType>

  <xsd:complexType name="OpenCmsTextblock">
    <xsd:sequence>
      <xsd:element name="Title" type="OpenCmsString" minOccurs="0" />
      <xsd:element name="Headline" type="OpenCmsString" />
      <xsd:element name="Text" type="OpenCmsHtml" />
    </xsd:sequence>
    <xsd:attribute name="language" type="OpenCmsLocale" use="required"/>
  </xsd:complexType>

  <xsd:annotation>
    <xsd:appinfo>
      <mappings>
        <mapping element="Title" mapto="property:Title" useDefault="true" />
        <mapping element="Title" mapto="galleryName" useDefault="true" />
      </mappings>
      <defaults>
        <default element="Title" 
                 value="%(page_title)%(no_prefix:: )%(value:Headline[1])" resolveMacros="false" />
      </defaults>
    </xsd:appinfo>
  </xsd:annotation>

</xsd:schema>

There are several interesting spots in the XSD:

  • The optional Title element
  • The two mapping entries
  • The definition of the default value for the Title element

The optional Title element is the one mapped to property:Title and galleryName. The important fact is, that the <mapping> node has set the attribute useDefault="true". This setting forces the default value defined for Title to be mapped to the Title property even if the element itself is not present.

To set default values for the Title element that fit for the actual content, special macros are used:

  • The %(page_title) macro inserts the title of the page where the content is placed.
  • The %(no_prefix:) macro places its body value, ": " in the example, only if a prefix exists, i.e., if the %(page_title) macro expands to a non-empty string in the example.
  • The %(value:) macro takes an XPath to an element of the content and expands to the value of this content.

The use of resolveMacros="false" in the <default> node is necessary to get the whole mapping working. If not set, the macros are resolved too early and will all expand to the empty string.

In case the optional Title element is added to the content via the content editor, the default value with unresolved macros is displayed and can be adjusted. The content editor can also use the macros when editing the value.

Macros for content-specific default values

The following macros are available to set content-specific default values.

%(page_title)

If the content is placed exactly at one page, the macro expands to the Title property of this page. Otherwise, it expands to the empty string.

%(page_nav)

If the content is placed exactly at one page, the macro expands to the NavPos property of this page. Otherwise, it expands to the empty string.

%(no_prefix:{string})

If the macro is expanded at the beginning of a string, it expands to the empty string. Otherwise, it expands to the value given as {string}.

%(value:{XPath})

The macro expands to the value of the current content element that is accessed via the given {XPath}.

Note that there are more macros. In particular you can use the %(key.{message key}) macro to provide localized, but not content specific default values.

For more available macros, see the constants in the CmsMacroResolver.

The configuration of the mappings and the default values can also be done with the preferable field-centered syntax, introduced in OpenCms 11, using the <FieldSettings>-node.