Start page
Start page
Start page

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

include Available up to FirstSpirit Version 4.0

The include function can be used to insert dynamic and static fragments within the <CMS_HEADER> tags. For example, fragments from the <CMS_HEADER> area can be entered and managed in a central location.

To integrate a static fragment an uninterpreted script is required and for a dynamic fragment a template script is required.

Important Use of the include function is not recommended. This function will be removed in a later version. Instead of the include function please use the $CMS_RENDER(..)$ instructions.

Static insertion of a define function with $CMS_RENDER(...)$ instruction

Instead of inserting an uninterpreted script using the include function it is recommended you realise this with a $CMS_RENDER(..)$ instruction in conjunction with a format template.

The combination from the uninterpreted script uninterpreted:

<CMS_FUNCTION name="define" resultname="uninterpretedScript">
  <CMS_CDATA_PARAM name="source"><![CDATA[Output of an uninterpreted script]]></CMS_CDATA_PARAM>
</CMS_FUNCTION>

and its use in a define function in a page template:

<CMS_HEADER>
  <CMS_FUNCTION name="include" resultname="void">
    <CMS_PARAM name="name"  value="uninterpreted" />
  </CMS_FUNCTION>
</CMS_HEADER>$CMS_VALUE(uninterpretedScript)$

can be rewritten as follows:

The content of the uninterpreted script is copied into a format template with the identifier templateFragment .
An opening <CMS_HEADER> tag is inserted in front of the opening <CMS_FUNCTION> tag.
A closing <CMS_HEADER> tag is inserted after the closing <CMS_FUNCTION> tag.

As the evaluation of a format template takes place in a separate context, the function cannot be accessed without adjustment. In order to be able to use the function in another context too (in this case in the context of the invoking template, e.g. page template, section template, etc.) we must use the attribute context. The value for the attribute is the context identifier in which the function is to be made available, e.g. section for the section template and PAGE for the page template.

Important The context attribute should only be used for this special case as variables with the same name in other contexts are overwritten by the attribute and therefore the availability can change.
E.g.: Section 1: Variable A is valid in Section 1 only. If the variable is put in the page context the Variable A with the value from Section 1 is also valid in Section 2. See also Chapter Contexts.

After the $CMS_RENDER(..)$ instruction the function is then available in the specified context.

To make the define function from the example available in the page function the context attribute with the value PAGE must be inserted in the <CMS_FUNCTION> tag.

The content of the format template is then roughly as follows:

<CMS_HEADER>
  <CMS_FUNCTION name="define" resultname="uninterpretedScript" context="PAGE">
    <CMS_CDATA_PARAM name="source"><![CDATA[Output of an uninterpreted script]]></CMS_CDATA_PARAM>
  </CMS_FUNCTION>
</CMS_HEADER>

Use of the format template in the page template is:

$CMS_RENDER(template:"templateFragment")$$CMS_VALUE(uninterpretedScript)$
Important Variables which are to be made available within the fragment must be defined before the $CMS_RENDER(...)$ instruction!

Dynamic insertion of a define function with $CMS_RENDER(...)$ instruction

Instead of inserting a script using the include function it is advisable to realise it with the help of a $CMS_RENDER(..)$ instruction.

The combination of an interpreted script:

//!BeanShell
out = new StringBuilder();
out.append("<CMS_FUNCTION name=\"define\" resultname=\"interpretedScript\">");
out.append("<CMS_CDATA_PARAM name=\"source\"><![CDATA[Output of an interpreted script<br>");
out.append("The value of the transfer parameter is:").append(output).append("]]></CMS_CDATA_PARAM>");
out.append("</CMS_FUNCTION>");
result.setValue(out.toString());

and its use in a define function in a page template:

<CMS_HEADER>
  <CMS_FUNCTION name="include" resultname="void">
    <CMS_PARAM name="name"  value="interpreted" />
    <CMS_PARAM name="output" value="OUTPUT VALUE" />
  </CMS_FUNCTION>
</CMS_HEADER>$CMS_VALUE(interpretedScript)$

can be rewritten as follows:

The script must be changed so that a template fragment is written in the context. To this end an opening and closing <CMS_FUNCTION> tag must be inserted. Here ParserUtil.parseTemplate(...) must be used to generate a template from the fragment and context.print(...) used to write the result in the context.
In addition, it must be noted that variables are not automatically available (in the above example: output), but instead context.getVariableValue(...) must be used to draw them from the context. After the changes the above example is as follows:

//!BeanShell
import de.espirit.firstspirit.generate.ParserUtil;

out = new StringBuilder();
out.append("<CMS_HEADER>");
out.append("<CMS_FUNCTION name=\"define\" resultname=\"interpretedScript\">");
out.append("<CMS_CDATA_PARAM name=\"source\"><![CDATA[Output of an interpreted script<br>");
out.append("The value of the transfer parameter is:").append(context.getVariableValue("output")).append("]]></CMS_CDATA_PARAM>");
out.append("</CMS_FUNCTION>");
out.append("</CMS_HEADER>");
context.print(ParserUtil.parseTemplate(out.toString()));

It is then invoked in the context as follows:

$CMS_SET(output, "OUTPUTVALUE")$
$CMS_RENDER(script:"interpreted")$
$CMS_VALUE(eval(interpretedScript))$

Syntax of the Include function

The basic structure of the include function is as follows:

<CMS_FUNCTION name="include" resultname="void">
  <CMS_PARAM name="name" value="IDENTIFIER" />
  <CMS_PARAM name="version" value="IDENTIFIER" />
  <CMS_VALUE_PARAM name="IDENTIFIER" value="VALUE" />
  <CMS_PARAM name="IDENTIFIER" value="VALUE" />
</CMS_FUNCTION>
Important The name parameter is a mandatory parameter. All other parameters are optional.

name parameter

The mandatory parameter name is used to specify the unique identifier of the script to be inserted.

version parameter

The optional parameter version can be used to specify the unique identifier of a presentation channel.

This is useful to avoid redundancies, for example if a BeanShell script is solely entered and maintained in a presentation channel.

If the parameter is not given the system attempts to insert the current presentation channel of the script.

User-specific parameters

In addition, user-specific parameters can be specified to make further information available to the scripts.

The parameter can be defined either as a constant:

<CMS_FUNCTION name="include" resultname="name">
  ...
  <CMS_PARAM name="source" value="A constant" />
</CMS_FUNCTION>

or as an expression:

<CMS_FUNCTION name="include" resultname="name">
  ...
  <CMS_VALUE_PARAM name="source" value="4 * 2 - 5" />
</CMS_FUNCTION>

The value of the parameter (value attribute) is available in a template script, under the identifier assigned for the name attribute:

...
print()IDENTIFIER);
...

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

Important 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: Static insertion of an uninterpreted script

The insertion of an uninterpreted script with the help of the include function can be realised as follows:

The content of the uninterpreted uninterpreted script is:

<CMS_FUNCTION name="define" resultname="uninterpretedScript">
  <CMS_CDATA_PARAM name="source"><![CDATA[Output of an uninterpreted script]]></CMS_CDATA_PARAM>
</CMS_FUNCTION>

The script is then inserted with the define function in a page template:

<CMS_FUNCTION name="include" resultname="void">
  <CMS_PARAM name="name"  value="uninterpreted" />
</CMS_FUNCTION>

The function is then invoked by means of:

$CMS_VALUE(uninterpretedScript)$

The output is:

Output of an uninterpreted script

Dynamic insertion of a define function with $CMS_RENDER(...)$ instruction

Starting with the content of the template script interpreted:

//!BeanShell
out = new StringBuilder();
out.append("<CMS_FUNCTION name=\"define\" resultname=\"interpretedScript\">");
out.append("<CMS_CDATA_PARAM name=\"source\"><![CDATA[Output of an interpreted script<br>");
out.append("The value of the transfer parameter is:").append(output).append("]]></CMS_CDATA_PARAM>");
out.append("</CMS_FUNCTION>");
result.setValue(out.toString());

If the script is inserted in a page template with the define function:

<CMS_FUNCTION name="include" resultname="void">
  <CMS_PARAM name="name"  value="interpreted" />
  <CMS_PARAM name="output" value="OUTPUT VALUE" />
</CMS_FUNCTION>

The function invocation is:

$CMS_VALUE(interpretedScript)$

The output is then:

Output of an interpreted script<br>
OUTPUTVALUE

Print version | Page start

© 2005 - 2012 e-Spirit AG | All rights reserved. | Last change: 09.08.2012