The CoreMedia FreeMarker API provides helpful macros and functions and is implicitly available in any FreeMarker template view rendered by the CAE. It uses the namespace cm for template calls.

cm.UNDEFINED

Returns a value representing that something is undefined as the FreeMarker template language has no build in support for null or undefined values. You will most likely encounter this value as a return value of various functions provided by our FreeMarker API. The value can be interpreted as a Boolean (false), a string (""), a sequence ([]) or a hash ({}) including all build-ins without needing additional checks to prevent rendering errors.

For example: Using the build-in ?has_content the code cm.UNDEFINED?has_content would return false which is exactly what would be expected from an empty string.

Use this value as a default value for parameters that should be ignored if not defined, like so:

<@cm.include self=self params={ "param1": param1!cm.UNDEFINED }/>

It also tells an include not to fail if the parameter for "self.related" is undefined:

<@cm.include self=self.related!cm.UNDEFINED/>

Caution

You might need this to distinguish cm.UNDEFINED value from an empty string or similar for various reasons. Please note that you cannot use build-ins such as == or != to check if a given value is cm.UNDEFINED as its value is equal to false and an empty string ("").

Please use one of functions described in the following sections instead.

cm.isUndefined(value)

Returns true if the given value is cm.UNDEFINED otherwise false.

cm.notUndefined(value, fallback)

Returns the value if it is not cm.UNDEFINED otherwise it will return the given fallback.

<#assign valueToUse=cm.notUndefined(providedValue, "hello") />

cm.include

This macro is the most important one. It includes a template for an object (self), using the view dispatcher instead of FreeMarker's built in include function. With the view parameter you can determine a specific template. Requires a template/view to be defined for such an object. For more information see Section 4.3.4, “Writing Templates” in Content Application Developer Manual.

Parameter	Required	Description
self		The target object for the view.
view		A specific template for this object.
params		Pass parameters into the included template.

Table 6.16. Parameters of cm.include

In this example the template CMArticle.teaser.ftl would be included without rendering a button, assuming that "article" has the type CMArticle.

<@cm.include self=article view="teaser" params={"showButton": false}/>

cm.getLink(target, [view], [params])

Create a link to the object passed as "target" in the given view and return the URL as a string. Requires a link scheme to be defined for the target object. If the target object is cm.UNDEFINED, an empty string is returned. For more information see paragraph "Linking" in Section 4.3.4, “Writing Templates” in Content Application Developer Manual.

Parameter	Required	Description
target		Object of which to render the link to.
view		String to specify a special view.
params		additional parameters given as a map.

Table 6.17. Parameters of cm.getLink

<a href="${cm.getLink(self)}">linktext</a>

cm.dataAttribute

Renders a serialized data attribute for HTML elements.

Parameter	Required	Description
name		Name for the attribute (the "data-" prefix is not added automatically)
data		An object containing values.

Table 6.18. Parameters of cm.dataAttribute

cm.hook

Renders the results of all com.coremedia.objectserver.view.events.ViewHookEventListener implementations that match the given type of self and that support the given ID and the parameters. For more information see Section 4.3.3.9, “View Hooks” in Content Application Developer Manual.

Parameter	Required	Description
id		String as identifier for the ViewHookEvent.
self		The object that the corresponding listeners have to support. Optional but defaults to "self" object from template context.
params		The parameters passed to the listener through the FreeMarker macro.

Table 6.19. Parameters of cm.hook

<@cm.hook id="page_end"/>

cm.getId(self)

Determine this object's id through the IdProvider and return the id as a string.

Parameter	Required	Description
self		Object to get ID of.

Table 6.20. Parameters of cm.getId

cm.responseHeader

Sets an HTTP response header. If the response is already committed, the macro will fail. For more information see Section 4.3.4, “Writing Templates” in Content Application Developer Manual.

Parameter	Required	Description
name		Name of the response header as String.
value		Value for the response header as String.

Table 6.21. Parameters of cm.responseHeader

<@cm.responseHeader name="Content-Type" value="text/html; charset=UTF-8"/>

cm.getRequestHeader(name)

Get an HTTP request header.

Parameter	Required	Description
name		Name of the header that should be returned.

Table 6.22. Parameters of cm.getRequestHeader

cm.localParameter(key, [defaultValue])

Returns a parameter from the localParameters map by given name or falls back to the given default.

Parameter	Required	Description
key		Description of the parameter.
defaultValue		A fallback if there are no value for the given key.

Table 6.23. Parameters of cm.localParameter

<#assign booleanExample=cm.localParameter("parameterName", false)/>

cm.localParameters()

Returns a map of all parameters set in a previous template.

<#-- all parameters: -->
<#assign examples=cm.localParameters() />

<#-- single parameters: -->
<#assign booleanExample=cm.localParameters().parameterName!false />

cm.substitute(id, [original], [default])

Fetching an action state (id) from an action object (original) and substitutes a bean. If the substitution result is null, it will fall back to default, which is cm.UNDEFINED by default. For more information see Section 5.4, “Content Placeholders” in Content Application Developer Manual.

Parameter	Required	Description
id		The substitution id.
original		The original bean.
default		Optional fallback bean. Default is UNDEFINED.

Table 6.24. Parameters of substitute

<<#-- @ftlvariable name="self" type="com.mycompany.Action" -->
<#assign substitutionID="example" />
<@cm.include self=cm.substitute(substitutionID, self) />

cm.message

Translates a message key into a localized message based on java.text.MessageFormat. This output is not escaped by default.

Parameter	Required	Description
key		Translates a message key into a localized message via Spring Framework.
args		Additional parameter as Array to enrich the output with functionality.
escaping		Additional Boolean parameter for escaping, default value is false.
highlightErrors		Specifies if errors should be highlighted, default value is true.

Table 6.25. Parameters of message

<button class="btn-close"><@cm.message "button_close"/></button>

cm.getMessage(key, [args], [highlightErrors])

Translates a message key into a localized message based on java.text.MessageFormat. Use ?no_esc to avoid escaping, if the message includes HTML.

Parameter	Required	Description
key		Translates a message key into a localized message.
args		Additional parameter to enrich the output with functionality.
highlightErrors		Specifies if errors should be highlighted, default value is false.

Table 6.26. Parameters of getMessage

<button class="btn-close" title="${cm.getMessage("button_close")}">X</button>

<#assign messageArgs=[5, "Hello World"] />
<div title="${cm.getMessage("search_results", messageArgs)}">
  <@cm.message key="search_results" args=messageArgs />
</div>

cm.hasMessage(key)

Checks if a translation for a given key exists.

Parameter	Required	Description
key		Checks if a message key exists, if no message found it will return an empty String.

Table 6.27. Parameter of hasMessage

<#assign titleKey=fragmentView.titleKey!""/>
<#if titleKey?has_content && (cm.hasMessage(titleKey))>
    <@cm.message titleKey/>
</#if>