6cca43b0f4e61dc27553b781cfc4cba7bc6332e4
[moodle.git] / lib / amd / src / modal.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  * Contain the logic for modals.
18  *
19  * @module     core/modal
20  * @class      modal
21  * @package    core
22  * @copyright  2016 Ryan Wyllie <ryan@moodle.com>
23  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
24  */
25 define(['jquery', 'core/templates', 'core/notification', 'core/key_codes',
26         'core/custom_interaction_events', 'core/modal_backdrop', 'core/event', 'core/modal_events'],
27      function($, Templates, Notification, KeyCodes, CustomEvents, ModalBackdrop, Event, ModalEvents) {
29     var SELECTORS = {
30         CONTAINER: '[data-region="modal-container"]',
31         MODAL: '[data-region="modal"]',
32         HEADER: '[data-region="header"]',
33         TITLE: '[data-region="title"]',
34         BODY: '[data-region="body"]',
35         FOOTER: '[data-region="footer"]',
36         HIDE: '[data-action="hide"]',
37         DIALOG: '[role=dialog]',
38         MENU_BAR: '[role=menubar]',
39         HAS_Z_INDEX: '.moodle-has-zindex',
40         CAN_RECEIVE_FOCUS: 'input:not([type="hidden"]), a[href], button, textarea, select, [tabindex]',
41     };
43     var TEMPLATES = {
44         LOADING: 'core/loading',
45         BACKDROP: 'core/modal_backdrop',
46     };
48     /**
49      * Module singleton for the backdrop to be reused by all Modal instances.
50      */
51     var backdropPromise;
53     /**
54      * Constructor for the Modal.
55      *
56      * @param {object} root The root jQuery element for the modal
57      */
58     var Modal = function(root) {
59         this.root = $(root);
60         this.modal = this.root.find(SELECTORS.MODAL);
61         this.header = this.modal.find(SELECTORS.HEADER);
62         this.title = this.header.find(SELECTORS.TITLE);
63         this.body = this.modal.find(SELECTORS.BODY);
64         this.footer = this.modal.find(SELECTORS.FOOTER);
65         this.hiddenSiblings = [];
66         this.isAttached = false;
67         this.bodyJS = null;
68         this.footerJS = null;
70         if (!this.root.is(SELECTORS.CONTAINER)) {
71             Notification.exception({message: 'Element is not a modal container'});
72         }
74         if (!this.modal.length) {
75             Notification.exception({message: 'Container does not contain a modal'});
76         }
78         if (!this.header.length) {
79             Notification.exception({message: 'Modal is missing a header region'});
80         }
82         if (!this.title.length) {
83             Notification.exception({message: 'Modal header is missing a title region'});
84         }
86         if (!this.body.length) {
87             Notification.exception({message: 'Modal is missing a body region'});
88         }
90         if (!this.footer.length) {
91             Notification.exception({message: 'Modal is missing a footer region'});
92         }
94         this.registerEventListeners();
95     };
97     /**
98      * Add the modal to the page, if it hasn't already been added. This includes running any
99      * javascript that has been cached until now.
100      *
101      * @method attachToDOM
102      */
103     Modal.prototype.attachToDOM = function() {
104         if (this.isAttached) {
105             return;
106         }
108         $('body').append(this.root);
110         // If we'd cached any JS then we can run it how that the modal is
111         // attached to the DOM.
112         if (this.bodyJS) {
113             Templates.runTemplateJS(this.bodyJS);
114             this.bodyJS = null;
115         }
117         if (this.footerJS) {
118             Templates.runTemplateJS(this.footerJS);
119             this.footerJS = null;
120         }
122         this.isAttached = true;
123     };
125     /**
126      * Count the number of other visible modals (not including this one).
127      *
128      * @method countOtherVisibleModals
129      * @return {int}
130      */
131     Modal.prototype.countOtherVisibleModals = function() {
132         var count = 0;
133         $('body').find(SELECTORS.CONTAINER).each(function(index, element) {
134             element = $(element);
136             // If we haven't found ourself and the element is visible.
137             if (!this.root.is(element) && element.hasClass('show')) {
138                 count++;
139             }
140         }.bind(this));
142         return count;
143     };
145     /**
146      * Get the modal backdrop.
147      *
148      * @method getBackdrop
149      * @return {object} jQuery promise
150      */
151     Modal.prototype.getBackdrop = function() {
152         if (!backdropPromise) {
153             backdropPromise = Templates.render(TEMPLATES.BACKDROP, {})
154                 .then(function(html) {
155                     var element = $(html);
157                     return new ModalBackdrop(element);
158                 })
159                 .fail(Notification.exception);
160         }
162         return backdropPromise;
163     };
165     /**
166      * Get the root element of this modal.
167      *
168      * @method getRoot
169      * @return {object} jQuery object
170      */
171     Modal.prototype.getRoot = function() {
172         return this.root;
173     };
175     /**
176      * Get the modal element of this modal.
177      *
178      * @method getModal
179      * @return {object} jQuery object
180      */
181     Modal.prototype.getModal = function() {
182         return this.modal;
183     };
185     /**
186      * Get the modal title element.
187      *
188      * @method getTitle
189      * @return {object} jQuery object
190      */
191     Modal.prototype.getTitle = function() {
192         return this.title;
193     };
195     /**
196      * Get the modal body element.
197      *
198      * @method getBody
199      * @return {object} jQuery object
200      */
201     Modal.prototype.getBody = function() {
202         return this.body;
203     };
205     /**
206      * Get the modal footer element.
207      *
208      * @method getFooter
209      * @return {object} jQuery object
210      */
211     Modal.prototype.getFooter = function() {
212         return this.footer;
213     };
215     /**
216      * Set the modal title element.
217      *
218      * @method setTitle
219      * @param {string} value The title string
220      */
221     Modal.prototype.setTitle = function(value) {
222         var title = this.getTitle();
223         title.html(value);
224     };
226     /**
227      * Set the modal body element.
228      *
229      * This method is overloaded to take either a string
230      * value for the body or a jQuery promise that is resolved with HTML and Javascript
231      * most commonly from a Templates.render call.
232      *
233      * @method setBody
234      * @param {(string|object)} value The body string or jQuery promise
235      */
236     Modal.prototype.setBody = function(value) {
237         var body = this.getBody();
239         if (typeof value === 'string') {
240             // Just set the value if it's a string.
241             body.html(value);
242             Event.notifyFilterContentUpdated(body);
243             this.getRoot().trigger(ModalEvents.bodyRendered, this);
244         } else {
245             // Otherwise we assume it's a promise to be resolved with
246             // html and javascript.
247             Templates.render(TEMPLATES.LOADING, {}).done(function(html) {
248                 body.html(html);
250                 value.done(function(html, js) {
251                     body.html(html);
253                     if (js) {
254                         if (this.isAttached) {
255                             // If we're in the DOM then run the JS immediately.
256                             Templates.runTemplateJS(js);
257                         } else {
258                             // Otherwise cache it to be run when we're attached.
259                             this.bodyJS = js;
260                         }
261                     }
262                     Event.notifyFilterContentUpdated(body);
263                     this.getRoot().trigger(ModalEvents.bodyRendered, this);
264                 }.bind(this));
265             }.bind(this));
266         }
267     };
269     /**
270      * Set the modal footer element.
271      *
272      * This method is overloaded to take either a string
273      * value for the body or a jQuery promise that is resolved with HTML and Javascript
274      * most commonly from a Templates.render call.
275      *
276      * @method setFooter
277      * @param {(string|object)} value The footer string or jQuery promise
278      */
279     Modal.prototype.setFooter = function(value) {
280         var footer = this.getFooter();
282         if (typeof value === 'string') {
283             // Just set the value if it's a string.
284             footer.html(value);
285         } else {
286             // Otherwise we assume it's a promise to be resolved with
287             // html and javascript.
288             Templates.render(TEMPLATES.LOADING, {}).done(function(html) {
289                 footer.html(html);
291                 value.done(function(html, js) {
292                     footer.html(html);
294                     if (js) {
295                         if (this.isAttached) {
296                             // If we're in the DOM then run the JS immediately.
297                             Templates.runTemplateJS(js);
298                         } else {
299                             // Otherwise cache it to be run when we're attached.
300                             this.footerJS = js;
301                         }
302                     }
303                 }.bind(this));
304             }.bind(this));
305         }
306     };
308     /**
309      * Mark the modal as a large modal.
310      *
311      * @method setLarge
312      */
313     Modal.prototype.setLarge = function() {
314         if (this.isLarge()) {
315             return;
316         }
318         this.getRoot().addClass('large');
319     };
321     /**
322      * Check if the modal is a large modal.
323      *
324      * @method isLarge
325      * @return {bool}
326      */
327     Modal.prototype.isLarge = function() {
328         return this.getRoot().hasClass('large');
329     };
331     /**
332      * Mark the modal as a small modal.
333      *
334      * @method setSmall
335      */
336     Modal.prototype.setSmall = function() {
337         if (this.isSmall()) {
338             return;
339         }
341         this.getRoot().removeClass('large');
342     };
344     /**
345      * Check if the modal is a small modal.
346      *
347      * @method isSmall
348      * @return {bool}
349      */
350     Modal.prototype.isSmall = function() {
351         return !this.getRoot().hasClass('large');
352     };
354     /**
355      * Determine the highest z-index value currently on the page.
356      *
357      * @method calculateZIndex
358      * @return {int}
359      */
360     Modal.prototype.calculateZIndex = function() {
361         var items = $(SELECTORS.DIALOG + ', ' + SELECTORS.MENU_BAR + ', ' + SELECTORS.HAS_Z_INDEX);
362         var zIndex = parseInt(this.root.css('z-index'));
364         items.each(function(index, item) {
365             item = $(item);
366             // Note that webkit browsers won't return the z-index value from the CSS stylesheet
367             // if the element doesn't have a position specified. Instead it'll return "auto".
368             var itemZIndex = item.css('z-index') ? parseInt(item.css('z-index')) : 0;
370             if (itemZIndex > zIndex) {
371                 zIndex = itemZIndex;
372             }
373         });
375         return zIndex;
376     };
378     /**
379      * Check if this modal is visible.
380      *
381      * @method isVisible
382      * @return {bool}
383      */
384     Modal.prototype.isVisible = function() {
385         return this.root.hasClass('show');
386     };
388     /**
389      * Check if this modal has focus.
390      *
391      * @method hasFocus
392      * @return {bool}
393      */
394     Modal.prototype.hasFocus = function() {
395         var target = $(document.activeElement);
396         return this.root.is(target) || this.root.has(target).length;
397     };
399     /**
400      * Check if this modal has CSS transitions applied.
401      *
402      * @method hasTransitions
403      * @return {bool}
404      */
405     Modal.prototype.hasTransitions = function() {
406         return this.getRoot().hasClass('fade');
407     };
409     /**
410      * Display this modal. The modal will be attached to the DOM if it hasn't
411      * already been.
412      *
413      * @method show
414      */
415     Modal.prototype.show = function() {
416         if (this.isVisible()) {
417             return;
418         }
420         if (!this.isAttached) {
421             this.attachToDOM();
422         }
424         this.getBackdrop().done(function(backdrop) {
425             var currentIndex = this.calculateZIndex();
426             var newIndex = currentIndex + 2;
427             var newBackdropIndex = newIndex - 1;
428             this.root.css('z-index', newIndex);
429             backdrop.setZIndex(newBackdropIndex);
430             backdrop.show();
432             this.root.removeClass('hide').addClass('show');
433             this.accessibilityShow();
434             this.getTitle().focus();
435             $('body').addClass('modal-open');
436             this.root.trigger(ModalEvents.shown, this);
437         }.bind(this));
438     };
440     /**
441      * Hide this modal.
442      *
443      * @method hide
444      */
445     Modal.prototype.hide = function() {
446         if (!this.isVisible()) {
447             return;
448         }
450         this.getBackdrop().done(function(backdrop) {
451             if (!this.countOtherVisibleModals()) {
452                 // Hide the backdrop if we're the last open modal.
453                 backdrop.hide();
454                 $('body').removeClass('modal-open');
455             }
457             var currentIndex = parseInt(this.root.css('z-index'));
458             this.root.css('z-index', '');
459             backdrop.setZIndex(currentIndex - 3);
461             this.accessibilityHide();
463             if (this.hasTransitions()) {
464                 // Wait for CSS transitions to complete before hiding the element.
465                 this.getRoot().one('transitionend webkitTransitionEnd oTransitionEnd', function() {
466                     this.getRoot().removeClass('show').addClass('hide');
467                 }.bind(this));
468             } else {
469                 this.getRoot().removeClass('show').addClass('hide');
470             }
472             this.root.trigger(ModalEvents.hidden, this);
473         }.bind(this));
474     };
476     /**
477      * Remove this modal from the DOM.
478      *
479      * @method destroy
480      */
481     Modal.prototype.destroy = function() {
482         this.root.remove();
483         this.root.trigger(ModalEvents.destroyed, this);
484     };
486     /**
487      * Sets the appropriate aria attributes on this dialogue and the other
488      * elements in the DOM to ensure that screen readers are able to navigate
489      * the dialogue popup correctly.
490      *
491      * @method accessibilityShow
492      */
493     Modal.prototype.accessibilityShow = function() {
494         // We need to get a list containing each sibling element and the shallowest
495         // non-ancestral nodes in the DOM. We can shortcut this a little by leveraging
496         // the fact that this dialogue is always appended to the document body therefore
497         // it's siblings are the shallowest non-ancestral nodes. If that changes then
498         // this code should also be updated.
499         $('body').children().each(function(index, child) {
500             // Skip the current modal.
501             if (!this.root.is(child)) {
502                 child = $(child);
503                 var hidden = child.attr('aria-hidden');
504                 // If they are already hidden we can ignore them.
505                 if (hidden !== 'true') {
506                     // Save their current state.
507                     child.data('previous-aria-hidden', hidden);
508                     this.hiddenSiblings.push(child);
510                     // Hide this node from screen readers.
511                     child.attr('aria-hidden', 'true');
512                 }
513             }
514         }.bind(this));
516         // Make us visible to screen readers.
517         this.root.attr('aria-hidden', 'false');
518     };
520     /**
521      * Restores the aria visibility on the DOM elements changed when displaying
522      * the dialogue popup and makes the dialogue aria hidden to allow screen
523      * readers to navigate the main page correctly when the dialogue is closed.
524      *
525      * @method accessibilityHide
526      */
527     Modal.prototype.accessibilityHide = function() {
528         this.root.attr('aria-hidden', 'true');
530         // Restore the sibling nodes back to their original values.
531         $.each(this.hiddenSiblings, function(index, sibling) {
532             sibling = $(sibling);
533             var previousValue = sibling.data('previous-aria-hidden');
534             // If the element didn't previously have an aria-hidden attribute
535             // then we can just remove the one we set.
536             if (typeof previousValue == 'undefined') {
537                 sibling.removeAttr('aria-hidden');
538             } else {
539                 // Otherwise set it back to the old value (which will be false).
540                 sibling.attr('aria-hidden', previousValue);
541             }
542         });
544         // Clear the cache. No longer need to store these.
545         this.hiddenSiblings = [];
546     };
548     /**
549      * Handle the tab event to lock focus within this modal.
550      *
551      * @method handleTabLock
552      * @param {event} e The tab key jQuery event
553      */
554     Modal.prototype.handleTabLock = function(e) {
555         if (!this.hasFocus()) {
556             return;
557         }
559         var target = $(document.activeElement);
560         var focusableElements = this.modal.find(SELECTORS.CAN_RECEIVE_FOCUS);
561         var firstFocusable = focusableElements.first();
562         var lastFocusable = focusableElements.last();
564         if (target.is(firstFocusable) && e.shiftKey) {
565             lastFocusable.focus();
566             e.preventDefault();
567         } else if (target.is(lastFocusable) && !e.shiftKey) {
568             firstFocusable.focus();
569             e.preventDefault();
570         }
571     };
573     /**
574      * Set up all of the event handling for the modal.
575      *
576      * @method registerEventListeners
577      */
578     Modal.prototype.registerEventListeners = function() {
579         this.getRoot().on('keydown', function(e) {
580             if (!this.isVisible()) {
581                 return;
582             }
584             if (e.keyCode == KeyCodes.tab) {
585                 this.handleTabLock(e);
586             } else if (e.keyCode == KeyCodes.escape) {
587                 this.hide();
588             }
589         }.bind(this));
591         CustomEvents.define(this.getModal(), [CustomEvents.events.activate]);
592         this.getModal().on(CustomEvents.events.activate, SELECTORS.HIDE, function(e, data) {
593             this.hide();
594             data.originalEvent.preventDefault();
595         }.bind(this));
596     };
598     return Modal;
599 });