Frontend Developer Manual / Version 2207
Table Of Contents
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") />
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
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.getId(self)
Determine this object's id through the IdProvider and return the id as a string.
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.