cmsfn
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 info.magnolia.templating.functions.TemplatingFunctions for the complete list. |
Running the examples
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:
-
Put the code example into a page template script. You can use the
hello.ftl
script from the Hello Magnolia tutorial, for example. -
Create a page and assign the Hello template to it.
-
Create some child pages and give them titles.
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
Retrieving content
Content by path
Retrieves content by a given path from a
workspace. The function
retrieves content from the website
workspace by default.
Method signature
ContentMap
contentByPath(String path)
Arguments
Argument | Description |
---|---|
|
required The path where the content is stored. |
|
optional, default is The workspace where the
content map is stored. The function retrieves content from the |
Usage
cmsfn.contentByPath(path, workspace)
[#assign myResource = cmsfn.contentByPath("/sample-css/", "resources")] ${myResource.text!}
Related functions
-
Node
nodeByPath(String path, String workspace)
. Retrieves a node by a given path from a workspace.
Content by ID
Retrieves content by ID from a
workspace. The function
retrieves content from the website
workspace by default.
Method signature
ContentMap
contentById(String id, String workspace)
Arguments
Argument | Description |
---|---|
|
required The identifier whose content map you want to get. |
|
optional, default is The workspace where the
content map is stored. The function retrieves content from the |
Usage
cmsfn.contentById(id, workspace)
[#assign myResource = cmsfn.contentById("79fca5a6-b104-417b-a107-25b94ebc3961", "resources")] [#if myResource??] ${myResource.text!} [/#if]
Related functions
-
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.
Content by template ID
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.
Method signature
List<Node>
contentListByTemplateId(Node searchRoot, String templateId)
List<Node> contentListByTemplateId(Node searchRoot, String templateId, int maxResultSize, String andClause, String orderByClause)
Arguments
Argument | Description |
---|---|
|
required The node to use as root for the search. |
|
required The template IDs to search for. |
|
optional Integer that sets the max number of results returned. This can significantly improve query performance. |
|
optional AND clause in SQL syntax excluding the word "AND" (for example, "date IS NOT NULL"). |
|
optional ORDER BY clause in SQL syntax, excluding the words "ORDER BY" (for example, "date desc" or "date asc"). |
Usage
cmsfn.contentListByTemplateId(searchRoot, templateId)
cmsfn.contentListByTemplateId(searchRoot, templateId, maxResultSize, andClause, orderByClause)
[#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??]
<ul>
[#list helloPages as child ]
<li>${cmsfn.asContentMap(child).title!}</li>
[/#list]
</ul>
[/#if]
[/#if]
Page by content
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.
Method signature
ContentMap
page(ContentMap content)
Inheritance
The methods here related to node inheritance .
The inherit methods are seldom necessary because areas already support inheritance natively through configuration. |
Inherit components or properties
Wraps the provided node with an inheritance wrapper so that the node inherits the components and/or properties that exist in the equivalent ancestor nodes of the of the provided node’s anchor . This is typically the page node for the provided node.
Inheritance is subject to the inheritance configuration of the node, but can be overridden with the parameters of this method. |
Method signature
Node inherit(Node content, String relPath, String nodeTypes, String nodeInheritance, String propertyInheritance)
Arguments
Argument | Description | ||
---|---|---|---|
|
The node you want to inherit. |
||
|
If not blank, the node will inherit the node specified by this relative path rather than the actual provided node.
|
||
|
If not blank, only ancestors of the anchor with one of the |
||
|
Specifies which child components of the ancestors to inherit. |
||
|
Specifies which properties of the ancestors to inherit. |
Links
Create link to node
Creates a link to a given node.
Method signature
String link(ContentMap contentMap)
Create link from URL stored in node
Creates an external link by using the property value of the given node.
Method signature
String externalLink(ContentMap content, String linkPropertyName)
Arguments
Argument | Description |
---|---|
|
required The node where the link property is stored. |
|
required The name of the property where the link reference is stored. |
Usage
cmsfn.externalLink(content, linkPropertyName)
[#assign externalLink = cmsfn.externalLink(content, "linkTypeExternal")!] [#if externalLink??] <a href="${externalLink}">external link</a> [/#if]
Related functions
-
String externalLink(Node content, String linkPropertyName)
Get link title from URL stored in node
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.
Method signature
String externalLinkTitle(ContentMap content, String linkPropertyName, String linkTitlePropertyName)
Arguments
Argument | Description |
---|---|
|
required The node where the link property is stored. |
|
required The name of the property where the link reference is stored. |
|
required The name of the property where the title is stored. |
Usage
cmsfn.externalLink(content, linkPropertyName, linkTitlePropertyName)
[#assign linkText = cmsfn.externalLinkTitle(cmsfn.decode(content), "linkTypeExternal", "title")!]
Related functions
-
String externalLink(Node content, String linkPropertyName, linkTitlePropertyName)
Get link prefix by node
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.
Get localized links
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 to which you are
applying the function (if the current content node is a component, the
function searches the parent page node).
- Example
-
The map could look like this:
Key | Value |
---|---|
|
/magnoliaAuthor/travel/about.html |
|
/magnoliaAuthor/de_DE/travel/about.html |
|
/magnoliaAuthor/de_CH/travel/about.html |
Usage
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]
Converting nodes and content maps
Convert node to content map
Converts a node to a content map.
Method signature
ContentMap
asContentMap(Node content)
Convert node collection to content map list
Converts a collection of nodes to a list of content map items
Method signature
List<ContentMap> asContentMapList(Collection<Node> nodeList)
Convert content map to node
Converts a content map to a node.
Method signature
Node
asJCRNode(ContentMap contentMap)
Convert content map collection to node list
Converts a content map collection to a list of nodes.
Method signature
List<Node> asNodeList(Collection<ContentMap> contentMapList)
Traversing JCR hierarchy
Children
Retrieves all the children (direct descendants) of the given node. If
you don’t specify 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, specify the node
type mgnl:page
.
Method signature
List<ContentMap> children(ContentMap content, String nodeTypeName, String blockIntermediateNodeName)
The To use the parameter, you need to use the |
Arguments
Argument | Description |
---|---|
|
required The node whose children you want to get. |
|
optional Type of the expected return nodes. |
|
optional The property allows you to access content of the intermediate block nodes. In the Magnolia webapps, the name of the intermediate node is |
Usage
cmsfn.children(content, nodeTypeName)
<ul>
[#list cmsfn.children(content, "mgnl:page") as child ]
<li>${child.title!}</li>
[/#list]
</ul>
Related functions
-
List<Node> children(Node content)
-
List<Node> children(Node content, String nodeTypeName)
Ancestors
Retrieves the ancestors of a content map. You can specify nodeType
to limit the types returned. If you do not, all node types are returned.
Method signature
List<ContentMap> ancestors(ContentMap contentMap)
List<ContentMap> ancestors(ContentMap contentMap, String nodeTypeName)
Arguments
Argument | Description |
---|---|
|
required The content map whose ancestors you want to get. |
|
optional Type of the expected return content map items. |
Usage
cmsfn.ancestors(contentMap, nodeTypeName)
Ancestor pages:
<ul>
[#list cmsfn.ancestors(content, "mgnl:page") as ancestor ]
<li>${ancestor.title!}</li>
[/#list]
</ul>
Related functions
-
List<Node> ancestors(Node content)
-
List<Node> ancestors(Node content, String nodeTypeName)
Parent
Retrieves the parent of a content map. You can specify nodeType
to
limit the types returned. If you do not, all node types are returned.
Method signature
ContentMap
parent(ContentMap contentMap)
ContentMap parent(ContentMap contentMap, String nodeTypeName)
Arguments
Argument | Description |
---|---|
|
required The content map whose parent you want to get. |
|
optional Type of the expected return content map items. |
Root
Retrieves the root content map of a content map. You can specify a
nodeType
to limit the types returned. If you do not, all types are
returned.
Method signature
ContentMap
root(ContentMap contentMap)
ContentMap root(ContentMap contentMap, String nodeTypeName)
Arguments
Argument | Description |
---|---|
|
required The content map whose root you want to get. |
|
optional Type of the expected return content map items. |
Usage
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!}
Related functions
-
Node
root(Node content)
-
Node root(Node content, String nodeTypeName)
Site root
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.
Method signature
ContentMap
siteRoot(ContentMap content)
Dumping an object’s structure and content hierarchy
Dump
Inspects the structure and content of the given object upto the given depth and outputs it either in plain text form or, optionally, in a simple HTML format.
Arguments
Argument | Description |
---|---|
|
required Specifies the object type to be inspected. The following objects are available in the default implementation of this inspector function:
|
|
optional, default is Specifies the depth of the inspection. |
|
optional, default is Output into a simple HTML format. |
System state helpers
Check for edit mode
Checks whether the content is requested in the page editor in edit mode on author instance.
Check for preview mode
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.
String manipulation
Decode HTML
Removes escaping of HTML on properties in a content map.
Text stored in the JCR is usually encoded. For instance, HTML
tag brackets are stored as >
and <
. However, the
rich
text field stores some HTML that should be rendered as proper HTML and
not as encoded text. In that case, use the decode
method.
Method signature
ContentMap
decode(ContentMap content)
Arguments
Argument | Description |
---|---|
|
required The content map you want to removing escaping of HTML for. |
Related functions
-
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.
Shorten string
Shortens a given string to a set length and adds the suffix " …" (space followed by three periods). 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.
Arguments
Argument | Description |
---|---|
|
required The string you want to abbreviate. |
|
required The number of characters to shorten to. |
Request
Language
See also Get localized links above.
Current language
Retrieves the language currently used.
Usage
cmsfn.language()
<html xml:lang="${cmsfn.language()}" lang="${cmsfn.language()}" class="no-js">
|
Wrap content in i18n node wrapper
Wraps content in info.magnolia.jcr.wrapper.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.
Method signature
Node
wrapForI18n(Node content)
Metadata
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.
Method signature
String metaData(ContentMap content, String property)
Arguments
Argument | Description | ||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
required The content map whose metadata you want to get. |
||||||||||||||||||
|
required
|
File helpers
File extension
Tries to determine the file extension of a filename by returning the suffix after the last dot.
File size
Returns a friendly, human-readable file size such as 120 kB. Use this function, for example, to provide approximate sizes of downloadable files.
See Apache FileUtils
for more.