# Menu

Questions ou commentaires?

Needs translation

## Purpose

Provides an interactive menu with optional sub-menus. Implements the WAI-ARIA menu design pattern.

## Working example

- English example
- French example
- Footer Menu Integration - English
- Footer Menu Integration - Français

## How to implement

1. Add the following code to the `header` area of the page. Note: This step should already be done for most themes.
   - English pages:

         <nav role="navigation" id="wb-sm" data-trgt="mb-pnl" class="wb-menu visible-md visible-lg" typeof="SiteNavigationElement">
         	<div class="container nvbar">
         		<h2>Topics menu</h2>
         		<div class="row">
         			<ul class="list-inline menu">
         				<li><a href="#">Section 1</a></li>
         				<li><a href="#">Section 2</a></li>
         				<li><a href="#">Section 3</a></li>
         			</ul>
         		</div>
         	</div>
         </nav>

   - French pages:

         <nav role="navigation" id="wb-sm" data-trgt="mb-pnl" class="wb-menu visible-md visible-lg" typeof="SiteNavigationElement">
         	<div class="container nvbar">
         		<h2>Menu des sujets</h2>
         		<div class="row">
         			<ul class="list-inline menu">
         				<li><a href="#">Section 1</a></li>
         				<li><a href="#">Section 2</a></li>
         				<li><a href="#">Section 3</a></li>
         			</ul>
         		</div>
         	</div>
         </nav>

2. Update the `ul` element with list items (`li`) containing the desired links.
3. Optional: Create a full menu to AJAX in. This menu will replace the `class="container"` element and its descendants. Sub-menus are achieved by nesting `<ul class="sm list-unstyled" id="lore" role="menu">` in each `li` element of the menu bar. The following is an example of a full menu:
   - English pages:

         <div class="pnl-strt container visible-md visible-lg nvbar">
         	<h2>Topics menu</h2>
         	<div class="row">
         		<ul class="list-inline menu" role="menubar">
         			<li><a href="#lore" class="item">Section 1</a>
         				<ul class="sm list-unstyled" id="lore" role="menu">
         					<li><a href="#">Item 1.1</a></li>
         					...
         				</ul>
         			</li>
         			<li><a href="#lor" class="item">Section 2</a>
         				<ul class="sm list-unstyled" id="lor" role="menu" >
         					<li><a href="#">Item 2.1</a></li>
         					...
         					<li class="slflnk"><a href="#">Section 2 - More</a></li>
         				</ul>
         			</li>
         			<li><a href="#lorm" class="item">Section 3</a>
         				<ul class="sm list-unstyled" id="lorm" role="menu" >
         					<li>
         						<details>
         							<summary>Section 3.1</summary>
         							<ul role="menu">
         								<li><a href="#">Item 3.1.1</a></li>
         								...
         							</ul>
         						</details>
         					</li>
         					...
         				</ul>
         			</li>
         		</ul>
         	</div>
         </div>

   - French pages:

         <div class="pnl-strt container visible-md visible-lg nvbar">
         	<h2>Menu des sujets</h2>
         	<div class="row">
         		<ul class="list-inline menu" role="menubar">
         			<li><a href="#lore" class="item">Section 1</a>
         				<ul class="sm list-unstyled" id="lore" role="menu">
         					<li><a href="#">Article 1.1</a></li>
         					...
         				</ul>
         			</li>
         			<li><a href="#lor" class="item">Section 2</a>
         				<ul class="sm list-unstyled" id="lor" role="menu" >
         					<li><a href="#">Article 2.1</a></li>
         					...
         					<li class="slflnk"><a href="#">Section 2 - Autre</a></li>
         				</ul>
         			</li>
         			<li><a href="#lorm" class="item">Section 3</a>
         				<ul class="sm list-unstyled" id="lorm" role="menu" >
         					<li>
         						<details>
         							<summary>Section 3.1</summary>
         							<ul role="menu">
         								<li><a href="#">Article 3.1.1</a></li>
         								...
         							</ul>
         						</details>
         					</li>
         					...
         				</ul>
         			</li>
         		</ul>
         	</div>
         </div>

4. Optional: Add sub-sub-menus to the full menu using nested `details` elements.
   Warning: Sub-sub-menus significantly increase menu complexity, particularly on screen readers and mobile devices, which can create usability issues for some users.

       <ul class="sm list-unstyled" id="lorm" role="menu" >
       	<li>
       		<details>
       			<summary>Section 3.1</summary>
       			<ul role="menu">
       				<li><a href="#">Item 3.1.1</a></li>
       					...
       			</ul>
       		</details>
       	</li>
       	...
       </ul>

5. Optional: Add `data-ajax-replace="[url]"` to the element with `class="wb-menu"`, with `[url]` being the URL of the full menu to AJAX in.

       <nav role="navigation" id="wb-sm" data-ajax-replace="ajax/menu-include-en.html" data-trgt="mb-pnl" class="wb-menu visible-md visible-lg" typeof="SiteNavigationElement">

6. Optional: Update `data-trgt` with the `id` of the target element for the mobile panel (in most cases this should not change).

## Footer Integration in Mobile Menu

For small and medium sized screens, the menu is rendered as a side panel, triggered by a menu button in the header, and includes the secondary menu and the footer. Footer sections must follow supported design patterns to be rendered in the menu without issue.

## Supported

Heading followed by a list of links

### Purpose

Use a heading followed by a list when multiple links need to be displayed. In the menu panel, this is rendered as a `<details>` element, with the heading as a summary.

### Code

    <section class="col-sm-4">
    	<h3>Heading 1</h3>
    	<ul class="list-unstyled">
    		<li><a href="#">List Element 1.1</a></li>
    		<li><a href="#">List Element 1.2</a></li>
    	</ul>
    </section>

Heading followed by a single link

### Purpose

A heading followed by a single link, either on its own or in a paragraph. In the menu panel, this is rendered as a single menu item, with the heading as the text.

### Code

    <section class="col-sm-4">
    	<h3>Heading 1</h3>
    	<p><a href="#">Link 1</a></p>
    </section>

Linked heading

### Purpose

A heading on its own, containing a link. In the menu panel, this is rendered as a single menu item.

### Code

    <section class="col-sm-4">
    	<h3><a href="#">Heading 1</a></h3>
    </section>

## Not Supported

Linked heading followed by a list of links

### Purpose

A combination of the list and lone heading pattern. This will not render properly in the menu panel, as the heading link will not be clickable.

### Code

    <section class="col-sm-4">
    	<h3><a href="#">Heading 1</a></h3>
    	<ul class="list-unstyled">
    		<li><a href="#">List Element 1.1</a></li>
    		<li><a href="#">List Element 1.2</a></li>
    	</ul>
    </section>

Heading followed by multiple links without using a list

### Purpose

A heading followed by a multiple links, either on their own, in paragraphs, or in smaller headings. Only the first link will be clickable in the menu panel.

### Code

    <section class="col-sm-4">
    	<h3>Heading 1</h3>
    	<p><a href="#">Link 1.1</a></p>
    	<p><a href="#">Link 1.2</a></p>
    </section>

Multiple linked headings

### Purpose

Multiple headings of the same size, each containing links. These will cause unwanted gaps in the menu panel. Additionally, this structure is not compliant to the HTML5 specification.

### Code

    <section class="col-sm-4">
    	<h3><a href="#">Heading 1</a></h3>
    	<h3><a href="#">Heading 2</a></h3>
    </section>

## Be Cautious

Mixing different supported structures will work, but it is better to be consistent and only use one.

## Configuration options

Option | Description | How to configure | Values
--- | --- | --- | ---
`data-ajax-replace` | Used to AJAX in a full menu. | Add `data-ajax-replace="[url]"` to the element with `class="wb-menu"`, with `[url]` being the URL of the full menu to AJAX in. | None (default): Full menu is not AJAXed in. URL URL for the full menu to AJAX in.
`data-trgt` | Used to identify the target for the mobile panel. | Add `data-trgt="mb-pnl"` to the element with `class="wb-menu"`. The value of `data-trgt` must match the `id` of the target element for the mobile panel. | String The `id` of the target element (should remain `mb-pnl` unless that `id` has changed.

## Events

Event | Trigger | What it does
--- | --- | ---
`wb-init.wb-menu` | Triggered manually (e.g., `$( ".wb-menu" ).trigger( "wb-init.wb-menu" );`). | Used to manually initialize the menu plugin. Note: The menu plugin will be initialized automatically unless the menu markup is added after the page has already loaded.
`wb-ready.wb-menu` (v4.0.5+) | Triggered automatically after a menu has initialized. | Used to identify which menu has initialized (target of the event).
    $( document ).on( "wb-ready.wb-menu", ".wb-menu", function( event, instance, settings ) {
    });
    $( ".wb-menu" ).on( "wb-ready.wb-menu", function( event ) {
    });
`wb-ready.wb` (v4.0.5+) | Triggered automatically when WET has finished loading and executing. | Used to identify when all WET plugins and polyfills have finished loading and executing.
    $( document ).on( "wb-ready.wb", function( event ) {
    });

## Source code

Menu source code on GitHub

Date de modification :
  2017-06-12