The <cms:decorate> tag

This tag is used to decorate words or phrases in already rendered HTML pages with additional tags in a postprocessing step.
For example, a decoration called "abbreviation" could decorate abbreviations in
the text with the <abbr> tag.

A text like "OpenCms is a CMS" would be decorated to "OpenCms is a <abbr title="Content Management System" lang ="en">CMS</abbr>"

Attributes:

Name Description Required
file The name of the configuration file used to configure the decoration. yes
locale The locale to be used for the decoration. no

Body:

The body of this tag contains the HTML that should be decorated.

Example usage:

In this example, the configuration of the decoration is defined in the file "/alkacon-documentation/documentation_taglib/test_tag_decorate.xml". For each usage of the <cms:decorate> tag, a different configuration file can be used.

IMPORTANT:
If the <cms:include> tag is used inside the <cms:decorate> tag, the attribute "cachable=false" must be used in the <cms:include> tag, otherwise the decoration will not work.

<cms:decorate file="/system/modules/mymodule/decoration/configuration.xml" >
<cms:include element="body" editable="true" cacheable="false" />
</cms:decorate>

 

Configuration

The configuration of the <cms:decorate> tag is done in a xml-content file stored in the OpenCms VFS. A default configuration file can be found at "/system/shared/decoration/configuration.xml" which can be edited by selecting "Edit" from the context menu. You can create different configuration files by copying the default file. Each configuration file holds global configuration settings and at least one decoration definition to be used within the <cms:decorate> tag. For each decoration definition, a set of .csv files can be defined which holds the keywords and their decoration.
 

Global settings

Currently there is one global setting:

Name Description
Locale depending decoration If this option is selected the decoration is build locale depending. This should be used if a keyword has different decorations in different locales. If a page is shown in the locale "en", only the English decorations are used and not those for a different locale. The default for this setting is false.


Settings for single decoration definition
For each decoration definition, several parameters must be entered:

Name Description
Name  The user-friendly name of this decoration definition, only used for
identifying the definition
Mark first occurance

If this option is selected, the first  occurance of a keyword (which is contained in the decoration defintion file) will be decorated differntly to later occurences.

E.g. if the first occurance of  "CMS" should be decorated like

"<abbr title="Content Management System" lang ="en">CMS</abbr>"

and all other occurences should only be decorated like

"<abbr>CMS</abbr>"

this option must be selected.
Pre-Text This field holds the text that should be inserted in front of the keyword to be decorated. Inside this text, the following macros are allowed:
  • ${decoration}: will be replaced with the decoration text from the decoration definition file
  • ${locale}: will be replaced with the locale of the decoration

For the example above, the "pre-text" will be:
<abbr>
Post-Text

This field holds the text that should be inserted behind the keyword to be decorated. The same macros as above can be used.

For the example, the "post-text" will be:
</abbr>
Pre-Text (first occurance)

This field holds the text that should be inserted in front of the keyword to be decorated on its first occurance (if this option is selected). The same macros as above can be used.
For the example above, the "pre-text (first occurance)" will be:
<abbr title="${decoration}" lang="${locale}">
Post-Text (first occurance)

This field holds the text that should be inserted after  the keyword to be decorated on its first occurance (if this option is selected). The same makors as above can be used.


For the example above, the "poste-text (first occurance)" will be:
</abbr>
Decoration File

The VFS Path to a decoration definition files used by this decoration definition


Example:
"/system/shared/decoration/decorations_en.csv"

Decoration definition files

Decoration definition files are CSV files, with two entries in each line,  separated by a pipe symbol "|".  For example, a line in such a CSV file would look like this:

CMS|Content Management System

A decoration definition uses a set of such decoration definition files, each of them holding the decorations for a single locale and starting with the same  prefix like this:

decorationAbbr_de.csv (for german abbreviation)
decorationAbbr_en.csv (for english abbreviation)
decorationAbbr.csv (for language independend abbreviation)

In this example, "decorationAbbr" is the so called "base name". All decoration definition files with the same base name  are automatically collected in the configuration. Depending on their locale postfix (e.g. "_en" or "_de") the keywords and decorations in it will be allocated to the correct locale. In the configuration, its only required to define one of the decoration definition files (e.g. "decorationAbbr_en") all other files with the same base name will be assigned automatically.

If you have set "Locale depending decoration" to true only the decoration definition file for the corrent locale and the file containing the locale independent decorations will be applied to the content inside the <cms:decorate> tag. If it is set to false, the decorator will look up a name in all decoration definition files and use the decorations in all of them.