$CMS_IF(...)$

Using $CMS_IF(...)$

Within a template, depending on a condition, for example the width of a picture, different outputs can be generated in the corresponding position of a page.
Conditional evaluations are carried out using the following instructions:

• $CMS_IF(...)$
• $CMS_SWITCH(...)$

Unlike the instruction $CMS_SWITCH(...)$, in $CMS_IF(...)$ only one expression each is checked for a comparable value. To this end a condition is given within the tag which checks a comparable value for "true" or "false" and then controls the output depending on the determined value.

Syntax of $CMS_IF(...)$

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

$CMS_IF(CONDITION)$
    EXECUTION PART (FULFILLED CONDITION)
$CMS_END_IF$

The code example describes the simplest variation of the instruction $CMS_IF(...)$. Within the instruction a condition (CONDITION) is given which must be fulfilled ("true") so that further instructions or outputs are executed within the $CMS_IF(...)$ tag.

The instruction can be extended by a $CMS_ELSE$ tag to define further instructions or outputs which are to be executed if the expression defined as a condition is "false":

$CMS_IF(CONDITION)$
  EXECUTION PART (FULFILLED CONDITION)
$CMS_ELSE$
  EXECUTION PART (UNFULFILLED CONDITION)
$CMS_END_IF$

The tag $CMS_ELSIF(CONDITION)$ can be used to define further conditions within the existing instruction $CMS_IF(CONDITION)$ and therefore the instruction can be nested as deep as necessary:

$CMS_IF(CONDITION_1)$
  EXECUTION PART (FULFILLED CONDITION_1)
$CMS_ELSIF(CONDITION_2)$
  EXECUTION PART (FULFILLED CONDITION_2)
$CMS_ELSE$
  EXECUTION PART (UNFULFILLED CONDITION_1 AND CONDITION_2)
$CMS_END_IF$

In the code example the second condition within $CMS_ELSIF(CONDITION_2)$ is not evaluated unless the first condition $CMS_IF(CONDITION_1)$ proves to be "false".

The $CMS_ELSIF(...) tag represents the merger of the two tags $CMS_ELSE$ and $CMS_IF(...)$. The above example can therefore also be realised using $CMS_ELSE$ and $CMS_IF(...)$:

$CMS_IF(CONDITION_1)$
  EXECUTION PART (FULFILLED CONDITION_1)
$CMS_ELSE$
  $CMS_IF(CONDITION_2)$
    EXECUTION PART (FULFILLED CONDITION_2)
  $CMS_ELSE$
    EXECUTION PART (UNFULFILLED CONDITION_1 AND CONDITION_2)
  $CMS_END_IF$
$CMS_END_IF$

The $CMS_IF(...)$ instruction can be extended as required to include further $CMS_ELSE$ and $CMS_ELSIF$ tags. Also, any number of $CMS_IF(...)$ instructions can be nested within each other.

Parameters of $CMS_IF(...)$

$CMS_IF(...)$ has one parameter only: the CONDITION.

How a CONDITION is structured and how it is evaluated is explained in the following.

CONDITION

To define a condition (CONDITION) which is passed to the instruction $CMS_IF(CONDITION)$ or $CMS_ELSIF(CONDITION)$ a maximum of three parameters are required:

1. Variable or constant
2. Operator (optional)
3. Comparable variable, comparable constant or reference value (optional)

The expression:

1 == 1

is therefore a valid condition as "1" is a valid constant, "==" is a valid operator and "1" is a valid comparable constant.

This also applies accordingly to the following expression:

a != b

The value of a variable or constant can be compared with another value via a condition or an operator respectively (see "expressions"). This is useful, e.g. if the value of the variable a changes within a function (e.g. Navigation); however, the comparable value is constant in several sub-areas.

In addition, there are several methods in FirstSpirit which return a Boolean value (e.g. #global.preview). For expressions which return a Boolean value, it is not necessary to specify an Operator or a Comparable value.

$CMS_IF(#global.preview)$
  EXECUTION PART (PREVIEW)
$CMS_ELSE$
  EXECUTION PART (DEPLOYMENT)
$CMS_END_IF$

Evaluation

The instruction $CMS_IF(...)$ checks whether a given condition is "true" or "false". The "true" branch does not require any further instructions and is also analysed in its simplest form in the instruction:

$CMS_IF(a != b)$
    That is my output! 
$CMS_END_IF$

. However, in the code example given above an output is only generated if the condition is "true".

If an output is to take place even if the condition is "false" a further $CMS_ELSE$ instruction is required

$CMS_IF(a != b)$
    That is my output! 
$CMS_ELSE$
    That is not correct!
$CMS_END_IF$

If a = 1 and b = 2 the condition is true and the instruction outputs the text "That is my output!".

If a = 1 and b = 1 the condition is false and the instruction outputs the text "That is not correct!".

Examples of $CMS_IF(...)$

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: Output of the change date in the preview

Code example:

$CMS_IF(#global.preview)$
  Change date: $CMS_VALUE(#global.page.changeDate.format("yyyy-MM-dd HH:mm"))$
$CMS_END_IF$

Description:

The example outputs the change date of a page of the Page Store in a preview.

Output:

Change date: 2007-02-19 10:39

or the change date in ISO format

2nd Example: Comparison of two constants

Code example:

$CMS_SET(set_var1,"A")$
$CMS_SET(set_var2,"B")$
$CMS_IF(set_var1 == set_var2)$
  A == B
$CMS_ELSE$
  A != B
$CMS_END_IF$

Description:

In the example, two constants set_var1 and set_var2 are defined. The $CMS_IF(...)$ function then compares set_var1 with set_var2.

Output:

As the content of set_var1 differs from the content of set_var2 the result is:

A != B

3rd Example: Modulo check in a loop

Code example:

$CMS_SET(set_compare)$
  $CMS_IF((for_val % 2) == 0)$
    even
  $CMS_ELSE$
    odd
  $CMS_END_IF$
$CMS_END_SET$

$CMS_FOR(for_val, [0 .. 10])$
  The number "$CMS_VALUE(for_val)$" is $CMS_VALUE(set_compare)$
$CMS_END_FOR$

Description:

The example describes the dynamic modulo check in a loop.
First, a document fragment set_compare is defined with the help of $CMS_SET(...)$...$CMS_END_SET$. In this fragment, depending on the given value, a modulo check determines whether the value is "even" or "odd".
The values are specified by $CMS_FOR(...)$.
The given $CMS_FOR(...)$ loop invokes the fragment for each integer from 0 to 10.

Output:

The number "0" is even
The number "1" is odd
The number "2" is even
The number "3" is odd
The number "4" is even
The number "5" is odd
The number "6" is even
The number "7" is odd
The number "8" is even
The number "9" is odd
The number "10" is even

Alternatively, this can also be realised with the method: even():

$CMS_SET(set_compare)$
  $CMS_IF(for_val.even)$
    even
  $CMS_ELSE$
    odd
  $CMS_END_IF$
$CMS_END_SET$

$CMS_FOR(for_val, [0 .. 10])$
  The number "$CMS_VALUE(for_val)$" is $CMS_VALUE(set_compare)$
$CMS_END_FOR$

and without document fragment:

$CMS_FOR(for_val, [0 .. 10])$
  The number "$CMS_VALUE(for_val)$" is $CMS_IF(for_val.even)$
    even
  $CMS_ELSE$
    odd
  $CMS_END_IF$
$CMS_END_FOR$