Search the documentation
 Show GitHub edit links  Hide GitHub edit links
In OpenCms since: 9.0 Documented since: 9.5 Latest revision for: 10.0 Valid for OpenCms: 10.5.3

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.

Content items that should be rendered via formatters must be configured as resource types.

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'.

Where to place a 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.
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.

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 traditional workplace's explorer view 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.

What is specified in a formatter configuration?

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 a 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.

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.

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.

Search content

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.

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.

Use as detail formatter

If checked, the formatter can be used when the resource is rendered in detail view.

Use as display formatter

If checked, the formatter is used by the tag <cms:display> if no other formatter is specified for the same resource type. Moreover, the formatter is added as option in the DisplayTypeSelectWidget.

Contains nested containers

Check this option if the formatter introduces a nested container.

Use strict 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.

CSS includes

Add formatter-specific CSS styles here. See here for details.

Javascript includes

Add formatter-specific JavaScript here. See here for details.

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. A demo on how to use element settings is found here.

Writing a formatter

A formatter is a normal JSP (type jsp). The special part is the use of the tag <cms:formatter> that exposes the content of the rendered resource.

Adding and editing a formatter

Use the traditional workplace's explorer view 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.

A typical formatter

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.

More information on writing formatters

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.

You can improve this page

Please contribute your suggestions or comments regarding this topic on our wiki. For support questions, please use the OpenCms mailing list or go for professional support.