Start page / Templates (basics) / Composition of templates / Format templates / Conversion

Conversion using format templates

Setting conversion rule

A conversion rule can be selected from the “Conversion” drop-down list. Only conversion rules which have previously been installed on the server are displayed in the list (for more information, see the Conversion rules (→Documentation for Administrators)). The default conversion rule is “Convert HTML”.

When a conversion rule is selected, it is only applied for the corresponding template set of the selected format template.

A single conversion rule can be defined for each template set. Additional conversion rules can be used in a template set by calling up the .convert() and .convert2() methods.
However, multiple conversion rules can be used within a single project.

Conversion rules are used to convert characters that are input. It is possible to:

swap one character for another or
swap a character for a string

A conversion rule consists of two parts:

“convert” is always evaluated whenever a conversion rule has been selected for a format template. If “quote” is also to be evaluated, the “Quote” box must also be checked (see the Properties page).

The conversion is only applied when the CMS_INPUT_DOM or CMS_INPUT_DOMTABLE input components are output.
The output must be defined with the #content system object, e.g., with $CMS_VALUE(#content)$.

convert

The “convert” area is used to convert the formatted text for the corresponding template set from one character set into the next character set. Non-HTML-compliant characters can be replaced with HTML-compliant characters for the “HTML” template set, for example. The “Convert HTML” conversion rule contains the following instruction, for example:

0x3c="&lt;"

In other words, the Unicode characters '0x3c' are converted into HTML-compatible '<'.

The .convert() method can be called in template sets (e.g., “HTML”) and/or in a format template.

quote

The “quote” area can be used to quote HTML-specific or XML-specific characters as well. Care should be taken to ensure that the characters <, >, ', " are quoted – as a minimum – or that they are included in the conversion rule used (for the template set) (see Security aspects).

The .convert2() method can be called in the template set (e.g., “HTML”) and/or in a format template. Quotation can be activated for a format template via the “quote” property.

Example for convert and convert2

Example: “test” conversion rule

[convert]
0x21="an exclamation mark"
0x23=0x24
[quote]
0x25=0x22

0x21 is the exclamation mark (!),
0x22 is the quotation mark (")
0x23 is the number sign (#),
0x24 is the dollar sign ($), and
0x25 is the percentage sign (%).

Multiple conversions should not be used, e.g.,
0x23=0x24
0x24=0x21

Example: “test” conversion rules being used in the project (format template):

<pre>
convert:  $CMS_VALUE(":::!:::#:::%:::".convert("test"))$
convert2: $CMS_VALUE(":::!:::#:::%:::".convert2("test"))$
</pre>

Example: “test” conversion result in the project (template set):

convert:  :::an exclamation mark:::$:::%:::
convert2: :::an exclamation mark:::$:::":::

Evaluation sequence of conversion rules

Formatted text

As shown in the “Formatted text” figure, the formatting attributes used by the editor are not always strictly separated but, under some circumstances, can even be nested.

In such cases, the conversion rules are always evaluated from inside to outside. As soon as a conversion rule has been applied, the corresponding text counts as converted and is excluded from subsequent conversion operations.

If a format template does not have a dedicated conversion rule, inheritance of conversion rules can be activated by setting a variable in the generation context.

By indicating $CMS_SET(inherit_format_conversion, true)$ (for example within a Project settings page).
By doing this, inheritance from an outer format template to an inner format template will be activated (in the case where this template does not contain any conversion rule).

Example:
For format template “Italic” : conversion: Unicode->HTML
For format template “Bold” : conversion: none
Applied to our example „This is text in bold and italic.“ this means:

$CMS_SET(inherit_format_conversion, false)$   (= default setting)

The conversion rule of “Italic” will not be applied to the text formatted with the format template “Bold” but only to the text formatted with the format template “Italic”
This means that “Bold” does not inherit the setting of “Italic”.
The default behaviour does not intend any inheritance of conversion rules.

$CMS_SET(inherit_format_conversion,true)$

The conversion rule of “Italic” will be applied to the text formatted with the format template “Bold”, too, as long as no dedicated conversion rule is set for “Bold”.

The setting of a blank conversion rule for a format template is a special case. Text formatted in this way counts as converted, i.e., no further conversions are carried out based on section formatting templates, for example. The characters are transferred to the corresponding template set as they were entered by the editor. A blank conversion rule of this type can be useful for outputting source texts, for example.

Print version | Page start