Navigation menu

Navigation Menu templates are used to customize the appearance of the main navigation. They can also be used for rendering navigation menus in other areas of the site. The template that will be used to render a NavigationMenu is determined by the tag that is used, and is not configurable in theme.json. If a template name is not supplied to the tag, the template named "Standard" will be used.

📘

Note

Because of this, a change to the template being used for HeaderView will be required to customize the main navigation on a site.

The NavigationMenu is generated based on the tree of CMS pages, excluding any page that has ExcludeFromNavigation set to true. ICatalogNavigationPages that are in the tree allow for the inclusion of categories in the navigation menu.

There are two different types of NavigationMenu templates:

• Content templates are used to render almost all pages.
• Catalog templates are used by any page that implements ICatalogNavigationPage.

DotLiquid tags

A Navigation Menu is rendered using a DotLiquid tag. In the responsive theme, this occurs in the HeaderView template, but the tag can be included in any type of template. Examples of how to use the tag are below:

<!-- This will render a NavigationMenu starting from the HomePage, using the Standard template, 
and it will be surrounded by a <ul> tag. These are the default values. -->
[% navigationMenu %]

<!-- This overrides the viewName and renders a NavigationMenu using templates named "MyCustomTemplate". 
Note that a template with this name must exist at both ~/Views/NavigationMenus/Content/MyCustomTemplate.liquid 
and ~/Views/NavigationMenus/Catalog/MyCustomTemplate.liquid -->
[% navigationMen 'MyCustomTemplate' %]

<!-- This will render a NavigationMenu starting from a page named "My Account", using the templates named "MyCustomTemplate" 
and the NavigationMenu will be surrounded by a <ol> tag. Note that the parameters can appear in any order -->
[% navigationMenu viewName: 'MyCustomTemplate' surroundWith: 'ol' pageName: 'My Account' %]

Behind the scenes, the NavigationMenuTag renders a series of MavigationMenuItemTags, which in turn makes use of the DotLiquid template. This allows for recursive menus to be rendered. A straightforward example of a NavigationMenu template would look like this:

<li>
    <a href="[[Model.Url]]" [% if Model.OpenInNewTab %] target="_blank" rel="noopener noreferrer" [% endif %]>[[Model.Title]]</a>
	<ul>
        [% for childItem in Model.Children %]
            [% navigationMenuItem childItem %] <!-- this will render the template recursively through the tree of NavigationMenuItemDrops -->
        [% endfor %]
    </ul>
</li>

DotLiquid model

The model used for Navigation Menu templates is the same for both Content and Catalog templates, however the values in it will differ slightly:

Upgrade themes without navigation menu templates

To maintain backwards compatibility for git themes, if a theme is loaded and does not contain any Navigation Menu templates, then the Navigation Menu templates from the responsive theme will be automatically loaded into it at start up. These templates will only exist in the database- the git theme itself is not modified.

If a git theme is then modified to include at least one Navigation Menu template, then those responsive Navigation Menu templates will be removed from the theme at start up. Therefore, it is important to include all required Navigation Menu templates, otherwise your theme may not render the site correctly.