Magnolia 5.7 reached extended end of life on May 31, 2022. Support for this branch is limited, see End-of-life policy. Please note that to cover the extra maintenance effort, this EEoL period is a paid extension in the life of the branch. Customers who opt for the extended maintenance will need a new license key to run future versions of Magnolia 5.7. If you have any questions or to subscribe to the extended maintenance, please get in touch with your local contact at Magnolia.
catfn
templating functions get content by category (tag, label). For example, you can retrieve all pages tagged with travel
. Categories are typically rendered as links on the website. They help the visitor discover related interesting content.
Accessing categorized content
Categories of a node
Return all category Nodes linked to the given node.
Method signature
List<Node> getCategories(Node node)
List<Node> getCategories(Node node, String propertyName)
Arguments
node | required The node whose categories you want to get. |
propertyName | optional Categories with a specified property name. Default is |
Returns
List<Node>
A list of category node items.
Usage
catfn.getCategories(node, propertyName)
This page belongs to the categories: [#assign allCategories = catfn.getCategories(cmsfn.asJCRNode(content))] [#list cmsfn.asContentMapList(allCategories) as cat ] ${cat.name}, [/#list]
Related categories
Get all pages with categories related to the given category. Related categories are referenced in the Categories app.
Method signature
Collection<Node> getRelatedCategories(String name)
Arguments
name | required The category name |
Returns
Collection<Node>
A collection of Node items marked with related categories.
Usage
catfn.getRelatedCategories(name)
[#assign myCategory = "biochemistry"] [#assign relatedCategories = catfn.getRelatedCategories(myCategory)!] [#if relatedCategories?? && relatedCategories?size>0] ${myCategory} has the following related categories:<br/> [#list relatedCategories as cat ] ${cat.name} [#if cat_has_next], [/#if] [/#list] [#else] ${myCategory} has no related categories [/#if]
Content for given category
Gets a collection of content node items for a given category.
This function returns content only from the website
workspace. It does not work with other workspaces. I f you need to get categorized content from another workspace, write a custom model. See RelatedToursModel as an example.
Method signature
Collection<Node> getContentByCategory(Node node, String name)
Arguments
node | required The root node under which you want to look for content, such as the root page of a site. |
name | required Category name. |
Returns
Collection<Node>
A collection of node items assigned the given category.
Usage
catfn.getContentByCategory(node, name)
Aggregating content for a certain category which is applied to page nodes (start node is root node)<br/> The following pages are tagged with category "sports": [#assign rootPage = cmsfn.asJCRNode(cmsfn.root(content, "mgnl:page"))!] [#assign sportsContent = catfn.getContentByCategory(rootPage, "sports")] [#if sportsContent??] [#list sportsContent as catNode ] [#if catNode.isNodeType("mgnl:page")] [#assign link=cmsfn.link(catNode)] [#assign title=cmsfn.asContentMap(catNode).title!catNode.getName()] <a href="${link}">${title}</a><br/> [/#if] [/#list] [/#if]
Nodes by category identifier
Performs a JCR query call in the website
workspace to get all Nodes
with a given category identifier under a specified page path. The method doesn't filter for a certain node type. If required you have to filter for node types when iterating over the list.
Method signature
Collection<Node> getContentByCategoryIdentifier(String sitePath, String identifier)
Arguments
sitePath | required Page path. |
identifier | required Category identifier. |
Returns
Collection<Node>
A collection of node items for the given category identifier and path.
Usage
catfn.getContentByCategoryIdentifier(sitePath, identifier)
[#assign frisbeeCatUuid = "32708be2-6c62-4cca-8eb5-d95e9261011f"] [#assign categorizedNodes = catfn.getContentByCategoryIdentifier("/", frisbeeCatUuid)] [#if categorizedNodes?? && categorizedNodes?size>0] Our website contains some pages about "frisbee":<br/> [#list categorizedNodes as node ] [#if node.isNodeType("mgnl:page")] [#assign contentMap = cmsfn.asContentMap(node)] ${contentMap.title!node.getName()}<br/> [/#if] [/#list] [#else] No pages found related to the category with the uuid "${frisbeeCatUuid}" [/#if]
Category workspace
Gets the name of the category
workspace. When using a search method where you have to provide the workspace name use this function instead of using a hardcoded literal.
Method signature
String getCategorizationRepository()
Returns
String
Usage
catfn.getCategorizationRepository()
[#assign myCatNode = cmsfn.nodeByPath("/all/sports/frisbee", catfn.getCategorizationRepository())!]
Category node by name
Get the Node
representing the category defined by categoryName
.
Method signature
Node getCategoryNodeByName(final String categoryName)
Arguments
categoryName | required The category name |
Returns
Node
Usage
catfn.getCategoryNodeByName(categoryName)
[#assign frisbeeNode = catfn.getCategoryNodeByName("frisbee")!] [#if frisbeeNode??]The node was created by ${cmsfn.metaData(cmsfn.asContentMap(frisbeeNode), "mgnl:createdBy")!"Mr. X"}[/#if]
Create a category link
Creates a link to the category overview page. The categoryName
is added to the URL as a selector.
Method signature
String getCategoryLink(Node categoryOverviewPage, String categoryName)
Arguments
categoryOverviewPage | required Category overview page as a Node. Use |
categoryName | required Name of a category. |
Returns
String
Returns a link (as String) to the category overview page for the selected category.
Example return value:
/magnoliaAuthor/category-overview~travel~.html
Usage
catfn.getCategoryLink(categoryOverviewPage, categoryName)
[#assign rootPage = cmsfn.root(content, "mgnl:page")! ] [#assign searchRoot = cmsfn.asJCRNode(rootPage)! ] [#assign catOverviewPage = catfn.getCategoryOverviewPage(searchRoot)! ] <a href="${catfn.getCategoryLink(catOverviewPage, "travel")!}">Travel</a>
Get the category overview page
Gets the category overview page as a Node. Category overview is a special page template that helps visitors discover related content. A visitor typically arrives to the page after clicking a category link. The page shows what other content is tagged with the same category.
The Category Overview page definition includes the properties type=feature
and subtype=categoryOverview
. The getCategoryOverviewPage
function searches for a page that has these properties.
You can limit the search to a specific site or branch by passing the root page node in the searchRoot
argument.
Method signature
Node getCategoryOverviewPage(Node searchRoot)
Arguments
searchRoot | required The parent page |
Returns
Node
Category overview page as a Node.
Usage
catfn.getCategoryOverviewPage(searchRoot)
[#assign rootPage = cmsfn.root(content, "mgnl:page")! ] [#assign searchRoot = cmsfn.asJCRNode(rootPage)! ] [#assign catOverviewPageNode = catfn.getCategoryOverviewPage(searchRoot)! ]
Get a page based on template type
and subtype
Gets a page based on the type
and subtype
of its page definition. This is a generic version of the getCategoryOverviewPage()
function above. You can provide any values for the type
and subtype
properties. Use this function for example to find a custom category page that you have defined yourself.
You can limit the search to a specific site or branch by passing the root page node in the siteRoot
argument.
Method signature
Node getContentByTemplateCategorySubCategory(Node siteRoot, String type, String subtype)
Arguments
type | required Value of the |
subType | required Value of the |
siteRoot | required Root |
Returns
Node
A node item matching the given type
and subtype
.
Usage
catfn.getContentByTemplateCategorySubCategory(siteRoot, type, subtype)
[#assign rootPage = cmsfn.root(content, "mgnl:page")! ] [#assign siteRoot = cmsfn.asJCRNode(rootPage)! ] ${catfn.getContentByTemplateCategorySubCategory(siteRoot, "feature", "tutorial")!}