// 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/>.
/**
* Implement an accessible aria tree widget, from a nested unordered list.
* Based on http://oaa-accessibility.org/example/41/.
*
* @module core/tree
* @copyright 2015 Damyon Wiese <damyon@moodle.com>
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
define(['jquery'], function($) {
// Private variables and functions.
var SELECTORS = {
ITEM: '[role=treeitem]',
GROUP: '[role=treeitem]:has([role=group]), [role=treeitem][aria-owns], [role=treeitem][data-requires-ajax=true]',
CLOSED_GROUP: '[role=treeitem]:has([role=group])[aria-expanded=false], [role=treeitem][aria-owns][aria-expanded=false], ' +
'[role=treeitem][data-requires-ajax=true][aria-expanded=false]',
FIRST_ITEM: '[role=treeitem]:first',
VISIBLE_ITEM: '[role=treeitem]:visible',
UNLOADED_AJAX_ITEM: '[role=treeitem][data-requires-ajax=true][data-loaded=false][aria-expanded=true]'
};
/**
* Constructor.
*
* @param {String} selector
* @param {function} selectCallback Called when the active node is changed.
*/
var Tree = function(selector, selectCallback) {
this.treeRoot = $(selector);
this.treeRoot.data('activeItem', null);
this.selectCallback = selectCallback;
this.keys = {
tab: 9,
enter: 13,
space: 32,
pageup: 33,
pagedown: 34,
end: 35,
home: 36,
left: 37,
up: 38,
right: 39,
down: 40,
asterisk: 106
};
// Apply the standard default initialisation for all nodes, starting with the tree root.
this.initialiseNodes(this.treeRoot);
// Make the first item the active item for the tree so that it is added to the tab order.
this.setActiveItem(this.treeRoot.find(SELECTORS.FIRST_ITEM));
// Create the cache of the visible items.
this.refreshVisibleItemsCache();
// Create the event handlers for the tree.
this.bindEventHandlers();
};
Tree.prototype.registerEnterCallback = function(callback) {
this.enterCallback = callback;
};
/**
* Find all visible tree items and save a cache of them on the tree object.
*
* @method refreshVisibleItemsCache
*/
Tree.prototype.refreshVisibleItemsCache = function() {
this.treeRoot.data('visibleItems', this.treeRoot.find(SELECTORS.VISIBLE_ITEM));
};
/**
* Get all visible tree items.
*
* @method getVisibleItems
* @return {Object} visible items
*/
Tree.prototype.getVisibleItems = function() {
return this.treeRoot.data('visibleItems');
};
/**
* Mark the given item as active within the tree and fire the callback for when the active item is set.
*
* @method setActiveItem
* @param {object} item jquery object representing an item on the tree.
*/
Tree.prototype.setActiveItem = function(item) {
var currentActive = this.treeRoot.data('activeItem');
if (item === currentActive) {
return;
}
// Remove previous active from tab order.
if (currentActive) {
currentActive.attr('tabindex', '-1');
currentActive.attr('aria-selected', 'false');
}
item.attr('tabindex', '0');
item.attr('aria-selected', 'true');
// Set the new active item.
this.treeRoot.data('activeItem', item);
if (typeof this.selectCallback === 'function') {
this.selectCallback(item);
}
};
/**
* Determines if the given item is a group item (contains child tree items) in the tree.
*
* @method isGroupItem
* @param {object} item jquery object representing an item on the tree.
* @returns {bool}
*/
Tree.prototype.isGroupItem = function(item) {
return item.is(SELECTORS.GROUP);
};
/**
* Determines if the given item is a group item (contains child tree items) in the tree.
*
* @method isGroupItem
* @param {object} item jquery object representing an item on the tree.
* @returns {bool}
*/
Tree.prototype.getGroupFromItem = function(item) {
var ariaowns = this.treeRoot.find('#' + item.attr('aria-owns'));
var plain = item.children('[role=group]');
if (ariaowns.length > plain.length) {
return ariaowns;
} else {
return plain;
}
};
/**
* Determines if the given group item (contains child tree items) is collapsed.
*
* @method isGroupCollapsed
* @param {object} item jquery object representing a group item on the tree.
* @returns {bool}
*/
Tree.prototype.isGroupCollapsed = function(item) {
return item.attr('aria-expanded') === 'false';
};
/**
* Determines if the given group item (contains child tree items) can be collapsed.
*
* @method isGroupCollapsible
* @param {object} item jquery object representing a group item on the tree.
* @returns {bool}
*/
Tree.prototype.isGroupCollapsible = function(item) {
return item.attr('data-collapsible') !== 'false';
};
/**
* Performs the tree initialisation for all child items from the given node,
* such as removing everything from the tab order and setting aria selected
* on items.
*
* @method initialiseNodes
* @param {object} node jquery object representing a node.
*/
Tree.prototype.initialiseNodes = function(node) {
this.removeAllFromTabOrder(node);
this.setAriaSelectedFalseOnItems(node);
// Get all ajax nodes that have been rendered as expanded but haven't loaded the child items yet.
var thisTree = this;
node.find(SELECTORS.UNLOADED_AJAX_ITEM).each(function() {
var unloadedNode = $(this);
// Collapse and then expand to trigger the ajax loading.
thisTree.collapseGroup(unloadedNode);
thisTree.expandGroup(unloadedNode);
});
};
/**
* Removes all child DOM elements of the given node from the tab order.
*
* @method removeAllFromTabOrder
* @param {object} node jquery object representing a node.
*/
Tree.prototype.removeAllFromTabOrder = function(node) {
node.find('*').attr('tabindex', '-1');
this.getGroupFromItem($(node)).find('*').attr('tabindex', '-1');
};
/**
* Find all child tree items from the given node and set the aria selected attribute to false.
*
* @method setAriaSelectedFalseOnItems
* @param {object} node jquery object representing a node.
*/
Tree.prototype.setAriaSelectedFalseOnItems = function(node) {
node.find(SELECTORS.ITEM).attr('aria-selected', 'false');
};
/**
* Expand all group nodes within the tree.
*
* @method expandAllGroups
*/
Tree.prototype.expandAllGroups = function() {
var thisTree = this;
this.treeRoot.find(SELECTORS.CLOSED_GROUP).each(function() {
var groupNode = $(this);
thisTree.expandGroup($(this)).done(function() {
thisTree.expandAllChildGroups(groupNode);
});
});
};
/**
* Find all child group nodes from the given node and expand them.
*
* @method expandAllChildGroups
* @param {Object} item is the jquery id of the group.
*/
Tree.prototype.expandAllChildGroups = function(item) {
var thisTree = this;
this.getGroupFromItem(item).find(SELECTORS.CLOSED_GROUP).each(function() {
var groupNode = $(this);
thisTree.expandGroup($(this)).done(function() {
thisTree.expandAllChildGroups(groupNode);
});
});
};
/**
* Expand a collapsed group.
*
* Handles expanding nodes that are ajax loaded (marked with a data-requires-ajax attribute).
*
* @method expandGroup
* @param {Object} item is the jquery id of the parent item of the group.
* @return {Object} a promise that is resolved when the group has been expanded.
*/
Tree.prototype.expandGroup = function(item) {
var promise = $.Deferred();
// Ignore nodes that are explicitly maked as not expandable or are already expanded.
if (item.attr('data-expandable') !== 'false' && this.isGroupCollapsed(item)) {
// If this node requires ajax load and we haven't already loaded it.
if (item.attr('data-requires-ajax') === 'true' && item.attr('data-loaded') !== 'true') {
item.attr('data-loaded', false);
// Get the closes ajax loading module specificed in the tree.
var moduleName = item.closest('[data-ajax-loader]').attr('data-ajax-loader');
var thisTree = this;
// Flag this node as loading.
const p = item.find('p');
p.addClass('loading');
// Require the ajax module (must be AMD) and try to load the items.
require([moduleName], function(loader) {
// All ajax module must implement a "load" method.
loader.load(item).done(function() {
item.attr('data-loaded', true);
// Set defaults on the newly constructed part of the tree.
thisTree.initialiseNodes(item);
thisTree.finishExpandingGroup(item);
// Make sure no child elements of the item we just loaded are tabbable.
p.removeClass('loading');
promise.resolve();
});
});
} else {
this.finishExpandingGroup(item);
promise.resolve();
}
} else {
promise.resolve();
}
return promise;
};
/**
* Perform the necessary DOM changes to display a group item.
*
* @method finishExpandingGroup
* @param {Object} item is the jquery id of the parent item of the group.
*/
Tree.prototype.finishExpandingGroup = function(item) {
// Expand the group.
var group = this.getGroupFromItem(item);
group.removeAttr('aria-hidden');
item.attr('aria-expanded', 'true');
// Update the list of visible items.
this.refreshVisibleItemsCache();
};
/**
* Collapse an expanded group.
*
* @method collapseGroup
* @param {Object} item is the jquery id of the parent item of the group.
*/
Tree.prototype.collapseGroup = function(item) {
// If the item is not collapsible or already collapsed then do nothing.
if (!this.isGroupCollapsible(item) || this.isGroupCollapsed(item)) {
return;
}
// Collapse the group.
var group = this.getGroupFromItem(item);
group.attr('aria-hidden', 'true');
item.attr('aria-expanded', 'false');
// Update the list of visible items.
this.refreshVisibleItemsCache();
};
/**
* Expand or collapse a group.
*
* @method toggleGroup
* @param {Object} item is the jquery id of the parent item of the group.
*/
Tree.prototype.toggleGroup = function(item) {
if (item.attr('aria-expanded') === 'true') {
this.collapseGroup(item);
} else {
this.expandGroup(item);
}
};
/**
* Handle a key down event - ie navigate the tree.
*
* @method handleKeyDown
* @param {Event} e The event.
*/
// This function should be simplified. In the meantime..
// eslint-disable-next-line complexity
Tree.prototype.handleKeyDown = function(e) {
var item = $(e.target);
var currentIndex = this.getVisibleItems()?.index(item);
if ((e.altKey || e.ctrlKey || e.metaKey) || (e.shiftKey && e.keyCode != this.keys.tab)) {
// Do nothing.
return;
}
switch (e.keyCode) {
case this.keys.home: {
// Jump to first item in tree.
this.getVisibleItems().first().focus();
e.preventDefault();
return;
}
case this.keys.end: {
// Jump to last visible item.
this.getVisibleItems().last().focus();
e.preventDefault();
return;
}
case this.keys.enter: {
var links = item.children('a').length ? item.children('a') : item.children().not(SELECTORS.GROUP).find('a');
if (links.length) {
if (links.first().data('overrides-tree-activation-key-handler')) {
// If the link overrides handling of activation keys, let it do so.
links.first().triggerHandler(e);
} else if (typeof this.enterCallback === 'function') {
// Use callback if there is one.
this.enterCallback(item);
} else {
window.location.href = links.first().attr('href');
}
} else if (this.isGroupItem(item)) {
this.toggleGroup(item, true);
}
e.preventDefault();
return;
}
case this.keys.space: {
if (this.isGroupItem(item)) {
this.toggleGroup(item, true);
} else if (item.children('a').length) {
var firstLink = item.children('a').first();
if (firstLink.data('overrides-tree-activation-key-handler')) {
firstLink.triggerHandler(e);
}
}
e.preventDefault();
return;
}
case this.keys.left: {
var focusParent = function(tree) {
// Get the immediate visible parent group item that contains this element.
tree.getVisibleItems().filter(function() {
return tree.getGroupFromItem($(this)).has(item).length;
}).focus();
};
// If this is a group item then collapse it and focus the parent group
// in accordance with the aria spec.
if (this.isGroupItem(item)) {
if (this.isGroupCollapsed(item)) {
focusParent(this);
} else {
this.collapseGroup(item);
}
} else {
focusParent(this);
}
e.preventDefault();
return;
}
case this.keys.right: {
// If this is a group item then expand it and focus the first child item
// in accordance with the aria spec.
if (this.isGroupItem(item)) {
if (this.isGroupCollapsed(item)) {
this.expandGroup(item);
} else {
// Move to the first item in the child group.
this.getGroupFromItem(item).find(SELECTORS.ITEM).first().focus();
}
}
e.preventDefault();
return;
}
case this.keys.up: {
if (currentIndex > 0) {
var prev = this.getVisibleItems().eq(currentIndex - 1);
prev.focus();
}
e.preventDefault();
return;
}
case this.keys.down: {
if (currentIndex < this.getVisibleItems().length - 1) {
var next = this.getVisibleItems().eq(currentIndex + 1);
next.focus();
}
e.preventDefault();
return;
}
case this.keys.asterisk: {
// Expand all groups.
this.expandAllGroups();
e.preventDefault();
return;
}
}
};
/**
* Handle an item click.
*
* @param {Event} event the click event
* @param {jQuery} item the item clicked
*/
Tree.prototype.handleItemClick = function(event, item) {
// Update the active item.
item.focus();
// If the item is a group node.
if (this.isGroupItem(item)) {
this.toggleGroup(item);
}
};
/**
* Handle a click (select).
*
* @method handleClick
* @param {Event} event The event.
*/
Tree.prototype.handleClick = function(event) {
if (event.altKey || event.ctrlKey || event.shiftKey || event.metaKey) {
// Do nothing.
return;
}
// Get the closest tree item from the event target.
var item = $(event.target).closest('[role="treeitem"]');
if (!item.is(event.currentTarget)) {
return;
}
this.handleItemClick(event, item);
};
/**
* Handle a focus event.
*
* @method handleFocus
* @param {Event} e The event.
*/
Tree.prototype.handleFocus = function(e) {
this.setActiveItem($(e.target));
};
/**
* Bind the event listeners we require.
*
* @method bindEventHandlers
*/
Tree.prototype.bindEventHandlers = function() {
// Bind event handlers to the tree items. Use event delegates to allow
// for dynamically loaded parts of the tree.
this.treeRoot.on({
click: this.handleClick.bind(this),
keydown: this.handleKeyDown.bind(this),
focus: this.handleFocus.bind(this),
}, SELECTORS.ITEM);
};
return /** @alias module:core/tree */ Tree;
});