// This file is part of Moodle - http://moodle.org/
//
// Moodle is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// Moodle is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with Moodle. If not, see <http://www.gnu.org/licenses/>.
/**
* Aria menubar functionality. Enhances a simple nested list structure into a full aria widget.
* Based on the open ajax example: http://oaa-accessibility.org/example/26/
*
* @module tool_lp/menubar
* @copyright 2015 Damyon Wiese <damyon@moodle.com>
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
define(['jquery'], function($) {
/** @property {boolean} Flag to indicate if we have already registered a click event handler for the document. */
var documentClickHandlerRegistered = false;
/** @property {boolean} Flag to indicate whether there's an active, open menu. */
var menuActive = false;
/**
* Close all open submenus anywhere in the page (there should only ever be one open at a time).
*
* @method closeAllSubMenus
*/
var closeAllSubMenus = function() {
$('.tool-lp-menu .tool-lp-sub-menu').attr('aria-hidden', 'true');
// Every menu's closed at this point, so set the menu active flag to false.
menuActive = false;
};
/**
* Constructor
*
* @param {jQuery} menuRoot Jquery collection matching the root of the menu.
* @param {Function[]} handlers called when a menu item is chosen.
*/
var Menubar = function(menuRoot, handlers) {
// Setup private class variables.
this.menuRoot = menuRoot;
this.handlers = handlers;
this.rootMenus = this.menuRoot.children('li');
this.subMenus = this.rootMenus.children('ul');
this.subMenuItems = this.subMenus.children('li');
this.allItems = this.rootMenus.add(this.subMenuItems);
this.activeItem = null;
this.isChildOpen = false;
this.keys = {
tab: 9,
enter: 13,
esc: 27,
space: 32,
left: 37,
up: 38,
right: 39,
down: 40
};
this.addAriaAttributes();
// Add the event listeners.
this.addEventListeners();
};
/**
* Open a submenu, first it closes all other sub-menus and sets the open direction.
* @method openSubMenu
* @param {Node} menu
*/
Menubar.prototype.openSubMenu = function(menu) {
this.setOpenDirection();
closeAllSubMenus();
menu.attr('aria-hidden', 'false');
// Set menu active flag to true when a menu is opened.
menuActive = true;
};
/**
* Bind the event listeners to the DOM
* @method addEventListeners
*/
Menubar.prototype.addEventListeners = function() {
var currentThis = this;
// When clicking outside the menubar.
if (documentClickHandlerRegistered === false) {
$(document).click(function() {
// Check if a menu is opened.
if (menuActive) {
// Close menu.
closeAllSubMenus();
}
});
// Set this flag to true so that we won't need to add a document click handler for the other Menubar instances.
documentClickHandlerRegistered = true;
}
// Hovers.
this.subMenuItems.mouseenter(function() {
$(this).addClass('menu-hover');
return true;
});
this.subMenuItems.mouseout(function() {
$(this).removeClass('menu-hover');
return true;
});
// Mouse listeners.
this.allItems.click(function(e) {
return currentThis.handleClick($(this), e);
});
// Key listeners.
this.allItems.keydown(function(e) {
return currentThis.handleKeyDown($(this), e);
});
this.allItems.focus(function() {
return currentThis.handleFocus($(this));
});
this.allItems.blur(function() {
return currentThis.handleBlur($(this));
});
};
/**
* Process click events for the top menus.
*
* @method handleClick
* @param {Object} item is the jquery object of the item firing the event
* @param {Event} e is the associated event object
* @return {boolean} Returns false
*/
Menubar.prototype.handleClick = function(item, e) {
e.stopPropagation();
var parentUL = item.parent();
if (parentUL.is('.tool-lp-menu')) {
// Toggle the child menu open/closed.
if (item.children('ul').first().attr('aria-hidden') == 'true') {
this.openSubMenu(item.children('ul').first());
} else {
item.children('ul').first().attr('aria-hidden', 'true');
}
} else {
// Remove hover and focus styling.
this.allItems.removeClass('menu-hover menu-focus');
// Clear the active item.
this.activeItem = null;
// Close the menu.
this.menuRoot.find('ul').not('.root-level').attr('aria-hidden', 'true');
// Follow any link, or call the click handlers.
var anchor = item.find('a').first();
var clickEvent = new $.Event('click');
clickEvent.target = anchor;
var eventHandled = false;
if (this.handlers) {
$.each(this.handlers, function(selector, handler) {
if (eventHandled) {
return;
}
if (item.find(selector).length > 0) {
var callable = $.proxy(handler, anchor);
// False means stop propogatting events.
eventHandled = (callable(clickEvent) === false) || clickEvent.isDefaultPrevented();
}
});
}
// If we didn't find a handler, and the HREF is # that probably means that
// we are handling it from somewhere else. Let's just do nothing in that case.
if (!eventHandled && anchor.attr('href') !== '#') {
window.location.href = anchor.attr('href');
}
}
return false;
};
/*
* Process focus events for the menu.
*
* @method handleFocus
* @param {Object} item is the jquery object of the item firing the event
* @return boolean Returns false
*/
Menubar.prototype.handleFocus = function(item) {
// If activeItem is null, we are getting focus from outside the menu. Store
// the item that triggered the event.
if (this.activeItem === null) {
this.activeItem = item;
} else if (item[0] != this.activeItem[0]) {
return true;
}
// Get the set of jquery objects for all the parent items of the active item.
var parentItems = this.activeItem.parentsUntil('ul.tool-lp-menu').filter('li');
// Remove focus styling from all other menu items.
this.allItems.removeClass('menu-focus');
// Add focus styling to the active item.
this.activeItem.addClass('menu-focus');
// Add focus styling to all parent items.
parentItems.addClass('menu-focus');
// If the bChildOpen flag has been set, open the active item's child menu (if applicable).
if (this.isChildOpen === true) {
var itemUL = item.parent();
// If the itemUL is a root-level menu and item is a parent item,
// show the child menu.
if (itemUL.is('.tool-lp-menu') && (item.attr('aria-haspopup') == 'true')) {
this.openSubMenu(item.children('ul').first());
}
}
return true;
};
/*
* Process blur events for the menu.
*
* @method handleBlur
* @param {Object} item is the jquery object of the item firing the event
* @return boolean Returns false
*/
Menubar.prototype.handleBlur = function(item) {
item.removeClass('menu-focus');
return true;
};
/*
* Determine if the menu should open to the left, or the right,
* based on the screen size and menu position.
* @method setOpenDirection
*/
Menubar.prototype.setOpenDirection = function() {
var pos = this.menuRoot.offset();
var isRTL = $(document.body).hasClass('dir-rtl');
var openLeft = true;
var heightmenuRoot = this.rootMenus.outerHeight();
var widthmenuRoot = this.rootMenus.outerWidth();
// Sometimes the menuMinWidth is not enough to figure out if menu exceeds the window width.
// So we have to calculate the real menu width.
var subMenuContainer = this.rootMenus.find('ul.tool-lp-sub-menu');
// Reset margins.
subMenuContainer.css('margin-right', '');
subMenuContainer.css('margin-left', '');
subMenuContainer.css('margin-top', '');
subMenuContainer.attr('aria-hidden', false);
var menuRealWidth = subMenuContainer.outerWidth(),
menuRealHeight = subMenuContainer.outerHeight();
var margintop = null,
marginright = null,
marginleft = null;
var top = pos.top - $(window).scrollTop();
// Top is the same for RTL and LTR.
if (top + menuRealHeight > $(window).height()) {
margintop = menuRealHeight + heightmenuRoot;
subMenuContainer.css('margin-top', '-' + margintop + 'px');
}
if (isRTL) {
if (pos.left - menuRealWidth < 0) {
marginright = menuRealWidth - widthmenuRoot;
subMenuContainer.css('margin-right', '-' + marginright + 'px');
}
} else {
if (pos.left + menuRealWidth > $(window).width()) {
marginleft = menuRealWidth - widthmenuRoot;
subMenuContainer.css('margin-left', '-' + marginleft + 'px');
}
}
if (openLeft) {
this.menuRoot.addClass('tool-lp-menu-open-left');
} else {
this.menuRoot.removeClass('tool-lp-menu-open-left');
}
};
/*
* Process keyDown events for the menu.
*
* @method handleKeyDown
* @param {Object} item is the jquery object of the item firing the event
* @param {Event} e is the associated event object
* @return boolean Returns false if consuming the event
*/
Menubar.prototype.handleKeyDown = function(item, e) {
if (e.altKey || e.ctrlKey) {
// Modifier key pressed: Do not process.
return true;
}
switch (e.keyCode) {
case this.keys.tab: {
// Hide all menu items and update their aria attributes.
this.menuRoot.find('ul').attr('aria-hidden', 'true');
// Remove focus styling from all menu items.
this.allItems.removeClass('menu-focus');
this.activeItem = null;
this.isChildOpen = false;
break;
}
case this.keys.esc: {
var itemUL = item.parent();
if (itemUL.is('.tool-lp-menu')) {
// Hide the child menu and update the aria attributes.
item.children('ul').first().attr('aria-hidden', 'true');
} else {
// Move up one level.
this.activeItem = itemUL.parent();
// Reset the isChildOpen flag.
this.isChildOpen = false;
// Set focus on the new item.
this.activeItem.focus();
// Hide the active menu and update the aria attributes.
itemUL.attr('aria-hidden', 'true');
}
e.stopPropagation();
return false;
}
case this.keys.enter:
case this.keys.space: {
// Trigger click handler.
return this.handleClick(item, e);
}
case this.keys.left: {
this.activeItem = this.moveToPrevious(item);
this.activeItem.focus();
e.stopPropagation();
return false;
}
case this.keys.right: {
this.activeItem = this.moveToNext(item);
this.activeItem.focus();
e.stopPropagation();
return false;
}
case this.keys.up: {
this.activeItem = this.moveUp(item);
this.activeItem.focus();
e.stopPropagation();
return false;
}
case this.keys.down: {
this.activeItem = this.moveDown(item);
this.activeItem.focus();
e.stopPropagation();
return false;
}
}
return true;
};
/**
* Move to the next menu level.
* This will be either the next root-level menu or the child of a menu parent. If
* at the root level and the active item is the last in the menu, this function will loop
* to the first menu item.
*
* If the menu is a horizontal menu, the first child element of the newly selected menu will
* be selected
*
* @method moveToNext
* @param {Object} item is the active menu item
* @return {Object} Returns the item to move to. Returns item is no move is possible
*/
Menubar.prototype.moveToNext = function(item) {
// Item's containing menu.
var itemUL = item.parent();
// The items in the currently active menu.
var menuItems = itemUL.children('li');
// The number of items in the active menu.
var menuNum = menuItems.length;
// The items index in its menu.
var menuIndex = menuItems.index(item);
var newItem = null;
var childMenu = null;
if (itemUL.is('.tool-lp-menu')) {
// This is the root level move to next sibling. This will require closing
// the current child menu and opening the new one.
if (menuIndex < menuNum - 1) {
// Not the last root menu.
newItem = item.next();
} else { // Wrap to first item.
newItem = menuItems.first();
}
// Close the current child menu (if applicable).
if (item.attr('aria-haspopup') == 'true') {
childMenu = item.children('ul').first();
if (childMenu.attr('aria-hidden') == 'false') {
// Update the child menu's aria-hidden attribute.
childMenu.attr('aria-hidden', 'true');
this.isChildOpen = true;
}
}
// Remove the focus styling from the current menu.
item.removeClass('menu-focus');
// Open the new child menu (if applicable).
if ((newItem.attr('aria-haspopup') === 'true') && (this.isChildOpen === true)) {
childMenu = newItem.children('ul').first();
// Update the child's aria-hidden attribute.
this.openSubMenu(childMenu);
}
} else {
// This is not the root level. If there is a child menu to be moved into, do that;
// otherwise, move to the next root-level menu if there is one.
if (item.attr('aria-haspopup') == 'true') {
childMenu = item.children('ul').first();
newItem = childMenu.children('li').first();
// Show the child menu and update its aria attributes.
this.openSubMenu(childMenu);
} else {
// At deepest level, move to the next root-level menu.
var parentMenus = null;
var rootItem = null;
// Get list of all parent menus for item, up to the root level.
parentMenus = item.parentsUntil('ul.tool-lp-menu').filter('ul').not('.tool-lp-menu');
// Hide the current menu and update its aria attributes accordingly.
parentMenus.attr('aria-hidden', 'true');
// Remove the focus styling from the active menu.
parentMenus.find('li').removeClass('menu-focus');
parentMenus.last().parent().removeClass('menu-focus');
// The containing root for the menu.
rootItem = parentMenus.last().parent();
menuIndex = this.rootMenus.index(rootItem);
// If this is not the last root menu item, move to the next one.
if (menuIndex < this.rootMenus.length - 1) {
newItem = rootItem.next();
} else {
// Loop.
newItem = this.rootMenus.first();
}
// Add the focus styling to the new menu.
newItem.addClass('menu-focus');
if (newItem.attr('aria-haspopup') == 'true') {
childMenu = newItem.children('ul').first();
newItem = childMenu.children('li').first();
// Show the child menu and update it's aria attributes.
this.openSubMenu(childMenu);
this.isChildOpen = true;
}
}
}
return newItem;
};
/**
* Member function to move to the previous menu level.
* This will be either the previous root-level menu or the child of a menu parent. If
* at the root level and the active item is the first in the menu, this function will loop
* to the last menu item.
*
* If the menu is a horizontal menu, the first child element of the newly selected menu will
* be selected
*
* @method moveToPrevious
* @param {Object} item is the active menu item
* @return {Object} Returns the item to move to. Returns item is no move is possible
*/
Menubar.prototype.moveToPrevious = function(item) {
// Item's containing menu.
var itemUL = item.parent();
// The items in the currently active menu.
var menuItems = itemUL.children('li');
// The items index in its menu.
var menuIndex = menuItems.index(item);
var newItem = null;
var childMenu = null;
if (itemUL.is('.tool-lp-menu')) {
// This is the root level move to previous sibling. This will require closing
// the current child menu and opening the new one.
if (menuIndex > 0) {
// Not the first root menu.
newItem = item.prev();
} else {
// Wrap to last item.
newItem = menuItems.last();
}
// Close the current child menu (if applicable).
if (item.attr('aria-haspopup') == 'true') {
childMenu = item.children('ul').first();
if (childMenu.attr('aria-hidden') == 'false') {
// Update the child menu's aria-hidden attribute.
childMenu.attr('aria-hidden', 'true');
this.isChildOpen = true;
}
}
// Remove the focus styling from the current menu.
item.removeClass('menu-focus');
// Open the new child menu (if applicable).
if ((newItem.attr('aria-haspopup') === 'true') && (this.isChildOpen === true)) {
childMenu = newItem.children('ul').first();
// Update the child's aria-hidden attribute.
this.openSubMenu(childMenu);
}
} else {
// This is not the root level. If there is a parent menu that is not the
// root menu, move up one level; otherwise, move to first item of the previous
// root menu.
var parentLI = itemUL.parent();
var parentUL = parentLI.parent();
// If this is a vertical menu or is not the first child menu
// of the root-level menu, move up one level.
if (!parentUL.is('.tool-lp-menu')) {
newItem = itemUL.parent();
// Hide the active menu and update aria-hidden.
itemUL.attr('aria-hidden', 'true');
// Remove the focus highlight from the item.
item.removeClass('menu-focus');
} else {
// Move to previous root-level menu.
// Hide the current menu and update the aria attributes accordingly.
itemUL.attr('aria-hidden', 'true');
// Remove the focus styling from the active menu.
item.removeClass('menu-focus');
parentLI.removeClass('menu-focus');
menuIndex = this.rootMenus.index(parentLI);
if (menuIndex > 0) {
// Move to the previous root-level menu.
newItem = parentLI.prev();
} else {
// Loop to last root-level menu.
newItem = this.rootMenus.last();
}
// Add the focus styling to the new menu.
newItem.addClass('menu-focus');
if (newItem.attr('aria-haspopup') == 'true') {
childMenu = newItem.children('ul').first();
// Show the child menu and update it's aria attributes.
this.openSubMenu(childMenu);
this.isChildOpen = true;
newItem = childMenu.children('li').first();
}
}
}
return newItem;
};
/**
* Member function to select the next item in a menu.
* If the active item is the last in the menu, this function will loop to the
* first menu item.
*
* @method moveDown
* @param {Object} item is the active menu item
* @param {String} startChr is the character to attempt to match against the beginning of the
* menu item titles. If found, focus moves to the next menu item beginning with that character.
* @return {Object} Returns the item to move to. Returns item is no move is possible
*/
Menubar.prototype.moveDown = function(item, startChr) {
// Item's containing menu.
var itemUL = item.parent();
// The items in the currently active menu.
var menuItems = itemUL.children('li').not('.separator');
// The number of items in the active menu.
var menuNum = menuItems.length;
// The items index in its menu.
var menuIndex = menuItems.index(item);
var newItem = null;
var newItemUL = null;
if (itemUL.is('.tool-lp-menu')) {
// This is the root level menu.
if (item.attr('aria-haspopup') != 'true') {
// No child menu to move to.
return item;
}
// Move to the first item in the child menu.
newItemUL = item.children('ul').first();
newItem = newItemUL.children('li').first();
// Make sure the child menu is visible.
this.openSubMenu(newItemUL);
return newItem;
}
// If $item is not the last item in its menu, move to the next item. If startChr is specified, move
// to the next item with a title that begins with that character.
if (startChr) {
var match = false;
var curNdx = menuIndex + 1;
// Check if the active item was the last one on the list.
if (curNdx == menuNum) {
curNdx = 0;
}
// Iterate through the menu items (starting from the current item and wrapping) until a match is found
// or the loop returns to the current menu item.
while (curNdx != menuIndex) {
var titleChr = menuItems.eq(curNdx).html().charAt(0);
if (titleChr.toLowerCase() == startChr) {
match = true;
break;
}
curNdx = curNdx + 1;
if (curNdx == menuNum) {
// Reached the end of the list, start again at the beginning.
curNdx = 0;
}
}
if (match === true) {
newItem = menuItems.eq(curNdx);
// Remove the focus styling from the current item.
item.removeClass('menu-focus');
return newItem;
} else {
return item;
}
} else {
if (menuIndex < menuNum - 1) {
newItem = menuItems.eq(menuIndex + 1);
} else {
newItem = menuItems.first();
}
}
// Remove the focus styling from the current item.
item.removeClass('menu-focus');
return newItem;
};
/**
* Function moveUp() is a member function to select the previous item in a menu.
* If the active item is the first in the menu, this function will loop to the
* last menu item.
*
* @method moveUp
* @param {Object} item is the active menu item
* @return {Object} Returns the item to move to. Returns item is no move is possible
*/
Menubar.prototype.moveUp = function(item) {
// Item's containing menu.
var itemUL = item.parent();
// The items in the currently active menu.
var menuItems = itemUL.children('li').not('.separator');
// The items index in its menu.
var menuIndex = menuItems.index(item);
var newItem = null;
if (itemUL.is('.tool-lp-menu')) {
// This is the root level menu.
// Nothing to do.
return item;
}
// If item is not the first item in its menu, move to the previous item.
if (menuIndex > 0) {
newItem = menuItems.eq(menuIndex - 1);
} else {
// Loop to top of menu.
newItem = menuItems.last();
}
// Remove the focus styling from the current item.
item.removeClass('menu-focus');
return newItem;
};
/**
* Enhance the dom with aria attributes.
* @method addAriaAttributes
*/
Menubar.prototype.addAriaAttributes = function() {
this.menuRoot.attr('role', 'menubar');
this.rootMenus.attr('role', 'menuitem');
this.rootMenus.attr('tabindex', '0');
this.rootMenus.attr('aria-haspopup', 'true');
this.subMenus.attr('role', 'menu');
this.subMenus.attr('aria-hidden', 'true');
this.subMenuItems.attr('role', 'menuitem');
this.subMenuItems.attr('tabindex', '-1');
// For CSS styling and effects.
this.menuRoot.addClass('tool-lp-menu');
this.allItems.addClass('tool-lp-menu-item');
this.rootMenus.addClass('tool-lp-root-menu');
this.subMenus.addClass('tool-lp-sub-menu');
this.subMenuItems.addClass('dropdown-item');
};
return /** @alias module:tool_lp/menubar */ {
/**
* Create a menu bar object for every node matching the selector.
*
* The expected DOM structure is shown below.
* <ul> <- This is the target of the selector parameter.
* <li> <- This is repeated for each top level menu.
* Text <- This is the text for the top level menu.
* <ul> <- This is a list of the entries in this top level menu.
* <li> <- This is repeated for each menu entry.
* <a href="someurl">Choice 1</a> <- The anchor for the menu.
* </li>
* </ul>
* </li>
* </ul>
*
* @method enhance
* @param {String} selector - The selector for the outer most menu node.
* @param {Function} handler - Javascript handler for when a menu item was chosen. If the
* handler returns true (or does not exist), the
* menu will look for an anchor with a link to follow.
* For example, if the menu entry has a "data-action" attribute
* and we want to call a javascript function when that entry is chosen,
* we could pass a list of handlers like this:
* { "[data-action='add']" : callAddFunction }
*/
enhance: function(selector, handler) {
$(selector).each(function(index, element) {
var menuRoot = $(element);
// Don't enhance the same menu twice.
if (menuRoot.data("menubarEnhanced") !== true) {
(new Menubar(menuRoot, handler));
menuRoot.data("menubarEnhanced", true);
}
});
},
/**
* Handy function to close all open menus anywhere on the page.
* @method closeAll
*/
closeAll: closeAllSubMenus
};
});