OpenCms documentation
OpenCms documentation

Editor field description for Formatter configuration

Contains the configuration for a single formatter.
Back

Tab "Basic configuration"

Display name
(Text input)
The user-readable name of the formatter.
Resource type
(???msg.page.md.widgetname.org.opencms.widgets.CmsTypeFilterWidget???)
Can occur as often as necessary
The representation of this field in the documentation does not correspond exactly to the appearance in the editor.
The type for which this is a formatter.
Formatter key
(Text input)
Optional
The formatter key is stored in container pages as reference to this formatter. This allows to replace e.g. the formatter JSP by configuration, without the need to change container pages that use the formatter. If the formatter key is not set, the UUID of this formatter is stored in container pages instead.
Formatter key must only consist of characters A-Z, a-z, 0-9, /, #, minus (-) or period (.)
Formatter key alias
(Text input)
Optional - Can occur as often as necessary
A deprecated formatter key that should still be mapped to this formatter, but not written to container pages.
JSP
(File selection)
The JSP used to format the content
Description
(Text input)
Optional
Description of the formatter. You can use %(key...) macros here for localization.
Rank
(Text input)
The rank of the formatter, which is used to determine the default formatter for a given container. A formatter with high rank will preferred over one with low rank if both match the container's type/width. Formatters defined in schemas have a rank of 10000.
Matching containers
Choice
Optional

The container types for which this formatter can be used.

As an option for older templates and formatters a container pixel width can be defined.

Choice option 1
Container types
Optional
Use this formatter for the matching container types.
Container type
(Text input)
Optional - Can occur as often as necessary
A container type for which this formatter can be used.
Choice option 2
Container pixel width
Optional
Use this formatter based on the container pixel width.
Width
(Text input)
Minimum width of the container
Maximum width
(Text input)
Optional
Maximum width of the container
Display formatter type
(Text input)
Optional
If this is not empty, the formatter will be used as a display formatter of the given type.
Enabled
(Check box)
If this is set to true, the formatter will be automatically available in the page editor without having to explicitly add it via the sitemap configuration.
Search content in container page
(Check box)

Controls if the content of an element that uses this formatter is added to the SOLR search index for the container page on which the formatter is used.

An example: Element 'E' is used with this formatter in page 'P' and contains the word 'TERM'. If 'TERM' is searched for, and this option is checked, then the search result will contain a link to page 'P'. If this option is not checked, 'P' will not be found.

Please note: The XML schema of the content element controls how exactly the element is added to the SOLR search index.

Remove unused nested containers
(Check box)

This is applicable only for formatters generating nested containers.

Changes are only applied when a container page using this formatter is modified in the page editor.

If this is checked, the content in the generated nested containers will be removed from the page if the element is removed from the page OR a nested container is not longer generated by the formatter. This is usually the expected behavior.

If this is not checked, the content in the generated nested containers is kept on the page even if the element is removed from the page OR different nested container structures are generated by the formatter depending on external factors. A use case for this is a formatter that dynamically generates different nested container structures for mobile and desktop devices.

Use as detail formatter
(Check box)
Optional

If this is checked then this formatter will automatically be used for formatting detail content on a detail page. The required container matching conditions like resource type and container type must be met. In case multiple formatters match the required conditions, the formatter with the highest rank number will be used.

If this is not checked then this formatter will not automatically be used for formatting detail content on a detail page.

Always apply meta mappings
(Check box)
Optional

If this option is set, meta mappings are applied if an element using this formatter is placed on a container page by drag and drop.

If this option is not set, meta mappings are applied only if this formatter is used for the detail element on a detail page.

Include element settings from display formatters
(Check box)
Optional
This option has to be checked to allow nested formatter settings.
Show element settings in content editor
(Check box)
Optional

If this is checked, the element settings will be editable in the form based content editor.

If this is not checked, the element settings will not be shown in the form editor.

Use for preview
(Check box)
Optional
When this is set, the formatter will be preferred for the preview function.
CSS includes
Choice
Optional
CSS files or snippets used by this formatter.
Choice option 1
Inline styles
(Text area)
Optional
A snippet of CSS to style this formatter's output.
A link to a CSS file to style this formatter's output.
Javascript includes
Choice
Optional
Javascript files or snippets used by this formatter.
Choice option 1
Inline script
(Text area)
Optional
A snippet of Javascript used by this formatter.
A link to a Javascript file used by this formatter.
Plugin
Optional - Can occur as often as necessary
Group
(Text input)
Target
(File selection)
Order
(Text input)
Optional
Attribute
Optional - Can occur as often as necessary
Key
(Text input)
Value
(Text input)

Tab "Supported settings"

Element setting defaults
(File selection)
Optional - Can occur as often as necessary
A configuration file containing default values for element settings.
Setting
Optional - Can occur as often as necessary
Used to configure the output generated by the formatter. Settings are usually displayed in the element settings dialog made available to the content manager.
Name
(Text input)
Optional
The name for this setting. The setting value can be accessed in the JSP using this name.
Alias
(Text input)
Optional
Include name
(Text input)
Optional
The include name for this setting. This can be used together with an element setting default file that contains shared setting definitions.
Displayed name
(Text input)
Optional
The name displayed in the element setting dialog for the content manager.
Description
(Text input)
Optional
The description should supply information about what this setting is used for, any which input values are allowed. The description is displayed in the element setting dialog for the content manager.
Visibility
(Select box)
Optional
Widget
(Combo box)
Optional
The widget to use to edit the setting.
Default
(Text input)
Optional
The default value.
Widget configuration
(Text input)
Optional
The widget configuration parameter(s).
Value translation
(Text input)
Optional
Validation rule
(Text input)
Optional
A regular expression used to validate the users input.
Validation type
(Select box)
Optional
Specifies if failing the regular expression test causes an error or a warning.
Error message
(Text input)
Optional
The error message to display when the validation fails.

Tab "Meta mappings"

Meta mapping
Optional - Can occur as often as necessary

Meta mappings allow access to values of the formatted element in the global template context.

Access is possible using the EL function ${cms.meta}

Key
(Text input)

The mapping will be accessible in the global template context using this key.

For example, a meta mapping key 'Description' can be accessed with the EL call ${cms.meta.Description}.

Path
(Text input)

The xpath to the mapped value in the formatted XML content.

The current locale is automatically added as a prefix.

Rank
(Text input)
Optional

The ranking for this meta mapping.

In case of multiple mappings from different formatters to the same key, the mapping with the highest ranking wins.

Default
(Text input)
Optional

The default value used for this mapping in case there is no content available for the configured path.

If no default has been configured and there is no content available for the configured path, then the mapping will not be set from this formatter.

Tab "Attributes"

Attribute
Optional - Can occur as often as necessary
A key-value pair used to store additional information about the formatter.
Key
(Text input)
Value
(Text input)