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

legacyContains

Using the legacyContains function

The legacyContains function is a comparative function which determines the occurrence of one or several sub-character strings in a specified character string (source character string).

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

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$

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".equals(IDENTIFIER))$
  ...
$CMS_ELSE$
  ...
$CMS_END_IF$

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

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 legacyContains function

The basic structure of the legacyContains function is as follows:

<CMS_FUNCTION name="legacyContains" resultname="IDENTIFIER">
  <CMS_VALUE_PARAM name="source" value="IDENTIFIER"/>
  <CMS_PARAM name="contains" value="CHARACTERSTRING"/>
  <CMS_PARAM name="ignoreCase" value="BOOLEAN"/>
  <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>

legacyContains function parameters

The legacyContains function can be specified with the following parameters:

contains
falseCase
ignoreCase
source
trueCase

The parameter source is a mandatory parameter. The contains parameter must be specified at least once and 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
contains	One or several comparable character strings (logically conjuncted by and)	X	O	O	yes
falseCase	Execution part if it does not contain any sub-character string	X	X	X	yes
ignoreCase	Ignore upper/lower case text (not case sensitive)	O	X	O	no
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

contains parameter

The contains parameter can be used to specify one or several sub-character strings the content of which is to be checked to see whether it is contained in the source character string (source parameter).

The individual contains parameters in the search are logically and conjuncted.

When defining a legacyContains function the contains parameter must be used at least once.

Definition with specification of a constant:

<CMS_FUNCTION name="legacyContains" resultname="name">
  <CMS_PARAM name="contains" value="CONSTANT" />
  <CMS_PARAM name="contains" value="CONSTANT" />
  ...
</CMS_FUNCTION>

falseCase parameter

The falseCase parameter is used to define an output value for the error case. If no occurrence of one (or several) sub-character strings (contains parameter) is found in the source character string (source parameter) 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 legacyContains function falseCase or trueCase must be specified.

Definition using a constant:

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

Definition using expressions:

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

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

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

ignoreCase parameter

Without definition of the ignoreCase parameter, upper and lower case of the sub-character string (i.e. case sensitivity) is taken into account in the comparison of the sub-character strings with the source character string (Boolean constant: false).

If the parameter ignoreCase is given with the Boolean constant true upper and lower case of the sub-character string are not taken into account.

Definition using a Boolean constant:

<CMS_FUNCTION name="legacyContains" resultname="name">
  <CMS_VALUE_PARAM name="ignoreCase" value="true" />
  ...
</CMS_FUNCTION>

<CMS_FUNCTION name="legacyContains" resultname="name">
  <CMS_VALUE_PARAM name="ignoreCase" value="false" />
  ...
</CMS_FUNCTION>

source parameter

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

When a legacyContains function is evaluated the occurrence of a sub-character string (contains parameter) is determined in the source character string.

The source parameter is a mandatory parameter.

Definition using a constant:

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

Definition using expressions:

<CMS_FUNCTION name="legacyContains" 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 at least one of the specified sub-character strings (contains parameter) is contained in the source character string (source parameter).

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 legacyContains function falseCase or trueCase must be specified.

Definition using a constant:

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

Definition using expressions:

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

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

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

Examples of the legacyContains 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.

1st Example: Specification of a sub-character chain

<CMS_FUNCTION name="legacyContains" resultname="containsString">
  <CMS_PARAM name="source" value="A character string" />
  <CMS_PARAM name="contains" value="ArACH" />
  <CMS_VALUE_PARAM name="ignoreCase" value="true" />
  <CMS_PARAM name="trueCase" value="contains sub-character string" />
  <CMS_PARAM name="falseCase" value="does NOT contain sub-character string" />
</CMS_FUNCTION>

In the example, during the evaluation the attempt is made to find the sub-character string ArACH in the source character string A character string. As upper and lower caps are not taken into account in the comparison the comparison returns true and therefore contains sub-character string is output.

2nd Example: Specifying several sub-character strings

<CMS_FUNCTION name="legacyContains" resultname="containsString">
  <CMS_PARAM name="source" value="A character string" />
  <CMS_PARAM name="contains" value="Weiche" />
  <CMS_PARAM name="contains" value="string" />
  <CMS_VALUE_PARAM name="ignoreCase" value="true" />
  <CMS_PARAM name="trueCase" value="contains sub-character string" />
  <CMS_PARAM name="falseCase" value="does NOT contain sub-character string" />
</CMS_FUNCTION>

In the example, during the evaluation the attempt is made to find the sub-character string Weiche and then string in the source character string A character string. As upper and lower caps are not taken into account in the comparison the comparison returns true and therefore contains sub-character string is output.

Print version | Page start