close

Filter

loading table of contents...

Frontend Developer Manual / Version 2307

Table Of Contents

6.5.1 CoreMedia (cm)

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

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") />

Example 6.8. Making sure that a provided value is not cm.UNDEFINED


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}/>

Example 6.9. Include a template with view and parameters.


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>

Example 6.10. Returns the URL to this page.


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"/>

Example 6.11. Setting a template hook with 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"/>

Example 6.12. Set the content type for the HTTP response header.


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)/>

Example 6.13. Returns a single parameter from the localParameters map.


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 />

Example 6.14. Returns the localParameters as map.


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) />

Example 6.15. Use of cm.substitute().


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>

Example 6.16. Renders a localized button with the given key "button_close"


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>

Example 6.17. Renders a button with localized title


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

Example 6.18. Example of cm.message and cm.getMessage() with arguments


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>

Example 6.19. Checks if a translation for a message exists and translates the message key into a localized String.


Search Results

Table Of Contents
warning

Your Internet Explorer is no longer supported.

Please use Mozilla Firefox, Google Chrome, or Microsoft Edge.