$CMS_SET(...)$

Using $CMS_SET(...)$

The $CMS_SET(...)$ instruction can be used to define a variable within a template and assign a value to the variable.

Syntax of $CMS_SET(...)$

The following syntax must be adhered to when using $CMS_SET(...)$:

$CMS_SET(IDENTIFIER,OBJECT)$

or

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

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$ (labelled above as BODY OF THE TEMPLATE FRAGMENT ).

The first expression is an object allocation, e.g. string, number, etc. The second expression describes the generation of a template fragment which is comparable, e.g. with a section template.

Parameters of $CMS_SET(...)$

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

• IDENTIFIER
• OBJECT or BODY

IDENTIFIER

The allocated object of the template fragment can be evoked in the source text of the template under the given identifier:

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

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

The identifier may contain the following characters only: 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 invoke the method .toString, which causes immediate resolution of the expression (see third code example).

BODY

With the body of a $CMS_SET(...)$ instruction, any $CMS_...(...)$ expressions required can be given, 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 of 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 analysed with $CMS_VALUE(...)$ in the first invocation! An endless loop can, e.g. be avoided by forced analysis (by .toString), or by complete avoidance of identifier repetition.

Example of an endless loop:

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

$CMS_VALUE(endlessloop)$

In the example the attempt is made to precede the value of endlessloop with the word PREFIX and to append the word POSTFIX .

The errors of the preview contains 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 (identifiable by the +) the expression is evaluated once only.

Generation of a dictionary

A dictionary can be generated as follows:

$CMS_SET(IDENTIFIER, { })$

It can then be allocated with the method .add :

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

To ensure there is no output it is possible to use a $CMS_SET(..)$ instruction with a dummy variable (e.g. void):

The output of the dictionary can be realised with the help of a $CMS_FOR(...)$ instruction:

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

Generation of a list

A $CMS_SET(...)$ instruction can be used to generate a new list.

The syntax for this is:

$CMS_SET(IDENTIFIER, [])$

New entries in a list can be realised either by giving the index

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

or using the method .add :

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

The output can be realised, e.g. by a $CMS_FOR(...)$ instruction:

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

Setting language-dependent values

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

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

$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 (on access to a dictionary):

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

Examples of $CMS_SET(...)$

Several examples of use of the instruction within templates are shown in the following. The examples are intended to clearly show the specific effect of the instruction and provide help for the template developer when creating their own templates.

The examples displayed here must be adjusted for use within a project! For example, variable names must be changed to the specific variable names of the project in which the instruction is to be used.

1st Example: Replacement of an if function with the instruction $CMS_SET(...)$

The instruction $CMS_SET(...)$ can replace the following function <CMS_FUNCTION name="if"...>:

<CMS_FUNCTION name="if" resultname="fr_pt_lang">
  <CMS_VALUE_PARAM name="conditionVar" value="global.language"/>
  <CMS_PARAM name="compareValue" value="EN"/>
   <CMS_CDATA_PARAM name="trueValue"><![CDATA[EN]]></CMS_CDATA_PARAM>
   <CMS_CDATA_PARAM name="falseValue"><![CDATA[not EN]]></CMS_CDATA_PARAM>
</CMS_FUNCTION>

The following instruction fulfils the tasks of the function given above:

$CMS_SET(fr_pt_lang)$
   $CMS_IF(#global.language.abbreviation == "EN")$
       EN
     $CMS_ELSE$
       not EN
   $CMS_END_IF$ 
$CMS_END_SET$

Description:

If the currently rendered language contains the abbreviation EN , EN is output, otherwise not EN.

Output:

$-- If  EN --$
EN

$-- If not  EN --$
not EN