Mappings and default values

Mappings automatically generate metadata for a content so that a content is easy to find in different locations, for example in the Explorer or in the Galleries. Mappings can be done with the help of macros. The same macros can be used to define default values for content fields.

Usage

Mappings and default values are defined per field in the <FieldSettings> section of a content schema.

The example below maps the value of the Title field to the title property, see the <MapTo>propterty:Title</MapTo> element.

If the title field has no value, a default value from a message bundle is mapped, see <Default>%(key.type.section.title)</Default>.

<xsd:complexType name="OpenCmsContentSection">
	<xsd:sequence>
		<xsd:element name="Title" type="OpenCmsString" />
	</xsd:sequence>
	<xsd:attribute name="language" type="OpenCmsLocale" use="required" />
</xsd:complexType>

<xsd:annotation>
	<xsd:appinfo>
		<FieldSettings>
			<Setting>
				<PropertyName>Title</PropertyName>
				<Default>%(key.type.m-section.title)</Default>
				<Mapping>
					<MapTo>property:Title</MapTo>
					<UseDefault>true</UseDefault>
				</Mapping>
			</Setting>
		</FieldSettings>
	</xsd:appinfo>
</xsd:annotation>

Property Mappings

Property mappings in newer version of OpenCms are locale specific. If there is a property named Title and in addition two locale specific properties named Title_de and Title_fr, then the locale specific value of the mapped field would be written to the respective locale specific property.

The locale specific mapping only works, if a locale specific target property definition such as Title_de has been created.

Available Macros

Macros dynamically generate values from various sources:

from the content itself: for example, the title of a content section can automatically become the title metadata of the content through a mapping, or the default value of a content field can be taken from another content field
from the context in which the content appears: in this way, for example, the page title on which a content section is placed can be added to the title metadata
from static labels
from external sources: for example, texts from localized message bundles

Macros can also be combined to form an extended mapping or default value.

%(value:{XPath}): The macro expands to the value of the current content element that is accessed via the given {XPath}.
%(key.{message key}): The macro expands to the localized message with the given message key.
%(page_title): If a 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 a 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}.

There are more macros available, see the CmsMacroResolver.

Example: Setting the title property and the workplace gallery name

To identify a 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 explorer) are essential. To obtain suitable values, it is common to map a content element to the title property.

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>
      <FieldSettings>
        <Setting>
          <PropertyName>Title</PropertyName>
          <Default>%(page_title)%(no_prefix:: )%(value:Headline[1])</Default>
          <DefaultResolveMacros>false</DefaultResolveMacros>
          <Mapping>
            <MapTo>property:Title</MapTo>
            <UseDefault>true</UseDefault>
          </Mapping>
          <Mapping>
            <MapTo>galleryName</MapTo>
            <UseDefault>true</UseDefault>
          </Mapping>
        </Setting>
      </FieldSettings>
    </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> element has set the option <UseDefault>true</UseDefault>. 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 <DefaultResolveMacros>false</DefaultResolveMacors> option along with the <Default> element 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.