define
The define function is used to define a variable in the header area of a page or section template and to assign a value to the variable.
The define function can also be used to specify conditional checks. The function delivers different return values depending on whether a given condition is fulfilled or not.
Defining variables and assigning values can be effected as well by using the instruction $CMS_SET(...)$, the define function has been maintained primarily for compatibility reasons with FirstSpirit version 3.1. One argument for using the define is its prominent position at the beginning (header) of a template.
Syntax of the define function
The basic structure of the define function is as follows:
1) Definition of a string constant:
<CMS_FUNCTION name="define" resultname="IDENTIFIER">
<CMS_PARAM name="source" value="CONSTANT" />
</CMS_FUNCTION>
Example:
<CMS_FUNCTION name="define" resultname="name">
<CMS_PARAM name="source" value="A constant" />
</CMS_FUNCTION>
In the example the return value of the define function is specified on the string A constant.
2) Definition using expressions:
<CMS_FUNCTION name="define" resultname="IDENTIFIER">
<CMS_VALUE_PARAM name="source" value="EXPRESSION" />
</CMS_FUNCTION>
Example:
<CMS_FUNCTION name="define" resultname="name">
<CMS_VALUE_PARAM name="source" value="4 * 2 - 5" />
</CMS_FUNCTION>
The return value of the define function is specified with the expression 4 * 2 - 5.
3) Definition of a template fragment (comparable with a section template):
<CMS_FUNCTION name="define" resultname="IDENTIFIER">
<CMS_CDATA_PARAM name="source">
<![CDATA[
BODY OF THE TEMPLATE FRAGMENT
]]>
</CMS_CDATA_PARAM>
</CMS_FUNCTION>
 |
The name of the variable, the expression or the template fragment must be specified using the parameter source, for example for expressions: <CMS_VALUE_PARAM name="source" value="...">. |
|
For common notes about the syntax of header functions please see introducing Functions page. |
Return object of the function
The result of the define function can be output or used
- in the header area and/or
- in the HTML area
of the template.
A $CMS_VALUE(...)$ instruction is used for this in the HTML area, for example
<CMS_HEADER>
<CMS_FUNCTION name="define" resultname="fr_pt_define">
<CMS_...>
</CMS_FUNCTION>
</CMS_HEADER>
<html>
...
$CMS_VALUE(fr_pt_define)$
...
</html>
For an example about using the result of the function in the header area see introducing page Functions.
Examples of the define 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: Conditional evaluation
<CMS_FUNCTION name="define" resultname="name">
<CMS_CDATA_PARAM name="source">
<![CDATA[
$CMS_IF(!myVar.isEmpty)$
first_option
$CMS_ELSE$
second_option
$CMS_END_IF$
]]>
</CMS_CDATA_PARAM>
</CMS_FUNCTION>
In the code example given above the content of a variable myVar is checked. If the value of myVar is null, the return value of the define function returns the first_option or, if this condition is not fulfilled, the second_option.
2nd Example: Case differentiation
<CMS_FUNCTION name="define" resultname="name">
<CMS_CDATA_PARAM name="source">
<![CDATA[
$CMS_SWITCH(myVar.toString)$
Standard_option
$CMS_CASE("ABC")$
first_option
$CMS_CASE("DEF")$
second_option
$CMS_CASE("XYZ")$
n-th_option
$CMS_END_SWITCH$
]]>
</CMS_CDATA_PARAM>
</CMS_FUNCTION>
In the code example given above the content of a variable myVar is checked. If the value of myVar is ABC, the return value of the define function returns the first_option , if the value is DEF, it returns the second_option, etc.
Any number of different conditions can be checked. You can use instructions and functions for this.