navfn
- Related topics
navfn
templating functions allow you to create navigation for your
site. There are methods to access standard pages and also content stored
in apps and rendered on virtual pages. The navfn
templating function
library is included in the MTE
module.
Accessing ancestors
Getting the root page
Returns the highest ancestor page of type mgnl:page for the provided content - which is the root page.
Method signature
ContentMap
rootPage(ContentMap content)
Usage
navfn.rootPage(content)
[#assign navigationRootPage = navfn.rootPage(content)!]
Returns the ancestor of the provided content at the specified depth if the ancestor is of type mgnl:page.
Method signature
ContentMap
ancestorPageAtLevel(ContentMap content, int depth)
Argument
Argument | Description |
---|---|
|
required The node whose ancestors you want to get. |
|
required The page depth. An ancestor of depth x is the page that is x levels down along the path from the root page to this page. e.g. depth == 1 would return the root page of this page, depth == 2 would return the child page of the root page to this page, etc. |
Accessing children
Getting child pages of a page
Returns the list of child nodes of type mgnl:page which aren’t hidden in navigation of the the provided page as a list of content maps.
Usage
navfn.navItems(page)
<!-- render links to all pages on "level 1" -->
[#assign navParentItem = navfn.rootPage(content)!]
[#if navParentItem??]
[#assign navItems = navfn.navItems(navParentItem)]
[#list navItems as navItem]
<a href="${cmsfn.link(navItem)!}">${navItem.navigationTitle!navItem.title!navItem.@name}</a> |
[/#list]
[/#if]
Getting child nodes by workspace, path and node type
Returns the list of child nodes with specific node type which aren’t hidden in navigation from a defined parent as a list of content maps. The workspace and parent path define the location of the parent. Use this method to render navigations for content stored in content apps on workspaces distinct from website.
Method signature
List<``ContentMap
> navItemsFromApp(String workspace, String parentPath, String nodeType)
Checking templates
Checking for a specified template
Checks whether the given page has the specified template.
Checking for a specified template type
Checks whether the given page has the specified template type.
Accessing URLs
Getting a page URL with a selector
Returns a page URL with a selector (delimited by the ~ [tilde]
character) identifying the content to be rendered. This relies on
Magnolia’s
selector
mechanism, for example
https://demopublic.magnolia-cms.com/tour-typebeach.html
Getting a page URL with a parameter
Returns a page url with a parameter identifying the content to be
rendered.
A link of this type is produced
http://mysite/mypage.html?parameterName=mycontent
where `mypage' is
the node name of the target page, `mycontent' the node name of the
content.
Method signature
String linkWithParameter(ContentMap page, ContentMap content)
String linkWithParameter(ContentMap page, ContentMap content, String parameterName)
Argument
Argument | Description |
---|---|
|
required The page whose URL you want to get. |
|
required The content from the content app. For example contact, tour, etc. |
|
optional, default is <workspace-name> The parameter name. |
Usage
navfn.linkWithParameter(page, content)
<a href="${navfn.linkWithParameter(page, navContentItem)!"#"}">${navContentItem.lastName!navContentItem.@name}</a>
navfn.linkWithParameter(page, content, parameterName)
<a href="${navfn.linkWithParameter(page, navContentItem, "contacts")!"#"}">${navContentItem.lastName!navContentItem.@name}</a>
Checking navigation items
Checking for current page
Checks whether navigation item is the currently displayed content.
Checking for ancestor of a nav item
Checks whether navigation item is the ancestor of the current page.
Checking if content should be hidden in navigation
Checks whether the given content should be hidden in navigation. The
hideInNav
property of the given content is used.
Checking if content should not be hidden in navigation
Checks whether the given content should not be hidden in navigation. The
hideInNav
property of the given content is used.
Checking for property values
This is small helper method which checks if a given property is true or false. The method is needed because in a FreeMarker template you don’t know if a property is stored as boolean or a string or if it exists at all.
The method avoids using checks like:
[#if navItem.showInNav?has_content && navItem.showInNav?string == "true"]
Argument
Argument | Description |
---|---|
|
required The content node. |
|
required The property name. |
Usage
navfn.isTrue(content, propertyName)
[#if navfn.isTrue(navItem, "showInNav")] ... [/#if]
if navParentItem??] list navItems as navItem] latexmath:[${navItem.navigationTitle!navItem.title!navItem.@name}</a> | [/#list] [/#if]]]></ac:plain-text-body></ac:structured-macro><h3>Getting child nodes by workspace, path and node type</h3><p>Returns the list of child nodes with specific node type which aren't hidden in navigation from a defined parent as a list of content maps. The workspace and parent path define the location of the parent. Use this method to render navigations for content stored in content apps on workspaces distinct from website.</p><h4>Method signature</h4><p><code>List<<ac:link ac:anchor="info.magnolia.jcr.util.ContentMap"><ri:page ri:content-title="Templating function arguments and return types" /><ac:plain-text-link-body><![CDATA[ContentMap]]></ac:plain-text-link-body></ac:link>> navItemsFromApp(String workspace, String parentPath, String nodeType)</code></p><h4>Argument</h4><table class="wrapped"><colgroup> <col /> <col /> </colgroup><tbody><tr><td><code>workspace</code></td><td><p><strong>required</strong></p><p>The workspace of the parent node.</p></td></tr><tr><td colspan="1"><code>parentPath</code></td><td colspan="1"><p><strong>required</strong></p><p>The path of the parent node whose children you want to get.</p></td></tr><tr><td colspan="1"><code>nodeType</code></td><td colspan="1"><p><strong>required</strong></p><p>The node type of the children you want to get.</p></td></tr></tbody></table><h4>Returns</h4><p><code>List<ContentMap></code></p><h4>Usage</h4><p><code>navfn.navItemsFromApp(workspace, parentPath, nodeType)</code></p><ac:structured-macro ac:name="code" ac:schema-version="1" ac:macro-id="993765e0-d1d2-4835-812f-c93ca20b264e"><ac:parameter ac:name="language">xml</ac:parameter><ac:plain-text-body><![CDATA// tag::#assign navContentItems = navfn.navItemsFromApp("contacts", "/", "mgnl:contact")] if]]]></ac:plain-text-body></ac:structured-macro><h2>Accessing URLs</h2><h3>Getting a page URL with a selector</h3><p><ac:inline-comment-marker ac:ref="2a5afdd4-33ae-41bc-900e-32e6d6fa6d4c">Returns a page URL with a selector (delimited by the ~ [tilde] character) identifying the content to be rendered. This relies on Magnolia's <ac:link ac:anchor="Selectors"><ri:page ri:content-title="Location, location, location" /><ac:plain-text-link-body><![CDATA[selector mechanism[]></ac:plain-text-link-body></ac:link>, </ac:inline-comment-marker>for example <span class="nolink"> <code>https://demopublic.magnolia-cms.com/tour-type~beach~.html</code></span></p><h4>Method signature</h4><p><code>String linkWithSelector(ContentMap page, ContentMap content)</code></p><h4>Argument</h4><table class="wrapped"><colgroup> <col /> <col /> </colgroup><tbody><tr><td><code>page</code></td><td><p><strong>required</strong></p><p>The page whose URL you want to get.</p></td></tr><tr><td colspan="1"><code>content</code></td><td colspan="1"><p><strong>required</strong></p><p>The content from the content app. For example contact, tour, etc.</p></td></tr></tbody></table><h4>Returns</h4><p><code>String</code></p><h4>Usage</h4><p><code>navfn.linkWithSelector(page, content)</code></p><ac:structured-macro ac:name="code" ac:schema-version="1" ac:macro-id="06065c0e-68dc-49e6-bd26-7abb845f9e70"><ac:parameter ac:name="language">xml</ac:parameter><ac:plain-text-body><![CDATA[<a href="$]\{navfn.linkWithSelector(page, navContentItem)!`#`}``>latexmath:[${navContentItem.lastName!navContentItem.@name}</a>]]></ac:plain-text-body></ac:structured-macro><h3>Getting a page URL with a parameter</h3><p>Returns a page url with a parameter identifying the content to be rendered.<br />A link of this type is produced <code>http://mysite/mypage.html?parameterName=mycontent</code> where 'mypage' is the node name of the target page, 'mycontent' the node name of the content.</p><h4>Method signature</h4><p><code>String linkWithParameter(ContentMap page, ContentMap content)</code></p><p><code>String linkWithParameter(ContentMap page, ContentMap content, String parameterName)</code></p><h4>Argument</h4><table class="wrapped"><colgroup> <col /> <col /> </colgroup><tbody><tr><td><code>page</code></td><td><p><strong>required</strong></p><p>The page whose URL you want to get.</p></td></tr><tr><td colspan="1"><code>content</code></td><td colspan="1"><p><strong>required</strong></p><p>The content from the content app. For example contact, tour, etc.</p></td></tr><tr><td colspan="1"><code>parameterName</code></td><td colspan="1"><p><strong>optional</strong>, <em>default</em> is <workspace-name></p><p>The parameter name.</p></td></tr></tbody></table><h4>Returns</h4><p><code>String</code></p><h4>Usage</h4><p><code>navfn.linkWithParameter(page, content)</code></p><ac:structured-macro ac:name="code" ac:schema-version="1" ac:macro-id="83c23a9d-9755-4d49-ab32-c62ad1bd9c64"><ac:parameter ac:name="language">xml</ac:parameter><ac:plain-text-body><![CDATA[<a href="$]\{navfn.linkWithParameter(page, navContentItem)!''#`}`>latexmath:[${navContentItem.lastName!navContentItem.@name}</a>]]></ac:plain-text-body></ac:structured-macro><p><code> <span>navfn.linkWithParameter(page, content, <span>parameterName</span>)</span> </code></p><ac:structured-macro ac:name="code" ac:schema-version="1" ac:macro-id="e696d6a1-1b96-478e-95f1-8a70c5d2a7d9"><ac:parameter ac:name="language">xml</ac:parameter><ac:plain-text-body><![CDATA[<a href="$]\{navfn.linkWithParameter(page, navContentItem, `contacts'')!``#''}``>latexmath:[${navContentItem.lastName!navContentItem.@name}</a>]]></ac:plain-text-body></ac:structured-macro><h3>Getting a URL for provided content</h3><p>Returns a URL for the provided content.</p><h4>Method signature</h4><p><code>String link(ContentMap content)</code></p><h4>Argument</h4><table class="wrapped"><colgroup> <col /> <col /> </colgroup><tbody><tr><td><code>content</code></td><td><p><strong>required</strong></p><p>The content for which <span>you want to get URL</span>.</p></td></tr></tbody></table><h4>Returns</h4><p><code>String</code></p><h4>Usage</h4><p><code>navfn.<span>link(content)</span> </code></p><ac:structured-macro ac:name="code" ac:schema-version="1" ac:macro-id="2c36a264-8e25-4d07-90ba-7a5487d6cdb4"><ac:parameter ac:name="language">xml</ac:parameter><ac:plain-text-body><![CDATA[<a href="$]\{navfn.link(navigationItem)!''#``}`>$\{navigationItem.navigationTitle!navigationItem.title!navigationItem.@name}]]>
Checking navigation items
Checking for current page
Checks whether navigation item is the currently displayed content.
Method signature
boolean isActive(ContentMap content, ContentMap navigationItem)
Argument
content
required
The current content node (page/area/component).
navigationItem
required
The navigation item.
Returns
boolean
Usage
navfn.isActive(content, navigationItem)
xml
Checking for ancestor of a nav item
Checks whether navigation item is the ancestor of the current page.
Method signature
boolean isOpen(ContentMap content, ContentMap navigationItem)
Argument
content
required
The current content node.
navigationItem
required
The navigation item.
Returns
boolean
Usage
navfn.isOpen(content, navigationItem)
xml
Checking if content should be hidden in navigation
Checks whether the given content should be hidden in navigation. The hideInNav property of the given content is used.
Method signature
boolean isHiddenInNav(ContentMap content)
Argument
content
required
The content node.
Returns
boolean
Usage
navfn.isHiddenInNav(content)
xml
Checking if content should not be hidden in navigation
Checks whether the given content should not be hidden in navigation. The hideInNav property of the given content is used.
Method signature
boolean isNotHiddenInNav(ContentMap content)
Argument
content
required
The content node.
Returns
boolean
Usage
navfn.isNotHiddenInNav(content)
xml
Checking for property values
This is small helper method which checks if a given property is true or false. The method is needed because in a FreeMarker template you don’t know if a property is stored as boolean or a string or if it exists at all.
The method avoids using checks like:
xml
Method signature
boolean isTrue(ContentMap content, String propertyName)
Argument
content
required
The content node.
propertyName
required
The property name.
Returns
boolean
Usage
navfn.isTrue(content, propertyName)
xml
–>