4ba8615e13a42b5b703a724089b838f78217cb98
[moodle.git] / lib / amd / src / tree.js
1 // This file is part of Moodle - http://moodle.org/
2 //
3 // Moodle is free software: you can redistribute it and/or modify
4 // it under the terms of the GNU General Public License as published by
5 // the Free Software Foundation, either version 3 of the License, or
6 // (at your option) any later version.
7 //
8 // Moodle is distributed in the hope that it will be useful,
9 // but WITHOUT ANY WARRANTY; without even the implied warranty of
10 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
11 // GNU General Public License for more details.
12 //
13 // You should have received a copy of the GNU General Public License
14 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
16 /**
17  * Implement an accessible aria tree widget, from a nested unordered list.
18  * Based on http://oaa-accessibility.org/example/41/.
19  *
20  * @module     tool_lp/tree
21  * @package    core
22  * @copyright  2015 Damyon Wiese <damyon@moodle.com>
23  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
24  */
25 define(['jquery'], function($) {
26     // Private variables and functions.
27     var SELECTORS = {
28         ITEM: '[role=treeitem]',
29         GROUP: '[role=treeitem]:has([role=group]), [role=treeitem][aria-owns], [role=treeitem][data-requires-ajax=true]',
30         CLOSED_GROUP: '[role=treeitem]:has([role=group])[aria-expanded=false], [role=treeitem][aria-owns][aria-expanded=false], ' +
31                  '[role=treeitem][data-requires-ajax=true][aria-expanded=false]',
32         FIRST_ITEM: '[role=treeitem]:first',
33         VISIBLE_ITEM: '[role=treeitem]:visible',
34         UNLOADED_AJAX_ITEM: '[role=treeitem][data-requires-ajax=true][data-loaded=false][aria-expanded=true]'
35     };
37     /**
38      * Constructor.
39      *
40      * @param {String} selector
41      * @param {function} selectCallback Called when the active node is changed.
42      */
43     var Tree = function(selector, selectCallback) {
44         this.treeRoot = $(selector);
46         this.treeRoot.data('activeItem', null);
47         this.selectCallback = selectCallback;
48         this.keys = {
49             tab:      9,
50             enter:    13,
51             space:    32,
52             pageup:   33,
53             pagedown: 34,
54             end:      35,
55             home:     36,
56             left:     37,
57             up:       38,
58             right:    39,
59             down:     40,
60             asterisk: 106
61         };
63         // Apply the standard default initialisation for all nodes, starting with the tree root.
64         this.initialiseNodes(this.treeRoot);
65         // Make the first item the active item for the tree so that it is added to the tab order.
66         this.setActiveItem(this.treeRoot.find(SELECTORS.FIRST_ITEM));
67         // Create the cache of the visible items.
68         this.refreshVisibleItemsCache();
69         // Create the event handlers for the tree.
70         this.bindEventHandlers();
71     };
73     Tree.prototype.registerEnterCallback = function(callback) {
74         this.enterCallback = callback;
75     };
77     /**
78      * Find all visible tree items and save a cache of them on the tree object.
79      *
80      * @method refreshVisibleItemsCache
81      */
82     Tree.prototype.refreshVisibleItemsCache = function() {
83         this.treeRoot.data('visibleItems', this.treeRoot.find(SELECTORS.VISIBLE_ITEM));
84     };
86     /**
87      * Get all visible tree items.
88      *
89      * @method getVisibleItems
90      * @return {Object} visible items
91      */
92     Tree.prototype.getVisibleItems = function() {
93         return this.treeRoot.data('visibleItems');
94     };
96     /**
97      * Mark the given item as active within the tree and fire the callback for when the active item is set.
98      *
99      * @method setActiveItem
100      * @param {object} item jquery object representing an item on the tree.
101      */
102     Tree.prototype.setActiveItem = function(item) {
103         var currentActive = this.treeRoot.data('activeItem');
104         if (item === currentActive) {
105             return;
106         }
108         // Remove previous active from tab order.
109         if (currentActive) {
110             currentActive.attr('tabindex', '-1');
111             currentActive.attr('aria-selected', 'false');
112         }
113         item.attr('tabindex', '0');
114         item.attr('aria-selected', 'true');
116         // Set the new active item.
117         this.treeRoot.data('activeItem', item);
119         if (typeof this.selectCallback === 'function') {
120             this.selectCallback(item);
121         }
122     };
124     /**
125      * Determines if the given item is a group item (contains child tree items) in the tree.
126      *
127      * @method isGroupItem
128      * @param {object} item jquery object representing an item on the tree.
129      * @returns {bool}
130      */
131     Tree.prototype.isGroupItem = function(item) {
132         return item.is(SELECTORS.GROUP);
133     };
135     /**
136      * Determines if the given item is a group item (contains child tree items) in the tree.
137      *
138      * @method isGroupItem
139      * @param {object} item jquery object representing an item on the tree.
140      * @returns {bool}
141      */
142     Tree.prototype.getGroupFromItem = function(item) {
143         var ariaowns = this.treeRoot.find('#' + item.attr('aria-owns'));
144         var plain = item.children('[role=group]');
145         if (ariaowns.length > plain.length) {
146             return ariaowns;
147         } else {
148             return plain;
149         }
150     };
152     /**
153      * Determines if the given group item (contains child tree items) is collapsed.
154      *
155      * @method isGroupCollapsed
156      * @param {object} item jquery object representing a group item on the tree.
157      * @returns {bool}
158      */
159     Tree.prototype.isGroupCollapsed = function(item) {
160         return item.attr('aria-expanded') === 'false';
161     };
163     /**
164      * Determines if the given group item (contains child tree items) can be collapsed.
165      *
166      * @method isGroupCollapsible
167      * @param {object} item jquery object representing a group item on the tree.
168      * @returns {bool}
169      */
170     Tree.prototype.isGroupCollapsible = function(item) {
171         return item.attr('data-collapsible') !== 'false';
172     };
174     /**
175      * Performs the tree initialisation for all child items from the given node,
176      * such as removing everything from the tab order and setting aria selected
177      * on items.
178      *
179      * @method initialiseNodes
180      * @param {object} node jquery object representing a node.
181      */
182     Tree.prototype.initialiseNodes = function(node) {
183         this.removeAllFromTabOrder(node);
184         this.setAriaSelectedFalseOnItems(node);
186         // Get all ajax nodes that have been rendered as expanded but haven't loaded the child items yet.
187         var thisTree = this;
188         node.find(SELECTORS.UNLOADED_AJAX_ITEM).each(function() {
189             var unloadedNode = $(this);
190             // Collapse and then expand to trigger the ajax loading.
191             thisTree.collapseGroup(unloadedNode);
192             thisTree.expandGroup(unloadedNode);
193         });
194     };
196     /**
197      * Removes all child DOM elements of the given node from the tab order.
198      *
199      * @method removeAllFromTabOrder
200      * @param {object} node jquery object representing a node.
201      */
202     Tree.prototype.removeAllFromTabOrder = function(node) {
203         node.find('*').attr('tabindex', '-1');
204         this.getGroupFromItem($(node)).find('*').attr('tabindex', '-1');
205     };
207     /**
208      * Find all child tree items from the given node and set the aria selected attribute to false.
209      *
210      * @method setAriaSelectedFalseOnItems
211      * @param {object} node jquery object representing a node.
212      */
213     Tree.prototype.setAriaSelectedFalseOnItems = function(node) {
214         node.find(SELECTORS.ITEM).attr('aria-selected', 'false');
215     };
217     /**
218      * Expand all group nodes within the tree.
219      *
220      * @method expandAllGroups
221      */
222     Tree.prototype.expandAllGroups = function() {
223         var thisTree = this;
225         this.treeRoot.find(SELECTORS.CLOSED_GROUP).each(function() {
226             var groupNode = $(this);
228             thisTree.expandGroup($(this)).done(function() {
229                 thisTree.expandAllChildGroups(groupNode);
230             });
231         });
232     };
234     /**
235      * Find all child group nodes from the given node and expand them.
236      *
237      * @method expandAllChildGroups
238      * @param {Object} item is the jquery id of the group.
239      */
240     Tree.prototype.expandAllChildGroups = function(item) {
241         var thisTree = this;
243         this.getGroupFromItem(item).find(SELECTORS.CLOSED_GROUP).each(function() {
244             var groupNode = $(this);
246             thisTree.expandGroup($(this)).done(function() {
247                 thisTree.expandAllChildGroups(groupNode);
248             });
249         });
250     };
252     /**
253      * Expand a collapsed group.
254      *
255      * Handles expanding nodes that are ajax loaded (marked with a data-requires-ajax attribute).
256      *
257      * @method expandGroup
258      * @param {Object} item is the jquery id of the parent item of the group.
259      * @return {Object} a promise that is resolved when the group has been expanded.
260      */
261     Tree.prototype.expandGroup = function(item) {
262         var promise = $.Deferred();
263         // Ignore nodes that are explicitly maked as not expandable or are already expanded.
264         if (item.attr('data-expandable') !== 'false' && this.isGroupCollapsed(item)) {
265             // If this node requires ajax load and we haven't already loaded it.
266             if (item.attr('data-requires-ajax') === 'true' && item.attr('data-loaded') !== 'true') {
267                 item.attr('data-loaded', false);
268                 // Get the closes ajax loading module specificed in the tree.
269                 var moduleName = item.closest('[data-ajax-loader]').attr('data-ajax-loader');
270                 var thisTree = this;
271                 // Flag this node as loading.
272                 item.addClass('loading');
273                 // Require the ajax module (must be AMD) and try to load the items.
274                 require([moduleName], function(loader) {
275                     // All ajax module must implement a "load" method.
276                     loader.load(item).done(function() {
277                         item.attr('data-loaded', true);
279                         // Set defaults on the newly constructed part of the tree.
280                         thisTree.initialiseNodes(item);
281                         thisTree.finishExpandingGroup(item);
282                         // Make sure no child elements of the item we just loaded are tabbable.
283                         item.removeClass('loading');
284                         promise.resolve();
285                     });
286                 });
287             } else {
288                 this.finishExpandingGroup(item);
289                 promise.resolve();
290             }
291         } else {
292             promise.resolve();
293         }
294         return promise;
295     };
297     /**
298      * Perform the necessary DOM changes to display a group item.
299      *
300      * @method finishExpandingGroup
301      * @param {Object} item is the jquery id of the parent item of the group.
302      */
303     Tree.prototype.finishExpandingGroup = function(item) {
304         // Expand the group.
305         var group = this.getGroupFromItem(item);
306         group.removeAttr('aria-hidden');
307         item.attr('aria-expanded', 'true');
309         // Update the list of visible items.
310         this.refreshVisibleItemsCache();
311     };
313     /**
314      * Collapse an expanded group.
315      *
316      * @method collapseGroup
317      * @param {Object} item is the jquery id of the parent item of the group.
318      */
319     Tree.prototype.collapseGroup = function(item) {
320         // If the item is not collapsible or already collapsed then do nothing.
321         if (!this.isGroupCollapsible(item) || this.isGroupCollapsed(item)) {
322             return;
323         }
325         // Collapse the group.
326         var group = this.getGroupFromItem(item);
327         group.attr('aria-hidden', 'true');
328         item.attr('aria-expanded', 'false');
330         // Update the list of visible items.
331         this.refreshVisibleItemsCache();
332     };
334     /**
335      * Expand or collapse a group.
336      *
337      * @method toggleGroup
338      * @param {Object} item is the jquery id of the parent item of the group.
339      */
340     Tree.prototype.toggleGroup = function(item) {
341         if (item.attr('aria-expanded') === 'true') {
342             this.collapseGroup(item);
343         } else {
344             this.expandGroup(item);
345         }
346     };
348     /**
349      * Handle a key down event - ie navigate the tree.
350      *
351      * @method handleKeyDown
352      * @param {Object} item is the jquery id of the parent item of the group.
353      * @param {Event} e The event.
354      */
355      // This function should be simplified. In the meantime..
356      // eslint-disable-next-line complexity
357     Tree.prototype.handleKeyDown = function(item, e) {
358         var currentIndex = this.getVisibleItems().index(item);
360         if ((e.altKey || e.ctrlKey || e.metaKey) || (e.shiftKey && e.keyCode != this.keys.tab)) {
361             // Do nothing.
362             return;
363         }
365         switch (e.keyCode) {
366             case this.keys.home: {
367                 // Jump to first item in tree.
368                 this.getVisibleItems().first().focus();
370                 e.preventDefault();
371                 return;
372             }
373             case this.keys.end: {
374                 // Jump to last visible item.
375                 this.getVisibleItems().last().focus();
377                 e.preventDefault();
378                 return;
379             }
380             case this.keys.enter: {
381                 var links = item.children('a').length ? item.children('a') : item.children().not(SELECTORS.GROUP).find('a');
382                 if (links.length) {
383                     if (links.first().data('overrides-tree-activation-key-handler')) {
384                         // If the link overrides handling of activation keys, let it do so.
385                         links.first().triggerHandler(e);
386                     } else if (typeof this.enterCallback === 'function') {
387                         // Use callback if there is one.
388                         this.enterCallback(item);
389                     } else {
390                         window.location.href = links.first().attr('href');
391                     }
392                 } else if (this.isGroupItem(item)) {
393                     this.toggleGroup(item, true);
394                 }
396                 e.preventDefault();
397                 return;
398             }
399             case this.keys.space: {
400                 if (this.isGroupItem(item)) {
401                     this.toggleGroup(item, true);
402                 } else if (item.children('a').length) {
403                     var firstLink = item.children('a').first();
405                     if (firstLink.data('overrides-tree-activation-key-handler')) {
406                         firstLink.triggerHandler(e);
407                     }
408                 }
410                 e.preventDefault();
411                 return;
412             }
413             case this.keys.left: {
414                 var focusParent = function(tree) {
415                     // Get the immediate visible parent group item that contains this element.
416                     tree.getVisibleItems().filter(function() {
417                         return tree.getGroupFromItem($(this)).has(item).length;
418                     }).focus();
419                 };
421                 // If this is a goup item then collapse it and focus the parent group
422                 // in accordance with the aria spec.
423                 if (this.isGroupItem(item)) {
424                     if (this.isGroupCollapsed(item)) {
425                         focusParent(this);
426                     } else {
427                         this.collapseGroup(item);
428                     }
429                 } else {
430                     focusParent(this);
431                 }
433                 e.preventDefault();
434                 return;
435             }
436             case this.keys.right: {
437                 // If this is a group item then expand it and focus the first child item
438                 // in accordance with the aria spec.
439                 if (this.isGroupItem(item)) {
440                     if (this.isGroupCollapsed(item)) {
441                         this.expandGroup(item);
442                     } else {
443                         // Move to the first item in the child group.
444                         this.getGroupFromItem(item).find(SELECTORS.ITEM).first().focus();
445                     }
446                 }
448                 e.preventDefault();
449                 return;
450             }
451             case this.keys.up: {
453                 if (currentIndex > 0) {
454                     var prev = this.getVisibleItems().eq(currentIndex - 1);
456                     prev.focus();
457                 }
459                 e.preventDefault();
460                 return;
461             }
462             case this.keys.down: {
464                 if (currentIndex < this.getVisibleItems().length - 1) {
465                     var next = this.getVisibleItems().eq(currentIndex + 1);
467                     next.focus();
468                 }
470                 e.preventDefault();
471                 return;
472             }
473             case this.keys.asterisk: {
474                 // Expand all groups.
475                 this.expandAllGroups();
476                 e.preventDefault();
477                 return;
478             }
479         }
480     };
482     /**
483      * Handle a click (select).
484      *
485      * @method handleClick
486      * @param {Object} item The jquery id of the parent item of the group.
487      * @param {Event} e The event.
488      */
489     Tree.prototype.handleClick = function(item, e) {
491         if (e.altKey || e.ctrlKey || e.shiftKey || e.metaKey) {
492             // Do nothing.
493             return;
494         }
496         // Update the active item.
497         item.focus();
499         // If the item is a group node.
500         if (this.isGroupItem(item)) {
501             this.toggleGroup(item);
502         }
503     };
505     /**
506      * Handle a focus event.
507      *
508      * @method handleFocus
509      * @param {Object} item The jquery id of the parent item of the group.
510      * @param {Event} e The event.
511      */
512     Tree.prototype.handleFocus = function(item) {
514         this.setActiveItem(item);
515     };
517     /**
518      * Bind the event listeners we require.
519      *
520      * @method bindEventHandlers
521      */
522     Tree.prototype.bindEventHandlers = function() {
523         var thisObj = this;
525         // Bind event handlers to the tree items. Use event delegates to allow
526         // for dynamically loaded parts of the tree.
527         this.treeRoot.on({
528             click: function(e) {
529               return thisObj.handleClick($(this), e);
530             },
531             keydown: function(e) {
532               return thisObj.handleKeyDown($(this), e);
533             },
534             focus: function() {
535               return thisObj.handleFocus($(this));
536             },
537         }, SELECTORS.ITEM);
538     };
540     return /** @alias module:tool_lp/tree */ Tree;
541 });