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>"
|file||The name of the configuration file used to configure the decoration.||yes|
|locale||The locale to be used for the decoration.||no|
The body of this tag contains the HTML that should be decorated.
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.
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" />
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.
Currently there is one global setting:
|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||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
|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: |
For the example above, the "pre-text" will be:
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:
|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.
|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.
|Decoration File|| |
The VFS Path to a decoration definition files used by this decoration definition
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.