Navigation

Navigation

The following covers Core navigation functionality: navigation settings, sorting order, button API and tooltip API.

Navigation settings

The navigation settings allow you to control the behaviour of the navigation bar.

JSON in course.json _navigation:

  "_navigation": {
    "_isDefaultNavigationDisabled": false, // disable the default navigation bar
    "_navigationAlignment": "top", // determines where the navigation bar is displayed - 'top' or 'bottom'
    "_isBottomOnTouchDevices": false // display the navigation bar at the bottom of the course for touch devices
  }

---

Navigation sorting order

The sorting order was introduced to give flexibility in the visual display of the navigation bar as well as accessibility compliance with WCAG 2.0 Making the DOM order match the visual order. The sorting of buttons is according to a data-order attribute in the DOM which is configured by _navOrder in course.json _globals._extensions.

Core navigation:

    "_extensions": {
      "_drawer": {
        "_navOrder": 100
      },
      "_navigation": {
        "_skipButton": {
          "_navOrder": -100
        },
        "_backButton": {
          "_navOrder": 0
        },
        "_spacers": [
          {
            "_navOrder": 0
          }
        ]
      }
    }

Navigation plugins also support _navOrder, for example pageLevelProgress or Visua11y.

Sorting order is typically defined by a range from 0 (far left for LTR) to 100 (far right for LTR). Items positioned between 0 to 100 are usually in increments of 10.

_spacers can be used to create space between nav items. The default separates out the left and right aligned items. Multiple spacers can be used depending on the desired layout e.g. two spacers would give you left, centered and right aligned items (see below).

Visual navigation display:



DOM order:



JSON in course.json _globals:

    "_extensions": {
      "_drawer": {
        "_navOrder": 100
      },
      "_navigation": {
        "_skipButton": {
          "_navOrder": -100
        },
        "_backButton": {
          "_navOrder": 0
        },
        "_spacers": [
          {
            "_navOrder": 20
          },
          {
            "_navOrder": 80
          }
        ]
      },
      "_navigationTitle": {
        "_navOrder": "30"
      },
      "_close": {
        "_navOrder": "150"
      }
    }

---

Navigation button API

The navigation button API was created to allow extensions to define buttons and add them to the navigation bar rather than allowing DOM injection. API features include:

• Supports backward compatibility with injection
• Display button text label based upon the button aria label
• Display button icons
• Ordering
• Show/hide text

Core navigation:
JSON in course.json to globally configure navigation button text labels:

"_navigation": {
  "_showLabel": true, // Show navigation button labels
  "_showLabelAtWidth": "medium", // Show label at this breakpoint and higher
  "_labelPosition": "auto" // Where to show the label in relation to the button icons 
}

When the user's browser window is at least the size specified in _showLabelAtWidth or greater, the text labels will be shown. Options include any, small, medium and large. small, medium and large refer to the standard Adapt breakpoints (see default screenSize values). The any option will show the label at any size.

The _labelPosition refers to where to show the label in relation to the button icons. Options inlclude auto, top, bottom, left and right.
auto - default display, inherits from lang direction [ icon / text] for LTR and [ text / icon ] for RTL
left - label displays left of icon regardless of lang direction [ text / icon ]
right - label displays right of icon regardless of lang direction [ icon / text]

Navigation plugins also support navLabel, for example pageLevelProgress or Visua11y.

Navigation model

• NavigationButtonModel To hold the properties for each button
• NavigationButtonView For extensions to make their own buttons and for legacy injected button management
• NavigationModel To hold the navigation configuration
• All model updates will be reflected in the DOM.

General API layout

import navigation from 'core/js/navigation';
navigation.model.set('_showLabel', true); // Show all labels

const backButton = navigation.getButton('back');
backButton.set('_order', 400); // Move the back button to the right
backButton.set('text', 'New Label'); // Change the back button label text


navigation.removeButton(backButton); // Remove back button

// Remove all buttons
navigation.buttons.forEach(button => navigation.removeButton(button));

Example, making a home button:

import Adapt from 'core/js/adapt';
import navigation from 'core/js/navigation';
import NavigationButtonModel from 'core/js/models/NavigationButtonModel';
import NavigationButtonView from 'core/js/views/NavigationButtonView';

// Extend the model and view classes to add own behaviour

Adapt.on('navigation:ready', () => {
  const model = new NavigationButtonModel({
    _id: 'home',
    _order: 0,
    _event: 'homeButton',
    _showLabel: null,
    _classes: '',
    _iconClasses: 'icon-medal',
    _role: 'link',
    ariaLabel: 'Home',
    text: '{{ariaLabel}}'
  });
  const view = new NavigationButtonView({ model });
  navigation.addButton(view);
});

Each button has the potential for custom _id, _order, _event, _showLabel, _classes, _iconClasses, _role, ariaLabel and text, with global settings for _showLabel, _navigationAlignment and _isBottomOnTouchDevices.

_event has some default behaviour at "backButton", "homeButton", "parentButton", "skipNavigation" and "returnToStart".

Example, added visua11y and the above home button to the vanilla course:

Backward compatibility

Older buttons should have an aria-label attribute or an .aria-label element in order for a text label to be automatically generated. A <span class="label" aria-hidden="true">{{ariaLabel}}</span> will be appended automatically to any existing button, if it doesn't exist, and will otherwise be automatically updated from the value of the aria-label attribute or .aria-label element. This is as model text defaults to {{ariaLabel}}. On older buttons "ariaLabel", "_role" and "_classes" have no effect when changed from the model as they should be supplied by the injected buttons themselves. "text", "_order", "_showLabel", "_id" and "_event" should work as expected on older injected buttons.

---

Navigation tooltip API

Tooltips display on mouseover and focus. Tooltips are read by a screenreader on mouseover, on focus the screen reader will read the target's aria label. The button aria-label is used to set the default tooltip text.

JSON in course.json to enable / disable globally:

"_tooltips": {
  "_isEnabled": true
}

Core navigation:
JSON in course.json _globals._extensions to configure Back button and Drawer button:

"_extensions": {
  "_navigation": {
    "_backNavTooltip": {
      "_isEnabled": true,
      "text": "{{ariaLabel}}"
    }
  },
  "_drawer": {
    "_navTooltip": {
      "_isEnabled": true,
      "text": "{{ariaLabel}}"
    }
  }
}

Navigation plugins also support _navTooltip, for example pageLevelProgress or Visua11y.