MDL-38661 JavaScript: Ensure that ARIA tags are set when expanding/collapsing content
[moodle.git] / course / yui / src / categoryexpander / js / categoryexpander.js
1 /**
2  * Adds toggling of subcategory with automatic loading using AJAX.
3  *
4  * This also includes application of an animation to improve user experience.
5  *
6  * @module moodle-course-categoryexpander
7  */
9 /**
10  * The course category expander.
11  *
12  * @constructor
13  * @class Y.Moodle.course.categoryexpander
14  */
16 var CSS = {
17         CONTENTNODE: 'content',
18         COLLAPSEALL: 'collapse-all',
19         DISABLED: 'disabled',
20         LOADED: 'loaded',
21         NOTLOADED: 'notloaded',
22         SECTIONCOLLAPSED: 'collapsed',
23         HASCHILDREN: 'with_children'
24     },
25     SELECTORS = {
26         LOADEDTREES: '.with_children.loaded',
27         CONTENTNODE: '.content',
28         CATEGORYLISTENLINK: '.category .info .name',
29         CATEGORYSPINNERLOCATION: '.name',
30         CATEGORYWITHCOLLAPSEDLOADEDCHILDREN: '.category.with_children.loaded.collapsed',
31         CATEGORYWITHMAXIMISEDLOADEDCHILDREN: '.category.with_children.loaded:not(.collapsed)',
32         COLLAPSEEXPAND: '.collapseexpand',
33         COURSEBOX: '.coursebox',
34         COURSEBOXLISTENLINK: '.coursebox .moreinfo',
35         COURSEBOXSPINNERLOCATION: '.name a',
36         COURSECATEGORYTREE: '.course_category_tree',
37         PARENTWITHCHILDREN: '.category'
38     },
39     NS = Y.namespace('Moodle.course.categoryexpander'),
40     TYPE_CATEGORY = 0,
41     TYPE_COURSE = 1,
42     URL = M.cfg.wwwroot + '/course/category.ajax.php';
44 /**
45  * Set up the category expander.
46  *
47  * No arguments are required.
48  *
49  * @method init
50  */
51 NS.init = function() {
52     var doc = Y.one(Y.config.doc);
53     doc.delegate('click', this.toggle_category_expansion, SELECTORS.CATEGORYLISTENLINK, this);
54     doc.delegate('click', this.toggle_coursebox_expansion, SELECTORS.COURSEBOXLISTENLINK, this);
55     doc.delegate('click', this.collapse_expand_all, SELECTORS.COLLAPSEEXPAND, this);
57     // Only set up they keybaord listeners when tab is first pressed - it
58     // may never happen and modifying the DOM on a large number of nodes
59     // can be very expensive.
60     doc.once('key', this.setup_keyboard_listeners, 'tab', this);
61 };
63 /**
64  * Set up keyboard expansion for course content.
65  *
66  * This includes setting up the delegation but also adding the nodes to the
67  * tabflow.
68  *
69  * @method setup_keyboard_listeners
70  */
71 NS.setup_keyboard_listeners = function() {
72     var doc = Y.one(Y.config.doc);
74     Y.log('Setting the tabindex for all expandable course nodes', 'info', 'moodle-course-categoryexpander');
75     doc.all(SELECTORS.CATEGORYLISTENLINK, SELECTORS.COURSEBOXLISTENLINK, SELECTORS.COLLAPSEEXPAND).setAttribute('tabindex', '0');
78     Y.one(Y.config.doc).delegate('key', this.toggle_category_expansion, 'enter', SELECTORS.CATEGORYLISTENLINK, this);
79     Y.one(Y.config.doc).delegate('key', this.toggle_coursebox_expansion, 'enter', SELECTORS.COURSEBOXLISTENLINK, this);
80     Y.one(Y.config.doc).delegate('key', this.collapse_expand_all, 'enter', SELECTORS.COLLAPSEEXPAND, this);
81 };
83 /**
84  * Toggle the animation of the clicked category node.
85  *
86  * @method toggle_category_expansion
87  * @private
88  * @param {EventFacade} e
89  */
90 NS.toggle_category_expansion = function(e) {
91     // Load the actual dependencies now that we've been called.
92     Y.use('io-base', 'json-parse', 'moodle-core-notification', 'anim', function() {
93         // Overload the toggle_category_expansion with the _toggle_category_expansion function to ensure that
94         // this function isn't called in the future, and call it for the first time.
95         NS.toggle_category_expansion = NS._toggle_category_expansion;
96         NS.toggle_category_expansion(e);
97     });
98 };
100 /**
101  * Toggle the animation of the clicked coursebox node.
102  *
103  * @method toggle_coursebox_expansion
104  * @private
105  * @param {EventFacade} e
106  */
107 NS.toggle_coursebox_expansion = function(e) {
108     // Load the actual dependencies now that we've been called.
109     Y.use('io-base', 'json-parse', 'moodle-core-notification', 'anim', function() {
110         // Overload the toggle_coursebox_expansion with the _toggle_coursebox_expansion function to ensure that
111         // this function isn't called in the future, and call it for the first time.
112         NS.toggle_coursebox_expansion = NS._toggle_coursebox_expansion;
113         NS.toggle_coursebox_expansion(e);
114     });
116     e.preventDefault();
117 };
119 NS._toggle_coursebox_expansion = function(e) {
120     var courseboxnode;
122     // Grab the parent category container - this is where the new content will be added.
123     courseboxnode = e.target.ancestor(SELECTORS.COURSEBOX, true);
124     e.preventDefault();
126     if (courseboxnode.hasClass(CSS.LOADED)) {
127         // We've already loaded this content so we just need to toggle the view of it.
128         this.run_expansion(courseboxnode);
129         return;
130     }
132     this._toggle_generic_expansion({
133         parentnode: courseboxnode,
134         childnode: courseboxnode.one(SELECTORS.CONTENTNODE),
135         spinnerhandle: SELECTORS.COURSEBOXSPINNERLOCATION,
136         data: {
137             courseid: courseboxnode.getData('courseid'),
138             type: TYPE_COURSE
139         }
140     });
141 };
143 NS._toggle_category_expansion = function(e) {
144     var categorynode,
145         categoryid,
146         depth;
148     if (e.target.test('a') || e.target.test('img')) {
149         // Return early if either an anchor or an image were clicked.
150         return;
151     }
153     // Grab the parent category container - this is where the new content will be added.
154     categorynode = e.target.ancestor(SELECTORS.PARENTWITHCHILDREN, true);
156     if (!categorynode.hasClass(CSS.HASCHILDREN)) {
157         // Nothing to do here - this category has no children.
158         return;
159     }
161     if (categorynode.hasClass(CSS.LOADED)) {
162         // We've already loaded this content so we just need to toggle the view of it.
163         this.run_expansion(categorynode);
164         return;
165     }
167     // We use Data attributes to store the category.
168     categoryid = categorynode.getData('categoryid');
169     depth = categorynode.getData('depth');
170     if (typeof categoryid === "undefined" || typeof depth === "undefined") {
171         return;
172     }
174     this._toggle_generic_expansion({
175         parentnode: categorynode,
176         childnode: categorynode.one(SELECTORS.CONTENTNODE),
177         spinnerhandle: SELECTORS.CATEGORYSPINNERLOCATION,
178         data: {
179             categoryid: categoryid,
180             depth: depth,
181             showcourses: categorynode.getData('showcourses'),
182             type: TYPE_CATEGORY
183         }
184     });
185 };
187 /**
188  * Wrapper function to handle toggling of generic types.
189  *
190  * @method _toggle_generic_expansion
191  * @private
192  * @param {Object} config
193  */
194 NS._toggle_generic_expansion = function(config) {
195     if (config.spinnerhandle) {
196       // Add a spinner to give some feedback to the user.
197       spinner = M.util.add_spinner(Y, config.parentnode.one(config.spinnerhandle)).show();
198     }
200     // Fetch the data.
201     Y.io(URL, {
202         method: 'POST',
203         context: this,
204         on: {
205             complete: this.process_results
206         },
207         data: config.data,
208         "arguments": {
209             parentnode: config.parentnode,
210             childnode: config.childnode,
211             spinner: spinner
212         }
213     });
214 };
216 /**
217  * Apply the animation on the supplied node.
218  *
219  * @method run_expansion
220  * @private
221  * @param {Node} categorynode The node to apply the animation to
222  */
223 NS.run_expansion = function(categorynode) {
224     var categorychildren = categorynode.one(SELECTORS.CONTENTNODE),
225         self = this,
226         ancestor = categorynode.ancestor(SELECTORS.COURSECATEGORYTREE);
228     // Add our animation to the categorychildren.
229     this.add_animation(categorychildren);
232     // If we already have the class, remove it before showing otherwise we perform the
233     // animation whilst the node is hidden.
234     if (categorynode.hasClass(CSS.SECTIONCOLLAPSED)) {
235         // To avoid a jump effect, we need to set the height of the children to 0 here before removing the SECTIONCOLLAPSED class.
236         categorychildren.setStyle('height', '0');
237         categorynode.removeClass(CSS.SECTIONCOLLAPSED);
238         categorynode.setAttribute('aria-expanded', 'true');
239         categorychildren.fx.set('reverse', false);
240     } else {
241         categorychildren.fx.set('reverse', true);
242         categorychildren.fx.once('end', function(e, categorynode) {
243             categorynode.addClass(CSS.SECTIONCOLLAPSED);
244             categorynode.setAttribute('aria-expanded', 'false');
245         }, this, categorynode);
246     }
248     categorychildren.fx.once('end', function(e, categorychildren) {
249         // Remove the styles that the animation has set.
250         categorychildren.setStyles({
251             height: '',
252             opacity: ''
253         });
255         // To avoid memory gobbling, remove the animation. It will be added back if called again.
256         this.destroy();
257         self.update_collapsible_actions(ancestor);
258     }, categorychildren.fx, categorychildren);
260     // Now that everything has been set up, run the animation.
261     categorychildren.fx.run();
262 };
264 NS.collapse_expand_all = function(e) {
265     // The collapse/expand button has no actual target but we need to prevent it's default
266     // action to ensure we don't make the page reload/jump.
267     e.preventDefault();
269     if (e.currentTarget.hasClass(CSS.DISABLED)) {
270         // The collapse/expand is currently disabled.
271         return;
272     }
274     var ancestor = e.currentTarget.ancestor(SELECTORS.COURSECATEGORYTREE);
275     if (!ancestor) {
276         return;
277     }
279     var collapseall = ancestor.one(SELECTORS.COLLAPSEEXPAND);
280     if (collapseall.hasClass(CSS.COLLAPSEALL)) {
281         this.collapse_all(ancestor);
282     } else {
283         this.expand_all(ancestor);
284     }
285     this.update_collapsible_actions(ancestor);
286 };
288 NS.expand_all = function(ancestor) {
289     var finalexpansions = [];
291     ancestor.all(SELECTORS.CATEGORYWITHCOLLAPSEDLOADEDCHILDREN)
292         .each(function(c) {
293         if (c.ancestor(SELECTORS.CATEGORYWITHCOLLAPSEDLOADEDCHILDREN)) {
294             // Expand the hidden children first without animation.
295             c.removeClass(CSS.SECTIONCOLLAPSED);
296             c.all(SELECTORS.LOADEDTREES).removeClass(CSS.SECTIONCOLLAPSED);
297         } else {
298             finalexpansions.push(c);
299         }
300     }, this);
302     // Run the final expansion with animation on the visible items.
303     Y.all(finalexpansions).each(function(c) {
304         this.run_expansion(c);
305     }, this);
307 };
309 NS.collapse_all = function(ancestor) {
310     var finalcollapses = [];
312     ancestor.all(SELECTORS.CATEGORYWITHMAXIMISEDLOADEDCHILDREN)
313         .each(function(c) {
314         if (c.ancestor(SELECTORS.CATEGORYWITHMAXIMISEDLOADEDCHILDREN)) {
315             finalcollapses.push(c);
316         } else {
317             // Collapse the visible items first
318             this.run_expansion(c);
319         }
320     }, this);
322     // Run the final collapses now that the these are hidden hidden.
323     Y.all(finalcollapses).each(function(c) {
324         c.addClass(CSS.SECTIONCOLLAPSED);
325         c.all(SELECTORS.LOADEDTREES).addClass(CSS.SECTIONCOLLAPSED);
326     }, this);
327 };
329 NS.update_collapsible_actions = function(ancestor) {
330     var foundmaximisedchildren = false,
331         // Grab the anchor for the collapseexpand all link.
332         togglelink = ancestor.one(SELECTORS.COLLAPSEEXPAND);
334     if (!togglelink) {
335         // We should always have a togglelink but ensure.
336         return;
337     }
339     // Search for any visibly expanded children.
340     ancestor.all(SELECTORS.CATEGORYWITHMAXIMISEDLOADEDCHILDREN).each(function(n) {
341         // If we can find any collapsed ancestors, skip.
342         if (n.ancestor(SELECTORS.CATEGORYWITHCOLLAPSEDLOADEDCHILDREN)) {
343             return false;
344         }
345         foundmaximisedchildren = true;
346         return true;
347     });
349     if (foundmaximisedchildren) {
350         // At least one maximised child found. Show the collapseall.
351         togglelink.setHTML(M.util.get_string('collapseall', 'moodle'))
352             .addClass(CSS.COLLAPSEALL)
353             .removeClass(CSS.DISABLED);
354     } else {
355         // No maximised children found but there are collapsed children. Show the expandall.
356         togglelink.setHTML(M.util.get_string('expandall', 'moodle'))
357             .removeClass(CSS.COLLAPSEALL)
358             .removeClass(CSS.DISABLED);
359     }
360 };
362 /**
363  * Process the data returned by Y.io.
364  * This includes appending it to the relevant part of the DOM, and applying our animations.
365  *
366  * @method process_results
367  * @private
368  * @param {String} tid The Transaction ID
369  * @param {Object} response The Reponse returned by Y.IO
370  * @param {Object} ioargs The additional arguments provided by Y.IO
371  */
372 NS.process_results = function(tid, response, args) {
373     var newnode,
374         data;
375     try {
376         data = Y.JSON.parse(response.responseText);
377         if (data.error) {
378             return new M.core.ajaxException(data);
379         }
380     } catch (e) {
381         return new M.core.exception(e);
382     }
384     // Insert the returned data into a new Node.
385     newnode = Y.Node.create(data);
387     // Append to the existing child location.
388     args.childnode.appendChild(newnode);
390     // Now that we have content, we can swap the classes on the toggled container.
391     args.parentnode
392         .addClass(CSS.LOADED)
393         .removeClass(CSS.NOTLOADED);
395     // Toggle the open/close status of the node now that it's content has been loaded.
396     this.run_expansion(args.parentnode);
398     // Remove the spinner now that we've started to show the content.
399     if (args.spinner) {
400         args.spinner.hide().destroy();
401     }
402 };
404 /**
405  * Add our animation to the Node.
406  *
407  * @method add_animation
408  * @private
409  * @param {Node} childnode
410  */
411 NS.add_animation = function(childnode) {
412     if (typeof childnode.fx !== "undefined") {
413         // The animation has already been plugged to this node.
414         return childnode;
415     }
417     childnode.plug(Y.Plugin.NodeFX, {
418         from: {
419             height: 0,
420             opacity: 0
421         },
422         to: {
423             // This sets a dynamic height in case the node content changes.
424             height: function(node) {
425                 // Get expanded height (offsetHeight may be zero).
426                 return node.get('scrollHeight');
427             },
428             opacity: 1
429         },
430         duration: 0.2
431     });
433     return childnode;
434 };