navfn

FreeMarker development only

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

ContentMaprootPage(ContentMap content)

Argument

Argument Description

Argument	Description
`content`	required The node whose ancestors you want to get.

content

required

The node whose ancestors you want to get.

Returns

ContentMap

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

ContentMapancestorPageAtLevel(ContentMap content, int depth)

Argument

Argument Description

Argument	Description
`content`	required The node whose ancestors you want to get.
`depth`	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.

content

required

The node whose ancestors you want to get.

depth

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.

Returns

ContentMap

Usage

navfn.ancestorPageAtLevel(content, depth)

[#assign subNavigationRootPage = navfn.ancestorPageAtLevel(content, 2)!]

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.

Method signature

List<ContentMap> navItems(ContentMap page)

Argument

Argument Description

Argument	Description
`page`	required The page whose child pages you want to get.

page

required

The page whose child pages you want to get.

Returns

List<ContentMap>

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)

Argument

Argument Description

Argument	Description
`workspace`	required The workspace of the parent node.
`parentPath`	required The path of the parent node whose children you want to get.
`nodeType`	required The node type of the children you want to get.

workspace

required

The workspace of the parent node.

parentPath

required

The path of the parent node whose children you want to get.

nodeType

required

The node type of the children you want to get.

Returns

List<ContentMap>

Usage

navfn.navItemsFromApp(workspace, parentPath, nodeType)

[#assign navContentItems = navfn.navItemsFromApp("contacts", "/", "mgnl:contact")]
[#list navContentItems as navItem]
    [#-- do something with the navItem here --]
[/#list]

Checking templates

Checking for a specified template

Checks whether the given page has the specified template.

Method signature

boolean hasTemplate(ContentMap page, String template)

Argument

Argument Description

Argument	Description
`page`	required The page whose template you want to check.
`template`	required The template to check for.

page

required

The page whose template you want to check.

template

required

The template to check for.

Returns

boolean

Usage

navfn.hasTemplate(page, template)

[#if navfn.hasTemplate(content, "mtk2:pages/contacts")]
  [#-- do something here --]
[/#if]

Checking for a specified template type

Checks whether the given page has the specified template type.

Method signature

boolean hasTemplateType(ContentMap page, String templateType)

Argument

Argument Description

Argument	Description
`page`	required The page whose template you want to check.
`templateType`	required The template type to check for.

page

required

The page whose template you want to check.

templateType

required

The template type to check for.

Returns

boolean

Usage

navfn.hasTemplateType(ContentMap page, String templateType)

[#if navfn.hasTemplateType(content, "section")]
  [#-- do something here --]
[/#if]

Checking for specified template subtype

Checks whether the given page has the specified template subtype.

Method signature

boolean hasTemplateSubtype(ContentMap page, String templateSubtype)

Argument

Argument Description

Argument	Description
`page`	required The page whose template you want to check.
`templateSubType`	required The sub-template type to check for.

page

required

The page whose template you want to check.

templateSubType

required

The sub-template type to check for.

Returns

boolean

Usage

navfn.hasTemplateSubtype(page, templateSubtype)

[#if navfn.hasTemplateSubtype(navItem, "contactsOverview")]
    [#-- do something here --]
[/#if]

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-type_beach.html

Method signature

String linkWithSelector(ContentMap page, ContentMap content)

Argument

Argument Description

Argument	Description
`page`	required The page whose URL you want to get.
`content`	required The content from the content app. For example contact, tour, etc.

page

required

The page whose URL you want to get.

content

required

The content from the content app. For example contact, tour, etc.

Returns

String

Usage

navfn.linkWithSelector(page, content)

<a href="${navfn.linkWithSelector(page, navContentItem)!"#"}">${navContentItem.lastName!navContentItem.@name}</a>

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

Argument	Description
`page`	required The page whose URL you want to get.
`content`	required The content from the content app. For example contact, tour, etc.
`parameterName`	optional, default is <workspace-name> The parameter name.

page

required

The page whose URL you want to get.

content

required

The content from the content app. For example contact, tour, etc.

parameterName

optional, default is <workspace-name>

The parameter name.

Returns

String

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>

Getting a URL for provided content

Returns a URL for the provided content.

Method signature

String link(ContentMap content)

Argument

Argument Description

Argument	Description
`content`	required The content for which you want to get URL.

content

required

The content for which you want to get URL.

Returns

String

Usage

navfn.link(content)

<a href="${navfn.link(navigationItem)!"#"}">${navigationItem.navigationTitle!navigationItem.title!navigationItem.@name}</a>

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

Argument Description

Argument	Description
`content`	required The current content node (page/area/component).
`navigationItem`	required The navigation item.

content

required

The current content node (page/area/component).

navigationItem

required

The navigation item.

Returns

boolean

Usage

navfn.isActive(content, navigationItem)

[#if navfn.isActive(content, navItem)]
    ...
[/#if]

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)

[#if navfn.isOpen(content, navItem)]
    ...
[/#if]

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

Argument Description

Argument	Description
`content`	required The content node.

content

required

The content node.

Returns

boolean

Usage

navfn.isHiddenInNav(content)

[#if !navfn.isHiddenInNav(navItem)]
   ...
[/#if]

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

Argument Description

Argument	Description
`content`	required The content node.

content

required

The content node.

Returns

boolean

Usage

navfn.isNotHiddenInNav(content)

[#if navfn.isNotHiddenInNav(navigationItem)]
    ...
[/#if]

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"]

Method signature

boolean isTrue(ContentMap content, String propertyName)

Argument

Argument Description

Argument	Description
`content`	required The content node.
`propertyName`	required The property name.

content

required

The content node.

propertyName

required

The property name.

Returns

boolean

Usage

navfn.isTrue(content, propertyName)

[#if navfn.isTrue(navItem, "showInNav")]
    ...
[/#if]