OpenCms documentation
OpenCms documentation

Options for display formatters

Element settings allow editors to change how contents are displayed. If a content is dropped directly to the page, a dialog for the element settings is available. But, if the content gets to the page indirectly, typically when collected in a list that is dopped to the page, the element settings can't be edited directly at the content.

With OpenCms 11 you can display the settings of a display formatter with the list that collects the rendered content. Several options are available.

Since OpenCms 10, display formatters are a feature of OpenCms. The idea is to have a list content and in the content, you specify not only which contents are displayed in the list, but also which formatters to use to display the content. This separates formatting of the list (frame) itself and the displayed elements in the list.

However, display formatters can have element settings and be used as "normal" formatter as well when dropping a content to a page directly. These settings are of course available when the formatted element is dropped directly to the page, but not if the formatter is used indirectly by the list.

To solve this problem, element settings of display formatters can be configured to be shown with the settings of the list, either appearing as a setting of the list itself, or in a separate section in the settings dialog.

The following picture shows an example of the settings dialog for a list that renders the elements via display formatters that have settings shown with the list's settings.

Settings mixed from a list and the used display formatters

Note that the settings starting at "Teaser text length" are already settings from display formatters, but they are shown like the above "normal" list settings. Additionally to the settings appearing as native list settings, there are settings in the extra section "Compact event teaser". These are clearly separated and it is visible to the editor that they apply to event teasers only. The different ways to integrate display formatter settings to the list settings become relevant mostly if lists collect elements of more than one type and the various display formatter might have settings that are shared between all of them - as for example configuration of the teaser length.

To get element settings from display formatters to lists, three steps are required:

  • The display formatters element settings have a suitable "Visibility" configured
  • The list content uses a schema element of type OpenCmsDisplayFormatter to reference the display formatters.
  • The list formatter that renders the list has the option "Include element settings from display formatters" enabled.

In the formatter configuration of the display formatter under the tab "Supported settings", element settings are configured. See here for the configuration in general. The important option concerning display formatters is the "Visibility".

element

The default option. The setting is only shown when the formatted element is dropped directly at the page.

elementAndParentShared

The setting is shown if the formatted element is directly dropped to the page and with the element settings of the list, but in an extra section in the settings dialog.

parentShared

The setting is not shown if the formatted element is directly dropped to the page, but with the element settings of lists like a native list setting.

parentIndividual

The setting is only shown with the list's settings, but in an extra section in the settings dialog.

Referencing display formatters in the list content

For most of your use cases the integrated list content might be sufficient, so you do not have to set up your own list.

In the schema definition (.xsd) of the list content, there must be a schema element to reference the display formatters that the list should use. This element must have type OpenCmsDisplayFormatter. It typically also uses the widget "DisplayTypeSelectWidget". Moreover, in the appinfo section, a node defining which schema elements hold display formatters, or in a more general speaking, nested formatters.

<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified">
    <!-- ... -->
    <xsd:complexType>
        <!-- ... -->
        <xsd:element name="TypesToCollect" type="OpenCmsDisplayFormatter" 
            minOccurs="1" maxOccurs="unbounded" />
        <!-- ... -->
    </xsd:complexType>
    <xsd:annotation>
        <xsd:appinfo>
            <!-- ... -->
            <nestedformatters>
                <nestedformatter element="TypesToCollect"/>
            </nestedformatters>
        </xsd:appinfo>
    </xsd:annotation>
</xsd:schema>

Basically the element defined in line 5 is declared to hold the references to the display formatters by the nestedformatter node in line 13.

A good example XSD is the schema definition of the list content shipped with OpenCms since version 11. Here you can see the xsd on GitHub.

A list content may have various formatters and only some of them may really shown contents with display formatters. For example, for lists of the integrated OpenCms list type, you may have a formatter only displaying filter options and another displaying the found resources. Hence, not for all list formatters the settings of display formatters should be shown in the lists settings dialog.

To show the settings of display formatters with the lists settings for a specific list formatter check "Include element settings from display formatters" in that list formatters configuration.

List formatter configuration: Include settings from display formatters