Skip to content

Latest commit

 

History

History
167 lines (108 loc) · 6.85 KB

README.md

File metadata and controls

167 lines (108 loc) · 6.85 KB
Raw

Hierarchical nav Build Status

Responsive hierarchical navigation pattern.

Browser Support

Tested and working on:

Browsers Primary Experience Core Experience
Chrome 35+ 35+
Firefox 30+ 30+
Safari 7+ 7+
IE 8+ 8+

Known issues:

  • IE < 9 does't support the <nav> element. Products that need to support old IEs should use HTML5Shiv (note that it's bundled by default in Modernizr.

Navigation

All navigation options have the same general markup structure that you can see in main.mustache.

Each navigation item can be either:

  • Plain text: must still be wrapped in <a> tag, e.g. <a>World</a>
  • Linked text: e.g. <a href="/world">World</a>
  • Sub Component: must be wrapped in <li> with a data-o-hierarchical-nav-is-cloneable attribute, e.g <li data-o-hierarchical-nav-is-cloneable>...</li>

…and can have one of the following behaviours:

  • Standalone item
  • Parent of sub-level: opens further navigation list with child options
  • Controller for DOM element: shows and hides an element elsewhere on the page, e.g. a 'mega-dropdown'

Where a navigation item is both a link and a parent or controller for mega-dropdown, the default behaviour on click will be cancelled.

Parent of sub-level

The <li> should be given a class of o-hierarchical-nav__parent, and should contain another <ul> list that declares its level via a data attribute:

<li class="o-hierarchical-nav__parent"><a>Level 2 item with sub-level</a>
	<ul data-o-hierarchical-nav-level="3">
		<li><a>Level 3 item</a></li>
		<li><a>Level 3 item</a></li>
	</ul>
</li>

When the nav item is clicked, the <li> will have an aria-expanded attribute toggled, which will control the visibility of the child list.

Controller for DOM element

The <li> should be given an aria-controls attribute with the value being the ID of the DOM element to control, for example:

<li aria-controls="megadropdown"><a>Mega dropdown</a></li>

...

<div id="megadropdown" aria-hidden="true">
	Mega-dropdown content
</div>

When the nav item is clicked, the element targeted by the aria-control attribute will have its aria-hidden attribute toggled.

Megadropdowns

The horizontal base style comes with default styling for a megadropdown element. This element has to add the class .o-hierarchical-nav__mega-dropdown.

Responsive collapsing of horizontal navigation

Horizontal navigation styles use o-squishy-list to allow priorities to be set on the top level nav items:

<nav>
	<ul data-o-hierarchical-nav-level="1">
		<li data-priority="2"><a>Important page</a></li>
		<li data-priority="3"><a>Less important page</a></li>
		<li data-priority="1"><a>Home</a></li>
	</ul>
</nav>

o-squishy-list will show as many items has will fit in the available width. If not everything will fit, then the necessary number of items will be hidden, starting with the lowest priority items.

If you don't want to use a responsive horizontal navigation, you can require Nav.js directly.

Hidden navigation items

A 'More' item may be added to the top level which will be populated with a list of elements that have been hidden by o-squishy-list:

<li data-more class="o-hierarchical-nav__parent" aria-hidden="true"><a>More</a></li>

This item is be hidden until it's needed. It's recommended that aria-hidden="true" should be added to a 'More' item so that it won't appear when running on core experience.

If there's a chance that all nav items will be hidden and added to the More list, then it's possible to change the text title of the More item depending on whether it contains some or all the navigation items:

<li data-more class="o-hierarchical-nav__parent"><a><span class="nav__more--if-some">More</span><span class="nav__more--if-all">Menu</span></a></li>

Sub-Components

If there is a structure required for the styling of nav components (i.e. other elements are required for icon display) or elements that are not links but should reduce to a sub-level when screen space does not allow then you can add a 'data-o-hierarchical-nav-is-cloneable' attribute and the element will be deeply cloned rather than a new anchor tag with the text content copied.

<li data-o-hierarchical-nav-is-cloneable><a><span>An item to clone</span><img src="" alt="icon"></a></li>

Vertical hierarchical nav

To make a nav work in a vertical layout, add data-o-hierarchical-nav-orientiation="vertical" to the <nav>.

Arrows

Add a <i></i> to display an arrow icon at the end of an <a> element:

<li class="o-hierarchical-nav__parent"><a>Item 3.2 (parent) <i></i></a>

Styling

There are two base mixins for modules and products to include:

  • Horizontal: @include oHierarchicalNavHorizontalTheme
  • Vertical: @include oHierarchicalNavVerticalTheme

Things that are important to add to your theme are:

  • Styles for the [aria-selected="true"] attribute
  • Setting a width for <nav> when extending the vertical theme
  • Down and right arrow icons for parent elements. Make sure the size and color are correct.

If you want to style megadropdowns, you need to add @at-root before the .o-hierarchical-nav__mega-dropdown class.

JavaScript instantiation

An o-hierarchical-nav object must be constructed for every <nav> you have on your page that uses this module.

var oHierarchicalNav = require('o-hierarchical-nav');
var nav = document.querySelector('.o-hierarchical-nav');
var hierarchicalNav = new oHierarchicalNav(nav);

Alternatively, a o.DOMContentLoaded event can be dispatched on the document to auto-construct a o-hierarchical-nav object for each element with a data-o-component="o-hierarchical-nav" attribute:

document.addEventListener("DOMContentLoaded", function() {
	document.dispatchEvent(new CustomEvent('o.DOMContentLoaded'));
});

All this really does is run the oHierarchicalNav.init() function, so if you don't want this module to initialise with all the others, you can run this when it suits you best.

License

Copyright (c) 2016 Financial Times Ltd. All rights reserved.

This software is published under the MIT licence.