Magnolia 5.4 reached end of life on November 15, 2018. This branch is no longer supported, see End-of-life policy.
cmsfn
templating functions traverse the JCR repository, get content, and create links. Helper functions convert objects from one type to another.
This page only lists the most commonly used functions. See TemplatingFunctions Javadoc for the complete list.
The function examples on this page require sample content. Look at each example to figure out what kind of content it needs.
Example: children
is a function that retrieves the children of the current node. To get meaningful results you need to execute the code on a page that has some children.
<ul> [#list cmsfn.children(content, "mgnl:page") as child ] <li>${child.title!}</li> [/#list] </ul>
To create sample content:
hello.ftl
script from the Hello Magnolia tutorial, for example.Your page structure could look like this:
The animals
page contains the example code. It has child pages and the children have titles. When you request the page the example code renders a list:
- Cats
- Dogs
- Monkeys
Retrieves content by a given path from a workspace. The function retrieves content from the website
workspace by default.
ContentMap contentByPath(String path)
path | required The path where the content is stored. |
workspace | optional , default is The workspace where the content map is stored. The function retrieves content from the |
ContentMap
cmsfn.contentByPath(path, workspace)
[#assign myResource = cmsfn.contentByPath("/sample-css/", "resources")] ${myResource.text!}
Node nodeByPath(String path, String workspace)
. Retrieves a node by a given path from a workspace.Retrieves content by ID from a workspace. The function retrieves content from the website
workspace by default.
ContentMap contentById(String id, String workspace)
id | required The identifier whose content map you want to get. |
workspace | optional , default is The workspace where the content map is stored. The function retrieves content from the |
ContentMap
cmsfn.contentById(id, workspace)
[#assign myResource = cmsfn.contentById("79fca5a6-b104-417b-a107-25b94ebc3961", "resources")] [#if myResource??] ${myResource.text!} [/#if]
Node nodeById(String id, String workspace)
. Retrieves a node by ID from a workspace.
Node getReferencedContent(Node content, String idPropertyName, String referencedWorkspace)
. Retrieves referenced content by a given content node, workspace and property. The content node you pass to this function must contain a property whose value identifies the referenced content.Find content objects by given template ID, below a given search root. Use this function to find pages that use a particular template, to aggregate content from similar pages, or to check where a template is used before deleting it from the system. You can limit the results to a set number, and add AND and ORDER BY parameters in SQL syntax.
List<Node> contentListByTemplateId(Node searchRoot, String templateId)
List<Node> contentListByTemplateId(Node searchRoot, String templateId, int maxResultSize, String andClause, String orderByClause)
searchRoot | required The node to use as root for the search. |
templateIds | required The template IDs to search for. |
maxResultSize | optional Integer that sets the max number of results returned. This can significantly improve query performance. |
andClause | optional AND clause in SQL syntax excluding the word "AND", for example "date IS NOT NULL". |
orderByClause | optional ORDER BY clause in SQL syntax, excluding the words "ORDER BY", for example "date desc" or "date asc". |
List<Node>
cmsfn.contentListByTemplateId(searchRoot, templateId)
cmsfn.contentListByTemplateId(searchRoot, templateId, maxResultSize, andClause, orderByClause)
Show the paths to all pages done with the template "hello" [#assign currentNode = cmsfn.asJCRNode(content)] [#assign rootPageNode = cmsfn.root(currentNode, "mgnl:page")!] [#if rootPageNode??] [#assign helloPages=cmsfn.contentListByTemplateId(rootPageNode, "hello-magnolia:pages/hello")] [#if helloPages??] [#list helloPages as child ] ${cmsfn.asContentMap(child).title!}, [/#list] [/#if] [/#if]
List<Node> contentListByTemplateIds(Node searchRoot, Set<String> templateIds, int maxResultSize, String andClause, String orderByClause)
. Retrieves content by a list of template IDs. This function takes many template IDs instead of only one.Retrieves the page that the passed content belongs to. For example, when you pass the content of a component to this function you get the parent page back. If the passed content has no parent page, which is the case for content managed in a content app and stored outside the website
workspace, null is returned. If the passed content represents a page, then the passed content is returned.
ContentMap page(ContentMap content)
content | required The content map whose page you want to find. |
ContentMap
cmsfn.page(content)
[#assign pageNode = cmsfn.page(content)!"unknown"] The title of the page node is ${pageNode.title}
Node page(Node content)
. Same as above but takes a node as an argument instead of a content map.Creates a link to a given node.
String link(ContentMap contentMap)
contentMap | required The node you want to link to, as a content map. |
String
cmsfn.link(contentMap)
[#assign rootNode = cmsfn.contentByPath("/home")] <a href="${cmsfn.link(rootNode)}">${rootNode.title!}</a>
String link(Node node)
String link(String workspace, String nodeIdentifier)
Creates an external link by using the property value of the given node.
String externalLink(ContentMap content, String linkPropertyName)
content | required The node where the link property is stored. |
linkPropertyName | required The name of the property where the link reference is stored. |
String
cmsfn.externalLink(content, linkPropertyName)
[#assign externalLink = cmsfn.externalLink(content, "linkTypeExternal")!] [#if externalLink??] <a href="${externalLink}">external link</a> [/#if]
String externalLink(Node content, String linkPropertyName)
Returns the title for a link using the property values of the given node. If the linkTitlePropertyName
property is null, the method falls back to the same method with 2 parameters, hence returning the link.
String externalLinkTitle(ContentMap content, String linkPropertyName, String linkTitlePropertyName)
content | required The node where the link property is stored. |
linkPropertyName | required The name of the property where the link reference is stored. |
linkTitlePropertyName | required The name of the property where the title is stored. |
String
cmsfn.externalLink(content, linkPropertyName, linkTitlePropertyName)
[#assign linkText = cmsfn.externalLinkTitle(cmsfn.decode(content), "linkTypeExternal", "title")!]
String externalLink(Node content, String linkPropertyName, linkTitlePropertyName)
Gets the link prefix by a given node. For instance the result is /<contextPath>
or something more complex if there is a URI2Repository mapping for the given node.
String linkPrefix(Node content)
content | required The node you want to get the link prefix for. |
String
cmsfn.linkPrefix(content)
[#assign prefix = cmsfn.linkPrefix(cmsfn.asJCRNode(content))!""] prefix = ${prefix}
Returns a map of localized links to the current node. This means: If you have defined three locales en
, de_DE
and de_CH
the function returns localized links to the node of the context on which you are applying the function. (If the current content node is a component, the function searches the parent page node.) Magnolia 5.4.1+
Example: The map could look like this:
Key | Value |
---|---|
en | /magnoliaAuthor/travel/about.html |
de_DE | /magnoliaAuthor/de_DE/travel/about.html |
de_CH | /magnoliaAuthor/de_CH/travel/about.html |
public Map<String, String> localizedLinks()
Map<String, String>
cmsfn.localizedLinks()
[#-- Build language navigation. --] [#assign localizedLinks = cmsfn.localizedLinks()!] [#if localizedLinks?has_content] [#assign languages = localizedLinks?keys] <ul> [#list languages as lang] [#assign current = cmsfn.isCurrentLocale(lang)] [#-- Use "compress" to put "li" and "a" on one line to prevent white spaces. --] <li>[@compress single_line=true] [#-- Current locale should not be linked. --] [#if current]${lang!}[/#if] [#if !current]<a href="${localizedLinks[lang]!'#'}">${lang!}</a>[/#if] [/@compress]</li> [/#list] </ul> [/#if]
Converts a node to a content map.
ContentMap asContentMap(Node content)
content | required The node you want to convert. |
ContentMap
cmsfn.asContentMap(content)
[#assign myNode = cmsfn.nodeByPath("/hello")] [#assign myMap = cmsfn.asContentMap(myNode)] ${myMap.title!}
Converts a collection of nodes to a list of content map items
List<ContentMap> asContentMapList(Collection<Node> nodeList)
nodeList | required The node collection you want to convert to a content map list. |
List<ContentMap>
List of content map items.
cmsfn.asContentMapList(nodeList)
[#assign currentNode = cmsfn.asJCRNode(content)] [#assign childrenNodesAsContentMaps = cmsfn.asContentMapList(cmsfn.children(currentNode, "mgnl:page"))] [#list childrenNodesAsContentMaps as child ] ${child.title!}, [/#list]
Converts a content map to a node.
Node asJCRNode(ContentMap contentMap)
contentMap | required The content map you want to convert. |
Node
cmsfn.asJCRNode(contentMap)
[#assign myNode = cmsfn.nodeByPath("/hello")] [#assign myMap = cmsfn.asContentMap(myNode)] ${myMap.title!}
Converts a content map collection to a list of nodes.
List<Node> asNodeList(Collection<ContentMap> contentMapList)
contentMapList | required The content map collection you want to convert to a list of nodes. |
List<Node>
List of nodes
cmsfn.asNodeList(contentMapList)
[#assign myMapList = cmsfn.children(content, "mgnl:page")] [#list cmsfn.asNodeList(myMapList) as child] ${cmsfn.parent(child)!}, [/#list]
Retrieves all the children (direct descendants) of the given node. If you don't specify a nodeType
the function will return all types of nodes, which is probably not what you want. A page typically has at least two kinds of child nodes: areas and pages. If you want just the pages then specify the node type mgnl:page
.
List<ContentMap> children(ContentMap content)
List<ContentMap> children(ContentMap content, String nodeTypeName)
content | required The node whose children you want to get. |
nodeTypeName | optional Type of the expected return nodes. |
List<ContentMap>
A list of ContentMap
items, in the case of the child nodes
cmsfn.children(content, nodeTypeName)
<ul> [#list cmsfn.children(content, "mgnl:page") as child ] <li>${child.title!}</li> [/#list] </ul>
List<Node> children(Node content)
List<Node> children(Node content, String nodeTypeName)
Retrieves the ancestors of a content map. You can specify a nodeType
to limit the types returned. If you don't all node types are returned.
List<ContentMap> ancestors(ContentMap contentMap)
List<ContentMap> ancestors(ContentMap contentMap, String nodeTypeName)
content | required The content map whose ancestors you want to get. |
nodeTypeName | optional Type of the expected return content map items. |
List<ContentMap>
List of ContentMap
items.
cmsfn.ancestors(contentMap, nodeTypeName)
Ancestor pages: [#list cmsfn.ancestors(content, "mgnl:page") as ancestor ] ${ancestor.title!}, [/#list]
List<Node> ancestors(Node content)
List<Node> ancestors(Node content, String nodeTypeName)
Retrieves the parent of a content map. You can specify a nodeType
to limit the types returned. If you don't all node types are returned.
ContentMap parent(ContentMap contentMap).
ContentMap parent(ContentMap contentMap, String nodeTypeName)
contentMap | required The content map whose parent you want to get. |
nodeTypeName | optional Type of the expected return content map items. |
ContentMap
cmsfn.parent(contentMap, nodeTypeName)
[#assign parent = cmsfn.parent(content, "mgnl:page")! ] Parent: ${parent.title!}
Node parent(Node content, String nodeTypeName)
. Same as above but takes a node as an argument instead of a content map.boolean isFromCurrentPage(ContentMap content)
. Checks if the passed content is from the current page.Retrieves the root content map of a content map. You can specify a nodeType
to limit the types returned. If you don't all types are returned.
ContentMap root(ContentMap contentMap)
ContentMap root(ContentMap contentMap, String nodeTypeName)
contentMap | required The content map whose root you want to get. |
nodeTypeName | optional Type of the expected return content map items. |
ContentMap
cmsfn.root(contentMap, nodeTypeName)
[#assign rootNode = cmsfn.root(content)! ] [#assign rootPage = cmsfn.root(content, "mgnl:page")! ] The root node title is ${rootNode.title!"not found"}<br/> The root page title is ${rootPage.title!}
Node root(Node content)
Node root(Node content, String nodeTypeName)
Retrieves the site root node by a given content map. The site root content map is defined as the page node with template type DefaultTemplateTypes#HOME
. If no ancestor page with this type is returned the JCR workspace root is returned.
ContentMap siteRoot(ContentMap content)
content | required The content map whose root node you want to get. |
ContentMap
cmsfn.siteRoot(content)
[#assign homeLink = cmsfn.link(cmsfn.siteRoot(content))!"/"]
Node siteRoot(Node content)
. Retrieves the site root by node.Checks whether the content is requested in the page editor in edit mode on the author instance.
boolean isEditMode()
boolean
cmsfn.isEditMode()
[#if cmsfn.editMode]You are in the edit mode<br/>[/#if] Is edit mode: ${cmsfn.isEditMode()?string}
Checks whether the content is requested in the page editor in preview mode. The check can be run either on the author instance or on the public instance.
boolean isPreviewMode()
boolean
cmsfn.isPreviewMode()
[#if cmsfn.previewMode]you are in the preview mode<br/>[/#if] is preview: ${cmsfn.isPreviewMode()?string}<br/>
Checks whether content is requested on the author instance.
boolean isAuthorInstance()
boolean
cmsfn.isAuthorInstance()
[#if cmsfn.authorInstance]you are on an author instance<br/>[/#if] is author instance: ${cmsfn.isAuthorInstance()?string}<br/>
Checks whether content is requested on the public instance.
boolean isPublicInstance()
boolean
cmsfn.isPublicInstance()
[#if cmsfn.publicInstance]you are on an public instance<br/>[/#if] is public instance: ${cmsfn.isPublicInstance()?string}<br/>
Removes escaping of HTML on properties in a content map.
When storing text to JCR, it is usually encoded. For instance brackets of HTML tags are stored as >
and <
. However, text stored with Rich text field stores some html which should be rendered as proper HTML and no as encoded text. In such a case use decode
method.
ContentMap decode(ContentMap content)
content | required The content map you want to removing escaping of HTML for. |
ContentMap
cmsfn.decode(content)
[#if content.text?has_content] ${cmsfn.decode(content).text} [/#if]
Node decode(Node content)
. Removes escaping of HTML on properties in a node.ContentMap encode(ContentMap content)
. Adds escaping of HTML on properties and changes line breaks into <br/>
tags in a content map.Node encode(Node content)
. Adds escaping of HTML on properties and changes line breaks into <br/>
tags in a node.Shortens a given string to a set length and adds the suffix " ..." (space, dot, dot, dot). Use this function to create teasers. Get the main content of a target page, shorten it to 100 characters, and render the shortened content in a teaser component.
String abbreviateString(String stringToAbbreviate, int length)
stringToAbbreviate | required The string you want to abbreviate. |
length | required The number of characters to shorten to. |
String
cmsfn.abbreviateString(stringToAbbreviate, length)
[#assign text = cmsfn.abbreviateString(text, 80)]
String abbreviateString(String stringToAbbreviate, int length, String suffix)
. Same as above but using a custom suffix such as "Read more".Retrieves the query string and fragment of a URL. Returns an empty string if none exists.
String queryStringAndFragment(String url)
url | required The URL whose query and fragment you want to get. |
String
cmsfn.queryStringAndFragment(url)
[#assign queryStringAndFragment = cmsfn.queryStringAndFragment("http://example.com#myApp::running?q=abcd")] Query string and fragment: ${queryStringAndFragment}
Retrieves the language currently used.
String language()
String
cmsfn.language()
<html xml:lang="${cmsfn.language()}" lang="${cmsfn.language()}" class="no-js">
Wraps content into a I18nNodeWrapper to deliver properties in a visitor's language. Use this function only if required. "Usually" content nodes are already "wrapped" having localized properties if they exist. Explicit wrapping using this function might be required when retrieving from a custom model class which may deliver unwrapped content nodes.
Node wrapForI18n(Node content)
content | required The content you want to wrap. |
Node
cmsfn.wrapForI18n(content)
[#assign specialNode = cmsfn.wrapForI18n(model.specialNode)]
The functions checks whether a given String representation of a locale is equal to the current locale. The current locale is the one selected by a user browsing on the website. (Note that the current locale is not the same as the browser locale.) Magnolia 5.4.1+
boolean cmsfn.isCurrentLocale(String locale)
boolean
locale | required String representation of a locale. |
cmsfn.isCurrentLocale("en")
[#if cmsfn.isCurrentLocale("en")] ... do something here ...[/#if]
Retrieves content metadata such as the author and date last modified. This function returns a string representation of the metadata property. This means that when you ask for a date you don't get a Date object back but a String.
String metaData(ContentMap content, String property)
content | required The content map whose metadata you want to get. | ||||||||||||||||||||||||
property | required Metadata property:
|
String
cmsfn.metaData(content, property)
This page was created by ${cmsfn.metaData(content, "mgnl:createdBy")!"nobody"}<br/> and last modified ${cmsfn.metaData(content, "mgnl:lastModified")!"never"}
String metaData(Node content, String property)
. Same as above but takes a node as an argument instead of a content map.Tries to determine the file extension of a filename by returning the suffix after the last dot.
String fileExtension(String fileName)
fileName | required The filename you want to get the extension for. |
String
cmsfn.fileExtension(fileName)
[#assign fileName = "/lirum-larum.JPG"] The extension of the file ${fileName} is "${cmsfn.fileExtension(fileName)}"
Returns a friendly, human-readable file size such as 120 kB. Use this function to provide approximate sizes of downloadable files, for example. See Apache's FileUtils
for more.
String readableFileSize(long sizeBytes)
sizeBytes | required The specific number of bytes. |
String
cmsfn.readableFileSize(sizeBytes)
[#assign fileSizeInBytes = 1321432216] The size of my file is ${fileSizeInBytes}, this means: ${cmsfn.readableFileSize(fileSizeInBytes)}