$CMS_SET(...)$

Using $CMS_SET(...)$

The $CMS_SET(...)$ instruction enables a variable to be defined within a template and a value to be assigned to the variable.

Syntax of $CMS_SET(...)$

When using $CMS_SET(...)$, there are two syntax options.

Variant 1:

$CMS_SET(IDENTIFIER,OBJECT)$

Variant 2:

$CMS_SET(IDENTIFIER)$
  BODY OF THE TEMPLATE FRAGMENT
$CMS_END_SET$

The first variant is an object allocation, e.g., string, number, etc. The second variant describes how a template fragment is generated and is similar to a section template, for example. In this case, the entire BODY OF THE TEMPLATE FRAGMENT is also executed when the CMS_SET variable (for example using $CMS_VALUE(IDENTIFIER)$) is evaluated and the code within it is executed.

Within a $CMS_SET(...)$ instruction, multiple variables or variables and assignments can be separated using commas, e.g.:

$CMS_SET(var1, var2)$ 

The IDENTIFIER and the OBJECT may not contain any $CMS_VALUE(...)$, e.g., $CMS_SET(varname$CMS_VALUE(a)$,"b")$ or $CMS_SET(a,"b$CMS_VALUE(c)$")$. Such expressions can only be used between $CMS_SET(IDENTIFIER)$ and $CMS_END_SET$ (labeled above as BODY OF THE TEMPLATE FRAGMENT).

Parameters of $CMS_SET(...)$

$CMS_SET(...)$ has the following parameters:

• IDENTIFIER
• OBJECT or BODY

IDENTIFIER

Under the specified identifier, the allocated object or the template fragment can be called in the source text of the template:

$-- Definition: --$
$CMS_SET(varName,"A")$

$-- Output: --$
$CMS_VALUE(varName)$

The identifier may only contain the following characters: A-Z, a-z, 0-9, and _.

OBJECT

One option for defining a $CMS_SET(...)$ instruction is to allocate an object:

$CMS_SET(varName,"Value")$

or

$CMS_SET(varName1,varName2)$

or

$CMS_SET(varName1,varName2.toString)$

The object can be both a constant as well as another variable or even an expression.

The value of the object and not the object itself must be allocated for further processing of the object. In most cases, it is sufficient to call the .toString method, as this will immediately resolve the expression (see third code example).

BODY

Within the body of a $CMS_SET(...)$ instruction, any $CMS_...(...)$ expressions can be specified, e.g.:

• $CMS_IF(...)$,
• $CMS_REF(...)$,
• $CMS_SET(...)$, and
• $CMS_VALUE(...)$

$CMS_SET(varName)$
  $CMS_IF(#global.preview)$
    Output in a preview page
  $CMS_ELSE$
    Other output
  $CMS_END_IF$
$CMS_END_SET$

Use of the identifier for a $CMS_SET(...)$ instruction in a $CMS_VALUE(...)$ instruction in the body of the $CMS_SET(...)$ instruction can result in an endless loop, as the body is evaluated with $CMS_VALUE(...)$ during the first call! An endless loop can be avoided, for example, by carrying out a forced evaluation (using .toString) or by completely preventing the identifier repetition.

Example of an endless loop:

$CMS_SET(endlessloop)$
  PREFIX$CMS_VALUE(endlessloop)$POSTFIX
$CMS_END_SET$

$CMS_VALUE(endlessloop)$

In the example, an attempt is made to add the word PREFIX before and the word POSTFIX after the endlessloop value.

The errors of the preview contain the following output:

ERROR: endless loop in template?

To avoid the endless loop in the example, the expression must be worded as follows:

$CMS_SET(endlessloop, "PREFIX" + endlessloop.toString + "POSTFIX")$
$CMS_VALUE(endlessloop)$

By rewording the expression as a summary of several objects (indicated by the +), the expression is evaluated once only.

Evaluation

The variable defined using the instruction $CMS_SET(...)$ can be of the TemplateDocument type. This means that the expression it contains has not yet been evaluated.

For example (template):

$CMS_SET(myVar)$
6 * 7 = $CMS_VALUE(6 * 7)$ 
$CMS_END_SET$

The expression $CMS_SET(...)$ ... $CMS_END_SET$ defines a variable of the type TemplateDocument in a template fragment ($CMS_SET(..., ...)$, on the other hand, executes an object allocation). This means that the variable myVar is of the type TemplateDocument in this case.

In order to continue working with the evaluated expression, the following expression can be used:

$CMS_RENDER(script:"myscript", scriptVar:myVar)$

$CMS_VALUE(myVar)$ also evaluates the expression of course!

Examples of $CMS_SET(...)$

Below are some examples of how to use the instruction within templates. The purpose of the examples is to point out the precise effect of the instruction and to assist template developers in creating their own templates.

1st example: Generating a set

A set (see page Set data type) can be generated as follows:

$CMS_SET(IDENTIFIER, { })$

It can then be assigned using the .add method.
To ensure there is no output, a $CMS_SET(...)$ instruction with a dummy variable (e.g., void) can be used:

$CMS_SET(mySet, { })$
$CMS_SET(void, mySet.add("1st entry"))$
$CMS_SET(void, mySet.add("2nd entry"))$
$CMS_SET(void, mySet.add("3rd entry"))$

The set can be output using a $CMS_FOR(...)$ instruction:

$CMS_FOR(_wrapper, mySet)$
  $CMS_VALUE(_wrapper)$
$CMS_END_FOR$

2nd example: Generating a list

Using a $CMS_SET(...)$ instruction, a list can be generated (see page List data type).

The syntax for this is:

$CMS_SET(IDENTIFIER, [])$

New entries in a list can be made either by specifying the index

$CMS_SET(myList, [])$
$CMS_SET(myList[0], "1st entry")$

or using the .add method:

$CMS_SET(myList, [])$
$CMS_SET(void, myList.add("1st entry"))$

The output can be realized using a $CMS_FOR(...)$ instruction, e.g.:

$CMS_FOR(_wrapper, myList)$
  $CMS_VALUE(_wrapper)$
$CMS_END_FOR$

3rd example: Setting language-dependent values (dictionary)

The $CMS_SET(...)$ instruction can be used to set language-dependent variables. Language-dependent means that a different variable value is set depending on the language selected.

The syntax for the implicit language use is as follows (via a map):

$CMS_SET(langValues,{ 
  "DE" : {
    "value1" : "D-Value1", 
    "value2" : "D-Value2"
    },
  "EN" : {
    "value1" : "E-Value1", 
    "value2" : "E-Value2"
     }
})$

In this case, the following expression is used to output a language-dependent value:

$CMS_VALUE(langValues[#global.language.abbreviation]["value1"])$

4th example: Working with template fragments

The example illustrates how variables are handled in different contexts within a template. Using a $CMS_SET(...)$ block, template fragments can be defined which can then be executed again and again within the template. The call remains the same but the values are redefined each time the call is made (in contrast to object allocation via $CMS_SET(...)$). This kind of template fragment can be used to complete table cells, for example.

Example:

$CMS_SET(param, "Value A")$

$CMS_SET(set_param1)$ 
  [Inside CMS_SET_BLOCK] $CMS_VALUE(param)$
$CMS_END_SET$

$CMS_SET(set_param2, " [Inside CMS_SET] " + param)$

$CMS_VALUE(set_param1)$<br>
$CMS_VALUE(set_param2)$<br>

$CMS_SET(param, "Value B")$

$CMS_VALUE(set_param1)$<br>
$CMS_VALUE(set_param2)$</br>

The $CMS_SET(param, "Value A")$ instruction is used within the template to define the param variable and to assign the “Value A” initial value to the variables (object allocation).

Using $CMS_SET(set_param1)$ [Inside CMS_SET_BLOCK] $CMS_VALUE(param)$$CMS_END_SET$, a template fragment is generated within the existing template. The code contained in the body of the template fragment – here $CMS_VALUE(param)$ – is executed when the CMS_SET variable is evaluated (by means of $CMS_VALUE(set_param1)$.

The $CMS_SET(set_param2, " [Inside CMS_SET] " + param)$ instruction is used within the template to define the set_param2 variable and to assign this value to the param variables (object allocation).

The output for the example is as follows:

[Inside CMS_SET_BLOCK] Value A 
[Inside CMS_SET] Value A
[Inside CMS_SET_BLOCK] Value B 
[Inside CMS_SET] Value A

Within the $CMS_SET(...)$ block, the value of the variables changes (in contrast to object allocation via $CMS_SET(...)$), as the entire body of the template fragment is executed here each time the CMS_SET variable is evaluated (for example using $CMS_VALUE(set_param1)$) and the code within it is executed.

In contrast, the value for $CMS_SET(set_param2, " [Inside CMS_SET] " + param)$ is only assigned once and then does not change again.