close

Filter

loading table of contents...

Frontend Developer Manual / Version 2201

Table Of Contents

6.5.3 Blueprint (bp)

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


<img src="${bp.getLinkToThemeResource('img/logo.jpg')}"/>

Example 6.31. Using the path to an image.


See Section 5.7, “Referencing a Static Theme Resource in FreeMarker” to learn more about referencing static theme resources.

bp.getBlobLink(target, filename, [view], [params])

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.

Parameter Required Description
target Blob of which to render the link to.
filename The filename to use at the end of the blob url.

Table 6.43. Parameters of bp.getBlobLink


<a href="${bp.getBlobLink(self.localSettings.myBlob!cm.UNDEFINED)}">download</a>

Example 6.32. Returns the URL to a blob in the local settings.


bp.getPageMetadata(page)

Returns the first navigation context within the navigation hierarchy.

Parameter Required Description
page The page metadata of content.

Table 6.44. 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.33. 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.45. 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.34. 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.46. Parameter of getContainer


<#if self.related?has_content>
  <@cm.include self=bp.getContainer(self.related) view="related"/>
</#if>

Example 6.35. 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.47. 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.48. Parameters of getContainerFromBase


<@cm.include self=bp.getContainer(self.media)
             view="asTeaser"/>

Example 6.36. 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.49. Parameter of getPageLanguageTag


<!DOCTYPE html>
<html lang="${bp.getPageLanguageTag(cmpage!self)}">
...
</html>

Example 6.37. 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.50. Parameter of getPageDirection


<!DOCTYPE html>
<html dir="${bp.getPageDirection(cmpage!self)!'ltr'}">
...
</html>

Example 6.38. 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.51. Parameter of getPlacementHighlightingMetaData


<div <@preview.metadata data=[bp.getPlacementHighlightingMetaData(pagrid.placement)!""]/>>
  ...
</div>

Example 6.39. 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.52. 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.40. 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.53. Parameters of getBiggestImageLink


<#assign fullImageLink=bp.getBiggestImageLink(self, "exampleAspectRatioName")/>

<a href="${fullImageLink}" title="${self.title!""}" data-cm-popup="gallery">...</a>

Example 6.41. 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.54. Parameters of transformedImageUrl


<#assign mobileImageUrl=bp.transformedImageUrl(self, "2x3", "200", "300")/>

<img src="${mobileImageUrl}" alt="${self.title!""}" />

Example 6.42. Renders a specific size and aspect ratio of an image


Search Results

Table Of Contents
warning

Your Internet Explorer is no longer supported.

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