Frontend Developer Manual / Version 2207
Table Of Contents
The Blueprint FreeMarker API provides calls for blueprint specific functionality like settings, markup, images, and
localization. It also includes some typical helper utilities like ids, buttons and more.
It uses the namespace bp
for template calls.
bp.isActiveNavigation(navigation, navigationPathList)
Returns true if the given navigation
object is contained in the navigationPathList
.
Parameter | Required | Description |
---|---|---|
navigation
|
| Navigation object |
navigationPathList
|
| List of navigation objects to check |
Table 6.30. Parameters of isActiveNavigation
<#if (bp.isActiveNavigation(self, (cmpage.navigation.navigationPathList)![]))> <#assign cssClass=cssClass + ' active'/> </#if>
Example 6.22. Assign a CSS class if this element is part of the navigation list.
bp.setting(self, key, [default])
Returns a setting for a given key
or the default
value. The lookup for the given key will
first check the given ContentBean self
, secondly the context
, like the Page and finally
the theme.
Parameter | Required | Description |
---|---|---|
self
|
| Settings object. |
key
|
| Key for the wanted setting. |
default
| Possible default value. |
Table 6.31. Parameters of setting
<#assign maxDepth=bp.setting(self, "navigation_depth", 2) />
Example 6.23. Define a "maxDepth"
setting or default to 2
.
bp.generateId([prefix])
Generates a unique HTML element id with the given prefix.
Parameter | Required | Description |
---|---|---|
prefix
| The prefix to add to the id. |
Table 6.32. Parameters of generateId
<#assign formId=bp.generateId('example') /> <label for="${formId}">Label</label> <input id="${formId}" type="text" name="example">
Example 6.24. Generate an ID for a form input.
bp.truncateText(text, [maxLength])
Shortens a text
at the first space character after maxLength
.
Parameter | Required | Description |
---|---|---|
text
|
| Text to be truncated. |
maxLength
| Text length limit based on characters. |
Table 6.33. Parameters of truncateText
<@bp.truncateText(self.teaserText!"", bp.setting(cmpage, "text.max.length", 200)) />
Example 6.25. Shorten a teaser text to a limit, defined in the page settings or default to 200.
bp.truncateHighlightedText(text, [maxLength])
Same as bp.truncateText(text, maxLength)
, but it will keep highlighted elements. Used in search result pages.
Parameter | Required | Description |
---|---|---|
text
|
| Text to be truncated. |
maxLength
| Text length limit based on characters. |
Table 6.34. Parameters of truncateHighlightedText
bp.isEmptyRichtext(richtext)
Checks if the given richtext is empty without the richtext grammar.
Parameter | Required | Description |
---|---|---|
richtext
|
| The richtext to be checked. |
Table 6.35. Parameters of isEmptyRichtext
<#if !bp.isEmptyRichtext(self.teaserText!"")> <div class="cm-teaser__text"> <@cm.include self=self.teaserText /> </div> </#if>
Example 6.26. Check if the teaserText is empty.
bp.previewTypes(page, self, [defaultFragmentViews])
Returns the preview views of an object based on its hierarchy as a list.
Parameter | Required | Description |
---|---|---|
self
|
| The object to preview. |
page
|
| The page used to find the setting named "fragmentPreview". |
defaultFragmentViews
| A Map defining defaults. |
Table 6.36. Parameters of previewTypes
bp.getStackTraceAsString(exception)
Returns a string including the whole Java stack trace of an exception.
Parameter | Required | Description |
---|---|---|
exception
|
| Exception of which to return the stack trace. |
Table 6.37. Parameters of getStackTraceAsString
<textarea class="stacktrace">${bp.getStackTraceAsString(self)!""}</textarea>
Example 6.27. Assign the link to this CMVideo object to a variable.
bp.isWebflowRequest
Checks, if this current request is a Spring Web Flow request.
<#assign isWebflowRequest=bp.isWebflowRequest()/> <#assign fragmentLink=cm.getLink(self.delegate, "fragment", { "targetView": self.view!cm.UNDEFINED, "webflow": isWebflowRequest })/>
Example 6.28. Assign the link to this CMVideo object to a variable.
bp.getDisplayFileSize(size, locale)
Returns the entered size
in human readable format.
Parameter | Required | Description |
---|---|---|
size
|
| Size as integer. |
locale
|
Optional locale. If not set, the locale of the context (page) is used, if available.
Fallbacks to the locale of the RequestContext .
|
Table 6.38. Parameters of getDisplayFileSize
bp.getDisplayFileFormat(mimeType)
Returns the file extension for a given mimeType
.
For example "image/jpeg" would return "jpg".
Parameter | Required | Description |
---|---|---|
mimeType
|
| Mime type to translate into its file extension. |
Table 6.39. Parameters of getDisplayFileFormat
bp.isDisplayableImage(blob)
Checks if this blob
is of the mime type "image".
Parameter | Required | Description |
---|---|---|
blob
|
| Blob to be checked. |
Table 6.40. Parameters of isDisplayableImage
<#if self.blob?has_content && bp.isDisplayableImage(self.blob)> ...
Example 6.29. Check if this blob has content and is an image.
bp.isDisplayableVideo(blob)
Checks if this blob
is of the mime type "video".
Parameter | Required | Description |
---|---|---|
blob
|
| Blob to be checked. |
Table 6.41. Parameters of isDisplayableVideo
<#if self.blob?has_content && bp.isDisplayableImage(self.blob)> ...
Example 6.30. Check if this blob has content and is a video.
bp.getLinkToThemeResource(path)
Retrieves the URL path that belongs to a theme resource (image, web font, etc.) defined by its path within the theme folder. The path must not contain any descending path segments.
Parameter | Required | Description |
---|---|---|
path
|
| Path to the resource within the theme folder. |
Table 6.42. Parameters of getLinkToThemeResource
See Section 5.7, “Referencing a Static Theme Resource in FreeMarker” to learn more about referencing static theme resources.
bp.getPageMetadata(page)
Returns the first navigation context within the navigation hierarchy.
Parameter | Required | Description |
---|---|---|
page
|
| The page metadata of content. |
Table 6.43. Parameter of getPageMetadata
<html <@preview.metadata data=bp.getPageMetadata(self)!""/>> <@cm.include self=self view="_head"/> <@cm.include self=self view="_body"/> </html>
Example 6.32. Renders metadata information to the HTML tag
bp.getPlacementPropertyName(placement)
Returns the name of a given placement.
Parameter | Required | Description |
---|---|---|
placement
|
|
Returns the property name of a given PageGridPlacement or "" .
|
Table 6.44. Parameter of getPlacementPropertyName
<#-- This placement is used for the footer section --> <footer id="cm-${self.name!""}" class="cm-footer"<@preview.metadata [bp.getPlacementPropertyName(self)!"", bp.getPlacementHighlightingMetaData(self)!""]/>> ... </footer>
Example 6.33. Renders the placement name to the metadata section.
bp.getContainer(items)
Utility function to allow rendering of containers with custom items, for example, partial containers with an item subset of the original container.
Parameter | Required | Description |
---|---|---|
item
|
| The items to be put inside the new container. Returns a new container. |
Table 6.45. Parameter of getContainer
<#if self.related?has_content> <@cm.include self=bp.getContainer(self.related) view="related"/> </#if>
Example 6.34. Gets the container for a related view.
bp.getDynamizableContainer(object, propertyPath)
Utility function to render possibly dynamic containers. A dynamic container will be rendered for dynamic inclusion by caching infrastructure (ESI) or the client (AJAX). The decision, if a container is dynamic or not, is performed on the server side via DynamicContainerStrategy implementations and does not require any further client-side or template logic.
Parameter | Required | Description |
---|---|---|
object
|
| The object backing the dynamizable container. Can be a content bean producing a list of beans that may contain dynamic items, such as a personalized content bean. |
propertyPath
|
| A possible nested property path referencing the list of beans for inclusion. Example: If object is an instance of CMTeasable the property path 'related' references the teasable's related items. |
Table 6.46. Parameter of getDynamizableContainer
bp.getContainerFromBase(baseContainer, [items])
Utility function to allow rendering of containers with custom items, for example partial containers with an item subset of the original container.
Parameter | Required | Description |
---|---|---|
baseContainer
|
| The base container from which the new container should be created. |
items
| The items to be put inside the new container. |
Table 6.47. Parameters of getContainerFromBase
<@cm.include self=bp.getContainer(self.media) view="asTeaser"/>
Example 6.35. A new container is created with a new subset of items and rendered as a teaser
bp.getPageLanguageTag(object)
Renders the value of the lang
attribute for the HTML
tag.
Parameter | Required | Description |
---|---|---|
object
|
| Object to determine the locale from IETF BCP 47 language code. |
Table 6.48. Parameter of getPageLanguageTag
<!DOCTYPE html> <html lang="${bp.getPageLanguageTag(cmpage!self)}"> ... </html>
Example 6.36. Renders the value of the lang attribute.
bp.getPageDirection(object)
Renders the value of the dir
attribute for the HTML
tag according to the locale of the page.
Parameter | Required | Description |
---|---|---|
object
|
|
Object to determine the locale direction from "ltr" or "rtl" .
|
Table 6.49. Parameter of getPageDirection
<!DOCTYPE html> <html dir="${bp.getPageDirection(cmpage!self)!'ltr'}"> ... </html>
Example 6.37. Renders the value of the dir attribute.
bp.getPlacementHighlightingMetaData(placement)
Returns a map which contains information about the state of the given placement. The map contains information about the name, and if it is in the layout and if it has items.
Parameter | Required | Description |
---|---|---|
placement
|
| The placement of a pagegrid to get the information for. |
Table 6.50. Parameter of getPlacementHighlightingMetaData
<div <@preview.metadata data=[bp.getPlacementHighlightingMetaData(pagrid.placement)!""]/>> ... </div>
Example 6.38. Renders a div with additional data attribute containing information about the state of the placement.
bp.responsiveImageLinksData(picture, [aspectRatios])
Adds responsive relevant image data as additional attribute to a picture.
Parameter | Required | Description |
---|---|---|
picture
|
| The given image. |
aspectRatios
| List of aspect ratios to use for this image. |
Table 6.51. Parameters of responsiveImageLinksData
<#if self.data?has_content> <#assign classResponsive="cm-media--responsive"/> <#assign attributes += {"data-cm-responsive-media": bp.responsiveImageLinksData(self)!""}/> <img src="#" ${classResponsive!""}" <@bp.renderAttr attributes/> </#if>
Example 6.39. Adding responsive attribute data to an image
bp.getBiggestImageLink(picture, aspectRatio)
Returns the image link of the biggest image for a given aspect ratio, defined in the Responsive Image Settings.
Parameter | Required | Description |
---|---|---|
picture
|
| The CMPicture image for which an URL should be rendered. |
aspectRatio
| The given aspect ratio, the default value is "". |
Table 6.52. Parameters of getBiggestImageLink
<#assign fullImageLink=bp.getBiggestImageLink(self, "exampleAspectRatioName")/> <a href="${fullImageLink}" title="${self.title!""}" data-cm-popup="gallery">...</a>
Example 6.40. Renders the biggest image link of a page
bp.transformedImageUrl(picture, aspectRatio, width, height)
Returns the link for an image in the given aspect ratio, width and height.
Parameter | Required | Description |
---|---|---|
picture
|
| The CMPicture image for which an URL should be rendered. |
aspectRatio
|
| The given aspect ratio. |
width
|
| The given width in px. |
height
|
| The given height in px. |
Table 6.53. Parameters of transformedImageUrl
<#assign mobileImageUrl=bp.transformedImageUrl(self, "2x3", "200", "300")/> <img src="${mobileImageUrl}" alt="${self.title!""}" />
Example 6.41. Renders a specific size and aspect ratio of an image
bp.getBlobLink(target, filename, [view], [params])
deprecated
Create a link to the blob passed as "target" in the given view and return the URL as a string. If the link to the blob could not be created or the blob is cm.UNDEFINED, an empty string is returned.
This function is deprecated, please use the default link function
cm.getLink(target, cm.UNDEFINED, { "filename": filename });
instead.