$CMS_RENDER(...)$
Using $CMS_RENDER(...)$
The $CMS_RENDER(...)$ instruction is used within a template
- to evaluate another output channel at the calling point
- to integrate the content of a format template
- to call a script
Syntax of $CMS_RENDER(...)$
When using $CMS_RENDER(...)$, the following syntax must be observed:
$CMS_RENDER(template:"IDENTIFIER",
IDENTIFIER_1:VALUE_1,
IDENTIFIER_2:VALUE_2,
...
IDENTIFIER_N:VALUE_N
)$
or
$CMS_RENDER(script:"IDENTIFIER",
IDENTIFIER_1:VALUE_1,
IDENTIFIER_2:VALUE_2,
...
IDENTIFIER_N:VALUE_N
)$
Multiple parameters can be separated using commas within a $CMS_RENDER(...)$ instruction, e.g.:
$CMS_RENDER(template:"tooltip", infoLayer:st_infoLayer)$
 |
All parameters except template and script are optional. |
$CMS_RENDER(#this, templateSet:"IDENTIFIER", pinTemplateSet:BOOLEAN)$
|
The parameter pinTemplateSet ist optional. |
$CMS_RENDER(...)$ parameters
$CMS_RENDER(...)$ has the following parameters:
Include source code of another output channel
Via the syntax #this, templateSet:"IDENTIFIER", the source code of another output channel of the same template is output at the corresponding position.
The optional parameter pinTemplateSet can be used to define whether the call of other templates in this source text should also take place in the called output channel (true, default value) or whether this should switch back to the original output channel (false).
$CMS_RENDER(#this, templateSet:"IDENTIFIER", pinTemplateSet:BOOLEAN)$
Integrating the content of a format template (template)
The template parameter defines the format template to be integrated at the current position of a template.
$CMS_RENDER(template:"IDENTIFIER",...)$
The IDENTIFIER is the abbreviation for the format template to be integrated.
The template version of the template set that has just been generated is always used by default.
Script calls within a template (script)
Scripts which were created in the project as a “Template” script type (see Scripting area) can be used via the $CMS_RENDER(...)$ instruction from a page or section template as well as from links:
$CMS_RENDER(script:"IDENTIFIER",...)$
The IDENTIFIER is the reference name of the script to be activated.
The template version of the template set that has just been generated is always used by default.
User-specified parameters
Any number of user-specified parameters can also be transferred to the format template or script using the instruction.
The identifier of a parameter is separated from the value by a colon (:).
However, each user-specified parameter is separated by a comma (,):
...,IDENTIFIER_1:"VALUE_1",IDENTIFIER_2:OBJEKT_2, ...,IDENTIFIER_N:"VALUE_N"
Either an object, variable, or textual value (placed within double quotation marks) can be transferred as the value.
The value is then available in the format template or in the script under the IDENTIFIER, e.g.:
$-- Page template: --$
$CMS_RENDER(template:"Output",variable:"VALUE")$
$-- Format template "Output": --$
Output: $CMS_VALUE(variable)$
or
$-- Page template: --$
$CMS_RENDER(script:"ScriptOutput",variable:"VALUE")$
$-- Script "ScriptOutput": --$
//!BeanShell
result.setValue(gc.getVariableValue("variable"));
|
The identifiers template, script, or version should not be used for user-specified parameters. |
Examples of $CMS_RENDER(...)$
Below are some examples of how to use the instruction within templates. The purpose of the examples is to point out the precise effect of the instruction and to assist template developers in creating their own templates.
|
The examples shown here must be adapted before they can be used within a project. For example, variable names need to be adapted to the specific variable names of the project in which the instruction is to be used. |
1st example: Conditional output using a format template
Code example:
$-- Page template: --$
$CMS_RENDER(template:"DefaultLayoutTemplate",style:true,value:"Value")$
$-- Format template "DefaultLayoutTemplate": --$
$CMS_IF(style)$
<b>$CMS_VALUE(value)$</b>
$CMS_ELSE$
<i>$CMS_VALUE(value)$</i>
$CMS_END_IF$
Description:
Depending on the value of the style transfer parameter, the value specified for value is output with formatting. If the style value is set to true, the value is output in bold; if the value is set to false, it is output in italics.
Output:
<b>Value</b>
2nd example: Output in conjunction with a script
Code example:
$-- Page template: --$
$CMS_RENDER(script:"ScriptOutput",value:"Value")$
$-- Script "ScriptOutput": --$
//!BeanShell
result.setValue(gc.getVariableValue("value"));
Description:
The ScriptOutput script outputs the value of the value transfer parameter.
Output:
Value
3rd example: Working with template fragments (and different contexts)
Using $CMS_SET(...)$ blocks and $CMS_RENDER(...)$ calls, template fragments can be included within a template and used as a type of “local function”:
$CMS_SET(_local_template)$
[Content]
$CMS_END_SET$
$CMS_RENDER(template: _local_template, _variant_class: "variant-1")$
[Inhalte]
$CMS_RENDER(template: _local_template, _variant_class: "variant-2")$
The following code example shows how this works in detail:
$CMS_SET(param, "Value A")$ <!--set initial value -->
$CMS_SET(set_param1)$
[Inside CMS_SET_BLOCK] $CMS_VALUE(param)$
$--Try to overwrite outer param from inside CMS_RENDER call --$
$CMS_SET(param, "Value C")$
$CMS_END_SET$
[A] $CMS_VALUE(param)$<br>
[B] $CMS_RENDER(set_param1, param:"Value B")$ => is not overwritten by CMS_SET of param!<br>
[C] $CMS_VALUE(param)$<br>
[D] $CMS_VALUE(set_param1)$<br>
[E] $CMS_VALUE(param)$ => now param has a different value as CMS_VALUE does not create a separate scope here!<br>
Description:
The example illustrates how variables are handled in different contexts within a template (for more information about contexts see also Chapter Variables and contexts in FirstSpirit). Using a $CMS_SET(...)$ block, template fragments can be defined which can then be executed again and again within the template. The call remains the same but the values are redefined each time the call is made (in contrast to object allocation via $CMS_SET(...)$).
The $CMS_SET(param, "Value A")$ instruction is used within the template to define the param variable and to assign the “Value A” initial value to the variables (object allocation).
Using $CMS_SET(set_param1)$ [Inside CMS_SET_BLOCK] $CMS_VALUE(param)$$CMS_END_SET$, a template fragment is generated within the existing template. The code contained in the body of the template fragment – here $CMS_VALUE(param)$ – is executed when the CMS_SET variable is evaluated (by means of $CMS_VALUE(set_param1)$ or $CMS_RENDER(set_param1, ...)$). However, there is one crucial difference:
The $CMS_RENDER(...)$ call generates a separate context (in contrast to the call via $CMS_VALUE(...)$) (see below).
The output for the example is as follows:
[A] Value A
[B] [Inside CMS_SET_BLOCK] Value B => is not overwritten by CMS_SET of param!
[C] Value A
[D] [Inside CMS_SET_BLOCK] Value A
[E] Value C => now param has a different value as CMS_VALUE does not create a separate scope here!
[A]: Output of the initially set value for the parameter (Value A).
[B]: Using call $CMS_RENDER(set_param1, param:"Value B")$, the param parameter is transferred with the Value B value. The $CMS_RENDER(...)$ call generates a separate context (in contrast to the call via $CMS_VALUE(...)$). As a result, no variables of the external context can be overwritten within the $CMS_SET(...)$ block (if the call is made via $CMS_RENDER(...)$). The $CMS_SET(param, "Value C")$ expression therefore does not take effect when the call is made via $CMS_RENDER(...)$.
[C] and [D]: The output using $CMS_VALUE(...)$ shows that the values of the variables have not changed (in the external context). When $CMS_VALUE(set_param1)$ is called, the $CMS_SET(...)$ block is executed again (but this time in the external context).
[E]: In this case, the parameter (in the external context) does actually change this time when the $CMS_SET(param, "Value C")$ expression is used.
4th example: Page template in which the content of the sections isn evaluated and prepared.
This should be done identically across several output channels.
Code example:
..
$CMS_RENDER(#this, templateSet:"logicChannel")$
$CMS_FOR(for_entry, set_valuelist)$
...
$CMS_END_FOR$
...
In the technical output channel logicChannel, the sections are then called up and the required information is stored in a list in the context of the page template:
$CMS_SET(set_valuelist, [])$
$CMS_VALUE(#global.page.body("myBody"))$
In the single sections, the information is then read out and added to the list (where set_resultvar is the result of the evaluation):
...
$CMS_SET(set_valuelist[set_valuelist.size], set_resultvar)$
5th example: In a section, a contentSelect function is to be used in different output channels.
However, in order to make them easier to maintain, this contentSelect function is only used once in a technical output channel:
...
$CMS_RENDER(#this, templateSet:"logicChannel")$
$CMS_FOR(for_entity, fr_myContentSelect.map(entity->entity.getDataset("<UID Tabletemplate>")))$
...
$CMS_END_FOR$
...
The following would then be found in the logicChannel:
<CMS_HEADER>
<CMS_FUNCTION name="contentSelect" resultname="fr_myContentSelect">
...
</CMS_FUNCTION>
</CMS_HEADER>
Unless the output of the datasets is specific to the single output channels, it also makes sense to output them directly in the logicChannel output channel, so that the corresponding code also only has to be maintained once.