Formatters and their configuration

In OpenCms content and layout are strictly separated. To render content of a special content type, several formatters can be provided. Each formatter can be configured to be used according to the container where the content is placed.

We explore the basic structure of a formatter and show in detail how to configure it.

How content is rendered

All HTML rendered in OpenCms is rendered via JSPs. Thus, also the HTML that displays content is rendered via JSPs. A JSP that renders content is called a formatter. A formatter is configured via a formatter configuration. The configuration specifies which content of which type is rendered with which formatter in which containers.

In addition to information about where to use a formatter, the configuration can contain information about special settings available for the formatter. These are called element settings.

When you use the "Add resource type" wizard of the module administration, an example formatter and formatter configuration are generated automatically. Using this wizard is the best option if you create a new content type that is exposed as a resource type.

Location of the formatter and its configuration

Formatters and their configuration are usually shipped with modules and both placed in the formatters/ sub-folder of a module. Since a formatter and its configuration are closely related, they typically get identical names (except for the suffix).

Whether formatters, configurations and content type definitions should be placed in the same module is a design decision where two options may be advantageous:

You can place content type definition, formatters and configurations in one module and make up modules for particular content types. Then you can add and remove the individual content types easily.
You can place content type definitions in a different module than the formatters and configurations. Then you can easily reuse the same content types with a different set of formatters.

Formatter configuration

Formatter configurations are XML content of type "Formatter configuration" (formatter_config). They connect resource types (typically content types) with formatters (JSPs that render the resources).

Adding and editing a formatter configuration

Use the explorer to add and edit a formatter configuration. Navigate to the folder where the configuration should be placed and click "New" -> "Other options" -> "Formatter configuration" to add a new formatter configuration.

The typical name for a formatter configuration is similar to the configured formatter's name. The usual suffix is ".xml".

To edit a formatter configuration right-click on it and choose "Edit". The form-based content editor opens.

Available configuration options

The main purpose of a formatter is to glue content, formatter and template together. Hence the main things to specify (with the formatter configuration's editor fields in braces) are

The type of the resources for which the formatter should be applied ("Resource type")
The formatter (JSP) that should be used for rendering ("JSP").
The containers in which the formatter should be used ("Match" as "Container types" or "Container width")

For specifying in which containers a formatter is used, we strongly recommend to match by "Container types". Containers (see here and here) have a type attribute where you can specify container types (just a comma-separated list of Strings, e.g. "default,center,flexible"). If the formatter configuration lists at least one of the types mentioned there (e.g. default), the formatter can be used for the container, i.e., the content is rendered with the formatter.

Here is an example formatter configuration:

In the tab "Basic configuration", you define the formatter and the type of the resources that are rendered with this formatter. Moreover, you provide a name for the particular formatter configuration, define when to use the formatter and say which head-includes have to be added to make the formatter work.

Options set in the "Basic configuration" tab

Display name: When you select the formatter for a content item, or you add/remove formatters in the sitemap configuration, this name is presented in the select box to identify the formatter.
Resource type: The type of the resources that should be formatted with the configured formatter.
JSP: The formatter to use.
Description: Description of the formatter. It is shown in the element settings of a content when hovering over the question mark next to the chosen formatter.
Rank: Formatters for resources of the same type are ordered by rank. If more than one formatter is available when you place a resource in a page, the formatter with the highest rank is chosen by default. (The choice can be altered manually via a setting that is automatically available for elements that can be formatted with different formatters.)
Match: Match defines in which containers a formatter can be applied. You can either specify containers via their width attribute or via their type attribute. If you choose width, the value specified as "Width" in the formatter configuration corresponds to the minimum width a container must have (set as width attribute), and the optional "Maximum width" specifies the maximum value of the width attribute that is allowed where the formatter is applicable.

We strongly recommend to match formatter to containers via the type.
Display formatter type: If a non-empty value is provided, the formatter is used by the tag <cms:display> by default for resources of that type. If more than one display formatter is present, the rank is used to select the formatter. Moreover, in the tag, a formatter might be specified explictly, overwriting the default.. Moreover, the formatter is added as option in the DisplayTypeSelectWidget. Via the widgets configuration option matchTypes the combination of display formatters can be restricted to the ones that have the same display type set here. This is for example used by the integrated list type and allows you to guarantee mixing only compatible display formatters.
Enabled: Check this option to make the formatter automatically available in the page editor. If the option is not checked, you can make it available via the sitemap configuration.
Search content in container page: If a resource is added to a page, its content may or may not be indexed for the page. If this option is checked and the resource is searchable at all, the page where it is placed will be found when you search for content of that type.
Remove unused nested containers: If checked, nested containers exposed by the formatter, but not rendered on a container page anymore, are deleted when the container page is stored.

Example: You have a row formatter that is configured to have four columns, each exposes a nested container. Now you reconfigure the row to have only three columns and save the container page where the row is displayed on. Then the information on the container of the fourth column is removed in the container page exactly if the option is set.

It is called "Use strict containers" before OpenCms 11.
Use as detail formatter: If checked, the formatter can be used when the resource is rendered in detail view.
Always apply meta mappings: If unchecked, the meta mappings are applied only if that formatter is used on a detail page. See here for details.
Include element settings from display formatters: If checked, element settings of referenced nested formatters are displayed with the settings of this formatter according to the settings configuration. See here for a detailed description.
Show element settings in content editor: If checked, an extra tab is added in the content editor, which allows you to edit the element settings there.
Use for preview: Resources can be previewed in the "Add wizard" or in the workplace's explorer. Check this option if the formatter should be used for such previews.
CSS includes: Add formatter-specific CSS styles here. See here for details.
Javascript includes: Add formatter-specific JavaScript here. See here for details.
Contains nested containers: Check this option if the formatter introduces a nested container. Does not appear anymore since OpenCms 11.

In the tab "Element settings" you can configure Element settings. These settings are shown when you click the symbol at an element that is rendered with the formatter. The content editor can alter these settings to adjust the behavior of the formatter. You can also link to a configuration file with already configured common element settings, which are reused by many other formatters.

In the tab "Meta mappings", you can set which values should be available to the page template as a meta mapping.

Basic formatter

Use the Explorer to add and edit a formatter. Navigate to the folder where the configuration should be placed and click "New" -> "JSP" to add a new formatter.

The typical name for a formatter is somehow related to the name of the rendered resource's type. The usual suffix is ".jsp", but dependend on what the output of the formatter actually is, this can differ. For example, it could be ".css" or ".pdf".

To edit a formatter right-click on it and choose "Edit sourcecode". The source code editor opens.

Here is an example of a typical formatter. It is kept simple but shows typical characteristics of a formatter.

<%@page buffer="none" session="false" trimDirectiveWhitespaces="true" taglibs="c,cms" %>

<cms:formatter var="content" val="value" rdfa="rdfa">
<div class="margin-bottom-30">
    <%-- Title of the article --%>
    <div class="headline"><h3 ${rdfa.Title}>${value.Title}</h3></div>
    <%-- The text field of the article with image --%>
    <div class="paragraph">
        <c:set var="showing" value="false" />
        <c:if test='${value.Image.isSet and (cms.element.settings["showImage"] eq "true")}'>
            <c:set var="showing" value="true" />
            <c:set var="imgwidth">${(cms.container.width - 50)}</c:set>
            <cms:img src="${value.Image}" width="${imgwidth}" scaleColor="transparent" scaleType="0" cssclass="left" />
        </c:if>
        ${value.Text}
        <c:if test="${showing}">
            <div class="clear"></div>
        </c:if>
    </div>
</div>
</cms:formatter>

Here are the interesting spots of the formatter:

As in each JSP, the taglibs used have to be included, here done via <%page ... taglibs="c,cms" %>.
The code that produces HTML is framed by <cms:formatter var="content" ...><div ...> ... </div></cms:formatter>. This is typical for all formatters. The <cms:formatter> exposes the content that should be rendered via an CmsJspContentAccessBean. In the example, the variables value and rdfa, exposed via the attributes val and rdfa are only abbreviations for content.value and content.rdfa.
Note: It is important to have a <div> directly nested as the only child of the formatter tag. Otherwise, the content may not render as expected (in particular in the page editor).
The formatter tests if elements are present in the currently rendered content, e.g., via value.Image.isSet in the example, and inserts content values in the HTML, e.g., via value.Title in the example.
The formatter is sensitive to element settings. In the example, the image is only rendered if the setting showImage is true, which is checked via cms.element.settings["showImage"] eq "true".
The formatter enables inline editing - here only for the Headline by adding ${rdfa.Title} to the <h3> tag.

Writing a formatter is like writing a normal JSP, but some of the special OpenCms JSP API is in particular useful in formatters. The topics listed below will be helpful in writing formatters.