Frontend Developer Manual / 6.5.3 Blueprint (bp)

Frontend Developer Manual / Version 2201

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

Filter

Frontend Developer Manual / Version 2201

6.5.3 Blueprint (bp)

bp.isActiveNavigation(navigation, navigationPathList)

bp.setting(self, key, [default])

bp.generateId([prefix])

bp.truncateText(text, [maxLength])

bp.truncateHighlightedText(text, [maxLength])

bp.isEmptyRichtext(richtext)

bp.previewTypes(page, self, [defaultFragmentViews])

bp.getStackTraceAsString(exception)

bp.isWebflowRequest

bp.getDisplayFileSize(size, locale)

bp.getDisplayFileFormat(mimeType)

bp.isDisplayableImage(blob)

bp.isDisplayableVideo(blob)

bp.getLinkToThemeResource(path)

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

bp.getPageMetadata(page)

bp.getPlacementPropertyName(placement)

bp.getContainer(items)

bp.getDynamizableContainer(object, propertyPath)

bp.getContainerFromBase(baseContainer, [items])

bp.getPageLanguageTag(object)

bp.getPageDirection(object)

bp.getPlacementHighlightingMetaData(placement)

bp.responsiveImageLinksData(picture, [aspectRatios])

bp.getBiggestImageLink(picture, aspectRatio)

bp.transformedImageUrl(picture, aspectRatio, width, height)