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 Optimizely <<{user["product-name"]}C>>ontent Management System (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:
Property | Type | Value |
|---|---|---|
Model.Title | string | The title that should be displayed for a menu item. Comes from the NavLinkDto.LinkText for a Catalog link, or the Title on a CMS page. |
Model.Url | string | The url to navigation to when a menu item is clicked. |
Model.OpenInNewTab | boolean | Indicates if a hyperlink should be opened in a new tab. |
Model.Level | int | Starting at 0, indicates \he current level of an item in the menu. Can be used to limit how far a recursive menu will render, or to render a menu differently based on the level of an item |
Model.Identifier | string | Can be used to unique identity this navigation menu item. Will contain the GUID of a category or the ContentKey of a CMS page. |
Model.ViewName | string | Used internally to determine if which view to use when rendering a recursive menu |
Model.NavigationMenuType | NavigationMenuType enum | Used internally to determine if a Content or Catalog template needs to used when rendering a recursive menu |
Model.Children | List<NavigationMenuItemDrop> | A list of all the children of this NavigationMenuItem |
Upgrade existing 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.