Functions

Functions can be used to give the output a certain level of dynamics (e.g., HTML pages). Functions enable content entered once by the editor to be output on the website flexibly, linked to particular conditions, for example, and offer functional enhancements for templates.

Header functions

Functions can be defined inside <CMS_HEADER> tags (“header function”) or inside instructions. Only valid XML may be entered inside <CMS_HEADER> tags. Alternatively, functions can also be generated and inserted by a BeanShell script.
A <CMS_HEADER> tag can be used in any kind of template for which a function is to be defined in the template set (see for page templates, for example). Header functions are executed just once, when a page is generated. Only functions which are known to the server can be used in template management; these are explained on the following pages.

In FirstSpirit, header functions can perform the following tasks:

• Defining variables, calculating and evaluating expressions (define function)
• Checking and evaluating entries made by the editor (define function)
• Rendering texts on an existing background image (Font function)
• Outputting tables with a complex layout (Table function)
• Outputting data (filtered and/or sorted) from the data store (contentSelect function)
• Evaluating structures from the site store for navigation (see Navigation function).
  This is possible for menu groups (MenuGroup function)
  or page groups (PageGroup function) in particular

Syntax of header functions

The basic structure of header functions is as follows:

<CMS_FUNCTION name="FUNCTION_IDENTIFIER" resultname="IDENTIFIER">
  <CMS_PARAM name="PARAMETER_NAME" value="CONSTANT" />
  <CMS_VALUE_PARAM name="PARAMETER_NAME" value="EXPRESSION" />

      <CMS_CDATA_PARAM name="PARAMETER_NAME">
          <![CDATA[
            ...
          ]]>
      </CMS_CDATA_PARAM>

</CMS_FUNCTION>

Every CMS function is enclosed within a <CMS_FUNCTION> tag. The name and resultname attributes must be set here:

• The value defined for name is the function identifier, which can be used to call up the function
• The identifier of the return variable which saves the function’s result is defined in resultname

Transferring parameters

In principle, values can be transferred to a header function as follows:

define function example:

1) <CMS_PARAM>
When using

<CMS_PARAM name="source" value="constant" />

the return value of the define function is specified in the constant string.

2) <CMS_VALUE_PARAM>
When using

<CMS_VALUE_PARAM name="source" value="constant" /> 

the return value of the define function is specified in the constant expression.

3) <CMS_CDATA_PARAM>

Template fragments can be transferred via <CMS_CDATA_PARAM> (or <CMS_ARRAY_PARAM> for the Navigation function and <CMS_NODE_PARAM> for the Table function), e.g.,

<CMS_CDATA_PARAM name="delimiter">
     <![CDATA[VALUE]]>
</CMS_CDATA_PARAM> 

If a value contains quotation marks, valid XML can be generated in one of the following ways:

Enclosing in single quotation marks:

<CMS_PARAM name="source" value='A "constant" with quotation marks' />

Masking with HTML entities:

<CMS_PARAM name="source" value="A &quot;constant&quot; with quotation marks" />

Parameter transfer using the "define” function

Multiple functions can be used in the header – even multiple functions of different types. The define function can be used to define variables or expressions, which can then in turn be used by another header function of the same template.

In a different function of the header, the value of a “define” function is fallen back to via <CMS_VALUE_PARAM>.

This enables header functions to be linked to entries made by the editor (e.g., in input components), structure variables, or project settings.

Example:

The following “define” function saves the value of an input component with the identifier st_text (e.g., CMS_INPUT_TEXT) in the variable ft_text:

<CMS_FUNCTION name="define" resultname="ft_text">
   <CMS_VALUE_PARAM name="source" value="st_text" />
</CMS_FUNCTION>

If the following Font function is defined in the same header area

<CMS_FUNCTION name="Font" resultname="font">
    <CMS_PARAM name="width" value="240" />
   <CMS_PARAM name="size" value="30" />
   <CMS_PARAM name="font" value="Courier" />
   <CMS_PARAM name="media" value="pic" />
   <CMS_PARAM name="color" value="#000000" />
   <CMS_PARAM name="boxjustify" value="center" />
   <CMS_PARAM name="boxvalign" value="center" />
   <CMS_PARAM name="justify" value="left" />
   <CMS_VALUE_PARAM name="text" value="ft_text" />
</CMS_FUNCTION>

and this is output outside the header area using

<img src="$CMS_REF(font)$" />

the text which the editor enters into the input component with the identifier st_text is used for the Font function, so the text is therefore output on the image with the identifier pic.

Calling/outputting functions

Functions can be called up wherever method calls can also be used. Unlike methods, however, functions do not refer to an object:

Every function has a function identifier, which can be used to call it up. One or more parameters can be transferred, depending on the type of the function. In addition to the transferred parameters, functions also have local variables, which are only valid inside the function. Some functions provide the result of the execution as a return value.

Syntax:

$CMS_VALUE(methodName([Arguments]))$

Empty check

For functions, an isEmpty check does not relate to whether the evaluated function result is empty, but to the function object. Therefore, .isEmpty always results in false, e.g.,

$CMS_VALUE(fr_pt_mainNavi.isEmpty)$

In order to check whether the result of a Navigation function is empty, for example, the following syntax can be used instead:

$CMS_VALUE(fr_pt_mainNavi.toString.isEmpty)$

However, it can take a lot of processing time to execute this call, depending on the scope of the project.