Start page / Template development / Template syntax / Functions / in the header / legacyIf

legacyIf

The legacyIf function fulfils two functions:

Compare a comparative character string with a source character string
Empty check of the source character string

The legacyIf function will be removed in a later FIRSTspirit version.

Equality check (Equals)

For the equality check of the specified character string:

against a character string it is advisable to use $CMS_IF(...)$ .
against several character strings it is advisable to use $CMS_SWITCH(...)$ .

Example:

$CMS_IF("CHARACTERSTRING" == IDENTIFIER)$
  ...
$CMS_ELSE$
  ...
$CMS_END_IF$

$CMS_SWITCH(IDENTIFIER)$
  ...
$CMS_CASE("CHARACTERSTRING")$
  ...
$CMS_END_SWITCH$

Empty check (isEmpty)

Whether a specified character string is empty or filled can be checked using the .isEmpty method in combination with $CMS_IF(...)$ :

$CMS_IF(IDENTIFIER.isEmpty)$
  ...
$CMS_ELSE$
  ...
$CMS_END_IF$

Sub-character string check (Contains)

For the check whether a sub-character string is contained in another character string it is advisable to use the .contains method in combination with $CMS_IF(...)$ ;

$CMS_IF("SUBCHARACTERSTRING".contains(IDENTIFIER))$
  ...
$CMS_ELSE$
  ...
$CMS_END_IF$

Syntax of the legacyIf function

The basic structure of the legacyIf function is as follows:

<CMS_FUNCTION name="legacyIf" resultname="IDENTIFIER">
  <CMS_VALUE_PARAM name="source" value="IDENTIFIER"/>
  <CMS_PARAM name="compareValue" value="CHARACTERSTRING"/>
  <CMS_CDATA_PARAM name="trueCase">
    <![CDATA[
      EXECUTION PART (FULFILLED CONDITION)
    ]]>
  </CMS_CDATA_PARAM>
  <CMS_CDATA_PARAM name="falseCase">
    <![CDATA[
      EXECUTION PART (UNFULFILLED CONDITION)
    ]]>
  </CMS_CDATA_PARAM>
</CMS_FUNCTION>

Parameters of the legacyIf function

The legacyIf function can be specified with the following parameters:

compareValue
falseCase
source
trueCase

The parameter source is a mandatory parameter. Either falseCase or trueCase must be specified. All other parameters are optional.

The values of the individual parameters can be given as constants (<CMS_PARAM>), expressions (<CMS_VALUE_PARAM>) or template fragments (<CMS_CDATA_PARAM>).

The parameter options are listed in the following table.

X means: can be used and recommended;
O means: use possible but not recommended;
- means: Use not possible

Parameter	Meaning	Specifying a constant	Specifying expressions	Specifying a template fragment	Mandatory parameter
compareValue	Comparative character string	X	X	O	no
falseCase	Execution part if it does not contain any sub-character string	X	X	X	yes
source	Specified / source character string	X	X	O	yes
trueCase	Execution part if one or several sub-character strings are contained	X	X	X	yes

compareValue parameter

The compareValue parameter can be used to specify a character string with which the source character string (source parameter) is compared.

Definition with specification of a constant:

<CMS_FUNCTION name="legacyIf" resultname="name">
  <CMS_PARAM name="compareValue" value="CONSTANT" />
  ...
</CMS_FUNCTION>

Definition using expressions:

<CMS_FUNCTION name="legacyIf" resultname="name">
  <CMS_VALUE_PARAM name="compareValue" value="EXPRESSION" />
  ...
</CMS_FUNCTION>

falseCase parameter

The falseCase parameter is used to define an output value for the error case. If the comparative character string (compareValueparameter) does not match the source character string (sourceparameter) or if the source character string is empty (if comparative character string is not given) the defined value is returned here.

For reverse compatibility reasons, for falseCase it is possible to use the synonym falseValue. However, this synonym should no longer be used.

When defining a legacyIf function falseCase or trueCase must be specified.

Definition using a constant:

<CMS_FUNCTION name="legacyIf" resultname="name">
  <CMS_PARAM name="falseCase" value="CONSTANT" />
  ...
</CMS_FUNCTION>

Definition using expressions:

<CMS_FUNCTION name="legacyIf" resultname="name">
  <CMS_VALUE_PARAM name="falseCase" value="EXPRESSION" />
  ...
</CMS_FUNCTION>

Definition using a template fragment (comparable with a section template):

<CMS_FUNCTION name="legacyIf" resultname="name">
  <CMS_CDATA_PARAM name="falseCase">
    <![CDATA[
      BODY OF THE TEMPLATE FRAGMENT
    ]]>
  </CMS_CDATA_PARAM>
  ...
</CMS_FUNCTION>

source parameter

The source parameter is used to specify the source character string.

When a legacyIf function is evaluated it is determined whether the comparative character string (compareValue parameter) matches the source character string.

If a comparative character string has not been specified the check is to see whether the source character string is not empty.

The source parameter is a mandatory parameter.

Definition using a constant:

<CMS_FUNCTION name="legacyIf" resultname="name">
  <CMS_PARAM name="source" value="CONSTANT" />
  ...
</CMS_FUNCTION>

Definition using expressions:

<CMS_FUNCTION name="legacyIf" resultname="name">
  <CMS_VALUE_PARAM name="source" value="EXPRESSION" />
  ...
</CMS_FUNCTION>

trueCase parameter

The trueCase parameter is used to define an output value for the case that the comparative character string (compareValue parameter) matches the source character string (source parameter) or the source character string is not empty (if comparative character string is not specified).

For reverse compatibility reasons, for trueCase it is possible to use the synonym trueValue. However, this synonym should no longer be used.

When defining a legacyIf function falseCase or trueCase must be specified.

Definition using a constant:

<CMS_FUNCTION name="legacyIf" resultname="name">
  <CMS_PARAM name="trueCase" value="CONSTANT" />
  ...
</CMS_FUNCTION>

Definition using expressions:

<CMS_FUNCTION name="legacyIf" resultname="name">
  <CMS_VALUE_PARAM name="trueCase" value="EXPRESSION" />
  ...
</CMS_FUNCTION>

Definition using a template fragment (comparable with a section template):

<CMS_FUNCTION name="legacyIf" resultname="name">
  <CMS_CDATA_PARAM name="trueCase">
    <![CDATA[
      BODY OF THE TEMPLATE FRAGMENT
    ]]>
  </CMS_CDATA_PARAM>
  ...
</CMS_FUNCTION>

Examples of the legacyIf function

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.

Example: Comparison of two character strings

<CMS_FUNCTION name="legacyIf" resultname="equalsString">
  <CMS_PARAM name="source" value="A character string" />
  <CMS_PARAM name="compareValue" value="ArACH" />
  <CMS_PARAM name="trueCase" value="character strings match" />
  <CMS_PARAM name="falseCase" value="character strings do NOT match" />
</CMS_FUNCTION>

In the example the evaluation checks whether the comparative character string ArACH is identical with the source character string A character string. As the comparison returns false the output is therefore Character strings do NOT match.

Print version | Page start