NavTool Viewtool

The $navtool Velocity viewtool allows you to create custom navigations with your own HTML and styles. It builds a navigation structure given a path or folder level, and returns a list of navigation items.

Usage

You can use the NavTool through both methods and properties, all of which return an object representing a folder in the dotCMS folder tree.

Methods

The getNav() method allows you to access the current folder or to pass in different parameters to access a folder on your site via an absolute path or a relative folder level.

Note: When passing in a level rather than a path, the path will be built from the request URI (e.g. the path as it is displayed in the user's browser) rather than the actual path to the page within dotCMS. For pages which have been accessed via a Vanity URL or URL Map, the request URI is not the actual path of the page being displayed, so an attempt to display the navigation using level will not work. Therefore, to display menus that may be displayed on pages used via Vanity URLs or URL Maps (such as top-level navigation), it is recommended that a path be passed instead of a level.

Parameters

The getNav() method accepts either a string (a folder path) or an integer (a folder level) as an argument. Both arguments are referenced from the root of the site where the page is located.

Method Examples

The following examples describe which folder is returned for different calls to $navtool.getNav() if the method call is made from the “/about-us/locations/index” page on the dotCMS starter site or dotCMS demo site.

Properties

If you specify the $navtool object directly, it returns the nav object of the current active folder (where the page is located). This is equivalent to calling $navtool.getNav() (with no arguments).

You may specify the properties of the $navtool object directly (without first having to assign the results to a Velocity variable), and you may chain the properties. This allows you to easily access nav objects for folders relative to the current folder with a single Velocity reference.

Property Examples

The following examples describe which folder is returned for different NavTool property references if the reference is made from the “/about-us/locations/index” page on the dotCMS starter site or dotCMS demo site.

Return Value and Properties

The navtool methods and properties each return a nav object, which contains the following properties:

The following additional properties are returned only if the nav obect is a Menu Link:

For example, if you access the nav object using #set($navobj = $navtool.getNav("/")), then you would reference the title parameter as $navobj.title.

Navigation Permissions

By default, the NavTool does not check permissions. This means users will see all navigation items, even if they don't have permission to view those items.

To configure the NavTool to respect permissions, change the ENABLE_NAV_PERMISSION property to true in the dotmarketing-config.properties file. After this change, only items the current user has permissions to View are returned in the navigation.

ENABLE_NAV_PERMISSION_CHECK=true

Note:

• It is strongly recommended that any changes to the dotmarketing-config.properties file be made through a configuration file extension.
• If the ENABLE_NAV_PERMISSION_CHECK property is enabled, it is recommend that you enclose the navigation in a #dotcache block to avoid performance degradation.

Examples

The following examples demonstrate several different ways to use the navigation tool to display navigation objects and customize navigation.

Example: Get the Current Active Navigation Folder

You can get the current active navigation folder by calling navtool.getNav() without any arguments.

#set($nav = $navtool.getNav())

Example: Two level Navigation

This example displays the navigation from the root of the folder tree, highlighting the active folder with the <strong> tag (if close enough to the root folder to be displayed in the navigation). The dotCMS documentation site left-side navigation bar uses a method similar to this to display the documentation tree.

#set( $list = $navtool.getNav("/") )
<ul>
  #foreach($n in $list)
    <li>
      <a href='${n.href}'>${n.title}</a>
      #set($children = $n.children)
      #if( $children && $children.size() > 0 )
        <ul>
          #foreach($child in $children)
            <li>
              #if($child.active)<strong>#end <a href='${child.href}'>${child.title}</a> #if($child.active)</strong>#end
              #set($grandchildren = $child.children)
              #if( $grandchildren && $grandchildren.size() > 0 )
                <ul>
                  #foreach($grandchild in $grandchildren)
                    <li>#if($grandchild.active)<strong>#end <a href='${grandchild.href}'>${grandchild.title}</a> #if($grandchild.active)</strong>#end
                  #end
                </ul>
              #end
            </li>
          #end
        </ul>
      #end
    </li>
  #end
</ul>

Example: Display the Navigation for the Parent Folder

This example works almost exactly the same as the previous example, but instead of displaying the navigation from the root of the folder tree, this example displays the navigation from 1 level up from the current folder (the parent folder), displaying both the current folder's siblings and children. As with the previous example, the active folder will be highlighted with the <strong> tag.

#set( $list = $navtool.getNav(1) )
<ul>
  #foreach($n in $list)
    <li>
      <a href='${n.href}'>${n.title}</a>
      #set($siblings = $n.children)
      #if( $siblings && $siblings.size() > 0 )
        <ul>
          #foreach($sib in $siblings)
            <li>
              #if($sib.active)<strong>#end <a href='${sib.href}'>${sib.title}</a> #if($sib.active)</strong>#end
              #set($children = $sib.children)
              #if( $children && $children.size() > 0 )
                <ul>
                  #foreach($child in $children)
                    <li><a href='${child.href}'>${child.title}</a>
                  #end
                </ul>
              #end
            </li>
          #end
        </ul>
      #end
    </li>
  #end
</ul>

Example: Add a “Reorder” button in Edit Mode

The following code adds a re-order button to the custom navigation when the page is viewed in Edit mode.

## ADD REORDER MENU BUTTON
#if ($EDIT_MODE && $PUBLISH_HTMLPAGE_PERMISSION)
   <div class="reorder-menu">
       #set($_formId="dot_form_menu_$date.date.time")
       #set ($folder = $folderAPI.findCurrentFolder($startFromPath, $host))
       #set ($menuId = $folder.inode)       
       #orderMenu()
   </div>
#end

Example: Build a Crumbtrail

The following code builds a crumbtrail up to 25 levels deep (based on the Show on Menu settings on the pages, files and folders in your site).

## Get the Nav item for the current folder
#set($current = $navtool.getNav())

## Build the list of folders to display in the crumbtrail
#set($crumb = $contents.getEmptyList())
#set($_x=$crumb.add(0,$current))
#foreach($item in [1..25])
     #set($current = $current.parent)
     #if($current.title=="System folder")
          #break
     #end
     #set($_x=$crumb.add(0,$current))
#end

## Display the crumbtrail
<ul>
     <li style="display:inline"><a href="/">Home</a></li>
     #foreach($item in $crumb)
          <li style="display:inline">     
               <a href="$item.href">$item.title</a>
          </li>
     #end
</ul>

Toolbox.xml Configuration

The following example shows how the ListTool is mapped in the toolbox.xml file:

<tool>
    <key>navtool</key>
    <scope>request</scope>
    <class>com.dotcms.rendering.velocity.viewtools.navigation.NavTool</class>
</tool>