b94cd8d67fecbda7d15fd0d46a4923b22ee79276
[moodle.git] / lib / yui / src / notification / js / dialogue.js
1 /* global DIALOGUE_PREFIX, BASE */
3 /**
4  * The generic dialogue class for use in Moodle.
5  *
6  * @module moodle-core-notification
7  * @submodule moodle-core-notification-dialogue
8  */
10 var DIALOGUE_NAME = 'Moodle dialogue',
11     DIALOGUE,
12     DIALOGUE_FULLSCREEN_CLASS = DIALOGUE_PREFIX + '-fullscreen',
13     DIALOGUE_HIDDEN_CLASS = DIALOGUE_PREFIX + '-hidden',
14     DIALOGUE_SELECTOR = ' [role=dialog]',
15     MENUBAR_SELECTOR = '[role=menubar]',
16     DOT = '.',
17     HAS_ZINDEX = 'moodle-has-zindex',
18     CAN_RECEIVE_FOCUS_SELECTOR = 'input:not([type="hidden"]), a[href], button, textarea, select, [tabindex]',
19     FORM_SELECTOR = 'form';
21 /**
22  * A re-usable dialogue box with Moodle classes applied.
23  *
24  * @param {Object} c Object literal specifying the dialogue configuration properties.
25  * @constructor
26  * @class M.core.dialogue
27  * @extends Panel
28  */
29 DIALOGUE = function(config) {
30     // The code below is a hack to add the custom content node to the DOM, on the fly, per-instantiation and to assign the value
31     // of 'srcNode' to this newly created node. Normally (see docs: https://yuilibrary.com/yui/docs/widget/widget-extend.html),
32     // this node would be pre-existing in the DOM, and an id string would simply be passed in as a property of the config object
33     // during widget instantiation, however, because we're creating it on the fly (and 'config.srcNode' isn't set yet), care must
34     // be taken to add it to the DOM and to properly set the value of 'config.srcNode' before calling the parent constructor.
35     // Note: additional classes can be added to this content node by setting the 'additionalBaseClass' config property (a string).
36     var id = 'moodle-dialogue-' + Y.stamp(this); // Can't use this.get('id') as it's not set at this stage.
37     config.notificationBase =
38         Y.Node.create('<div class="' + CSS.BASE + '">')
39               .append(Y.Node.create('<div id="' + id + '" role="dialog" ' +
40                                     'aria-labelledby="' + id + '-header-text" class="' + CSS.WRAP + '"  aria-live="polite"></div>')
41               .append(Y.Node.create('<div id="' + id + '-header-text" class="' + CSS.HEADER + ' yui3-widget-hd"></div>'))
42               .append(Y.Node.create('<div class="' + CSS.BODY + ' yui3-widget-bd"></div>'))
43               .append(Y.Node.create('<div class="' + CSS.FOOTER + ' yui3-widget-ft"></div>')));
44     Y.one(document.body).append(config.notificationBase);
45     config.srcNode = '#' + id;
46     delete config.buttons; // Don't let anyone pass in buttons as we want to control these during init. addButton can be used later.
47     DIALOGUE.superclass.constructor.apply(this, [config]);
48 };
49 Y.extend(DIALOGUE, Y.Panel, {
50     // Window resize event listener.
51     _resizeevent: null,
52     // Orientation change event listener.
53     _orientationevent: null,
54     _calculatedzindex: false,
55     // Current maskNode id
56     _currentMaskNodeId: null,
57     /**
58      * The original position of the dialogue before it was reposition to
59      * avoid browser jumping.
60      *
61      * @property _originalPosition
62      * @protected
63      * @type Array
64      */
65     _originalPosition: null,
67     /**
68      * The list of elements that have been aria hidden when displaying
69      * this dialogue.
70      *
71      * @property _hiddenSiblings
72      * @protected
73      * @type Array
74      */
75     _hiddenSiblings: null,
77     /**
78      * Hide the modal only if it doesn't contain a form.
79      *
80      * @method hideIfNotForm
81      */
82     hideIfNotForm: function() {
83         var bb = this.get('boundingBox'),
84             formElement = bb.one(FORM_SELECTOR);
86         if (formElement === null) {
87             this.hide();
88         }
89     },
91     /**
92      * Initialise the dialogue.
93      *
94      * @method initializer
95      */
96     initializer: function() {
97         var bb;
99         if (this.get('closeButton') !== false) {
100             // The buttons constructor does not allow custom attributes
101             this.get('buttons').header[0].setAttribute('title', this.get('closeButtonTitle'));
102         }
104         // Initialise the element cache.
105         this._hiddenSiblings = [];
107         if (this.get('render')) {
108             this.render();
109         }
110         this.after('visibleChange', this.visibilityChanged, this);
111         if (this.get('center')) {
112             this.centerDialogue();
113         }
115         if (this.get('modal')) {
116             // If we're a modal then make sure our container is ARIA
117             // hidden by default. ARIA visibility is managed for modal dialogues.
118             this.get(BASE).set('aria-hidden', 'true');
119             this.plug(Y.M.core.LockScroll);
120         }
122         // Workaround upstream YUI bug http://yuilibrary.com/projects/yui3/ticket/2532507
123         // and allow setting of z-index in theme.
124         bb = this.get('boundingBox');
125         bb.addClass(HAS_ZINDEX);
127         // Add any additional classes that were specified.
128         Y.Array.each(this.get('extraClasses'), bb.addClass, bb);
130         if (this.get('visible')) {
131             this.applyZIndex();
132         }
133         // Recalculate the zIndex every time the modal is altered.
134         this.on('maskShow', this.applyZIndex);
136         this.on('maskShow', function() {
137             // When the mask shows, position the boundingBox at the top-left of the window such that when it is
138             // focused, the position does not change.
139             var w = Y.one(Y.config.win),
140                 bb = this.get('boundingBox');
142             if (!this.get('center')) {
143                 this._originalPosition = bb.getXY();
144             }
146             // Check if maskNode already init click event.
147             var maskNode = this.get('maskNode');
148             if (this._currentMaskNodeId !== maskNode.get('_yuid')) {
149                 this._currentMaskNodeId = maskNode.get('_yuid');
150                 maskNode.on('click', this.hideIfNotForm, this);
151             }
153             if (bb.getStyle('position') !== 'fixed') {
154                 // If the boundingBox has been positioned in a fixed manner, then it will not position correctly to scrollTop.
155                 bb.setStyles({
156                     top: w.get('scrollTop'),
157                     left: w.get('scrollLeft')
158                 });
159             }
160         }, this);
162         // Add any additional classes to the content node if required.
163         var nBase = this.get('notificationBase');
164         var additionalClasses = this.get('additionalBaseClass');
165         if (additionalClasses !== '') {
166             nBase.addClass(additionalClasses);
167         }
169         // Remove the dialogue from the DOM when it is destroyed.
170         this.after('destroyedChange', function() {
171             this.get(BASE).remove(true);
172         }, this);
173     },
175     /**
176      * Either set the zindex to the supplied value, or set it to one more than the highest existing
177      * dialog in the page.
178      *
179      * @method applyZIndex
180      */
181     applyZIndex: function() {
182         var highestzindex = 1,
183             zindexvalue = 1,
184             bb = this.get('boundingBox'),
185             ol = this.get('maskNode'),
186             zindex = this.get('zIndex');
187         if (zindex !== 0 && !this._calculatedzindex) {
188             // The zindex was specified so we should use that.
189             bb.setStyle('zIndex', zindex);
190         } else {
191             // Determine the correct zindex by looking at all existing dialogs and menubars in the page.
192             Y.all(DIALOGUE_SELECTOR + ', ' + MENUBAR_SELECTOR + ', ' + DOT + HAS_ZINDEX).each(function(node) {
193                 var zindex = this.findZIndex(node);
194                 if (zindex > highestzindex) {
195                     highestzindex = zindex;
196                 }
197             }, this);
198             // Only set the zindex if we found a wrapper.
199             zindexvalue = (highestzindex + 1).toString();
200             bb.setStyle('zIndex', zindexvalue);
201             this.set('zIndex', zindexvalue);
202             if (this.get('modal')) {
203                 ol.setStyle('zIndex', zindexvalue);
205                 // In IE8, the z-indexes do not take effect properly unless you toggle
206                 // the lightbox from 'fixed' to 'static' and back. This code does so
207                 // using the minimum setTimeouts that still actually work.
208                 if (Y.UA.ie && Y.UA.compareVersions(Y.UA.ie, 9) < 0) {
209                     setTimeout(function() {
210                         ol.setStyle('position', 'static');
211                         setTimeout(function() {
212                             ol.setStyle('position', 'fixed');
213                         }, 0);
214                     }, 0);
215                 }
216             }
217             this._calculatedzindex = true;
218         }
219     },
221     /**
222      * Finds the zIndex of the given node or its parent.
223      *
224      * @method findZIndex
225      * @param {Node} node The Node to apply the zIndex to.
226      * @return {Number} Either the zIndex, or 0 if one was not found.
227      */
228     findZIndex: function(node) {
229         // In most cases the zindex is set on the parent of the dialog.
230         var zindex = node.getStyle('zIndex') || node.ancestor().getStyle('zIndex');
231         if (zindex) {
232             return parseInt(zindex, 10);
233         }
234         return 0;
235     },
237     /**
238      * Event listener for the visibility changed event.
239      *
240      * @method visibilityChanged
241      * @param {EventFacade} e
242      */
243     visibilityChanged: function(e) {
244         var titlebar, bb;
245         if (e.attrName === 'visible') {
246             this.get('maskNode').addClass(CSS.LIGHTBOX);
247             // Going from visible to hidden.
248             if (e.prevVal && !e.newVal) {
249                 bb = this.get('boundingBox');
250                 if (this._resizeevent) {
251                     this._resizeevent.detach();
252                     this._resizeevent = null;
253                 }
254                 if (this._orientationevent) {
255                     this._orientationevent.detach();
256                     this._orientationevent = null;
257                 }
258                 bb.detach('key', this.keyDelegation);
260                 if (this.get('modal')) {
261                     // Hide this dialogue from screen readers.
262                     this.setAccessibilityHidden();
263                 }
264             }
265             // Going from hidden to visible.
266             if (!e.prevVal && e.newVal) {
267                 // This needs to be done each time the dialog is shown as new dialogs may have been opened.
268                 this.applyZIndex();
269                 // This needs to be done each time the dialog is shown as the window may have been resized.
270                 this.makeResponsive();
271                 if (!this.shouldResizeFullscreen()) {
272                     if (this.get('draggable')) {
273                         titlebar = '#' + this.get('id') + ' .' + CSS.HEADER;
274                         this.plug(Y.Plugin.Drag, {handles: [titlebar]});
275                         Y.one(titlebar).setStyle('cursor', 'move');
276                     }
277                 }
278                 this.keyDelegation();
280                 // Only do accessibility hiding for modals because the ARIA spec
281                 // says that all ARIA dialogues should be modal.
282                 if (this.get('modal')) {
283                     // Make this dialogue visible to screen readers.
284                     this.setAccessibilityVisible();
285                 }
286             }
287             if (this.get('center') && !e.prevVal && e.newVal) {
288                 this.centerDialogue();
289             }
290         }
291     },
292     /**
293      * If the responsive attribute is set on the dialog, and the window size is
294      * smaller than the responsive width - make the dialog fullscreen.
295      *
296      * @method makeResponsive
297      */
298     makeResponsive: function() {
299         var bb = this.get('boundingBox');
301         if (this.shouldResizeFullscreen()) {
302             // Make this dialogue fullscreen on a small screen.
303             // Disable the page scrollbars.
305             // Size and position the fullscreen dialog.
307             bb.addClass(DIALOGUE_FULLSCREEN_CLASS);
308             bb.setStyles({'left': null,
309                           'top': null,
310                           'width': null,
311                           'height': null,
312                           'right': null,
313                           'bottom': null});
314         } else {
315             if (this.get('responsive')) {
316                 // We must reset any of the fullscreen changes.
317                 bb.removeClass(DIALOGUE_FULLSCREEN_CLASS)
318                     .setStyles({'width': this.get('width'),
319                                 'height': this.get('height')});
320             }
321         }
323         // Update Lock scroll if the plugin is present.
324         if (this.lockScroll) {
325             this.lockScroll.updateScrollLock(this.shouldResizeFullscreen());
326         }
327     },
328     /**
329      * Center the dialog on the screen.
330      *
331      * @method centerDialogue
332      */
333     centerDialogue: function() {
334         var bb = this.get('boundingBox'),
335             hidden = bb.hasClass(DIALOGUE_HIDDEN_CLASS),
336             x,
337             y;
339         // Don't adjust the position if we are in full screen mode.
340         if (this.shouldResizeFullscreen()) {
341             return;
342         }
343         if (hidden) {
344             bb.setStyle('top', '-1000px').removeClass(DIALOGUE_HIDDEN_CLASS);
345         }
346         x = Math.max(Math.round((bb.get('winWidth') - bb.get('offsetWidth')) / 2), 15);
347         y = Math.max(Math.round((bb.get('winHeight') - bb.get('offsetHeight')) / 2), 15) + Y.one(window).get('scrollTop');
348         bb.setStyles({'left': x, 'top': y});
350         if (hidden) {
351             bb.addClass(DIALOGUE_HIDDEN_CLASS);
352         }
353         this.makeResponsive();
354     },
355     /**
356      * Return whether this dialogue should be fullscreen or not.
357      *
358      * Responsive attribute must be true and we should not be in an iframe and the screen width should
359      * be less than the responsive width.
360      *
361      * @method shouldResizeFullscreen
362      * @return {Boolean}
363      */
364     shouldResizeFullscreen: function() {
365         return (window === window.parent) && this.get('responsive') &&
366                Math.floor(Y.one(document.body).get('winWidth')) < this.get('responsiveWidth');
367     },
369     show: function() {
370         var result = null,
371             header = this.headerNode,
372             content = this.bodyNode,
373             focusSelector = this.get('focusOnShowSelector'),
374             focusNode = null;
376         result = DIALOGUE.superclass.show.call(this);
378         if (!this.get('center') && this._originalPosition) {
379             // Restore the dialogue position to it's location before it was moved at show time.
380             this.get('boundingBox').setXY(this._originalPosition);
381         }
383         // Try and find a node to focus on using the focusOnShowSelector attribute.
384         if (focusSelector !== null) {
385             focusNode = this.get('boundingBox').one(focusSelector);
386         }
387         if (!focusNode) {
388             // Fall back to the header or the content if no focus node was found yet.
389             if (header && header !== '') {
390                 focusNode = header;
391             } else if (content && content !== '') {
392                 focusNode = content;
393             }
394         }
395         if (focusNode) {
396             focusNode.focus();
397         }
398         return result;
399     },
401     hide: function(e) {
402         if (e) {
403             // If the event was closed by an escape key event, then we need to check that this
404             // dialogue is currently focused to prevent closing all dialogues in the stack.
405             if (e.type === 'key' && e.keyCode === 27 && !this.get('focused')) {
406                 return;
407             }
408         }
410         // Unlock scroll if the plugin is present.
411         if (this.lockScroll) {
412             this.lockScroll.disableScrollLock();
413         }
415         return DIALOGUE.superclass.hide.call(this, arguments);
416     },
417     /**
418      * Setup key delegation to keep tabbing within the open dialogue.
419      *
420      * @method keyDelegation
421      */
422     keyDelegation: function() {
423         var bb = this.get('boundingBox');
424         bb.delegate('key', function(e) {
425             var target = e.target;
426             var direction = 'forward';
427             if (e.shiftKey) {
428                 direction = 'backward';
429             }
430             if (this.trapFocus(target, direction)) {
431                 e.preventDefault();
432             }
433         }, 'down:9', CAN_RECEIVE_FOCUS_SELECTOR, this);
434     },
436     /**
437      * Trap the tab focus within the open modal.
438      *
439      * @method trapFocus
440      * @param {string} target the element target
441      * @param {string} direction tab key for forward and tab+shift for backward
442      * @return {Boolean} The result of the focus action.
443      */
444     trapFocus: function(target, direction) {
445         var bb = this.get('boundingBox'),
446             firstitem = bb.one(CAN_RECEIVE_FOCUS_SELECTOR),
447             lastitem = bb.all(CAN_RECEIVE_FOCUS_SELECTOR).pop();
449         if (target === lastitem && direction === 'forward') { // Tab key.
450             return firstitem.focus();
451         } else if (target === firstitem && direction === 'backward') {  // Tab+shift key.
452             return lastitem.focus();
453         }
454     },
456     /**
457      * Sets the appropriate aria attributes on this dialogue and the other
458      * elements in the DOM to ensure that screen readers are able to navigate
459      * the dialogue popup correctly.
460      *
461      * @method setAccessibilityVisible
462      */
463     setAccessibilityVisible: function() {
464         // Get the element that contains this dialogue because we need it
465         // to filter out from the document.body child elements.
466         var container = this.get(BASE);
468         // We need to get a list containing each sibling element and the shallowest
469         // non-ancestral nodes in the DOM. We can shortcut this a little by leveraging
470         // the fact that this dialogue is always appended to the document body therefore
471         // it's siblings are the shallowest non-ancestral nodes. If that changes then
472         // this code should also be updated.
473         Y.one(document.body).get('children').each(function(node) {
474             // Skip the element that contains us.
475             if (node !== container) {
476                 var hidden = node.get('aria-hidden');
477                 // If they are already hidden we can ignore them.
478                 if (hidden !== 'true') {
479                     // Save their current state.
480                     node.setData('previous-aria-hidden', hidden);
481                     this._hiddenSiblings.push(node);
483                     // Hide this node from screen readers.
484                     node.set('aria-hidden', 'true');
485                 }
486             }
487         }, this);
489         // Make us visible to screen readers.
490         container.set('aria-hidden', 'false');
491     },
493     /**
494      * Restores the aria visibility on the DOM elements changed when displaying
495      * the dialogue popup and makes the dialogue aria hidden to allow screen
496      * readers to navigate the main page correctly when the dialogue is closed.
497      *
498      * @method setAccessibilityHidden
499      */
500     setAccessibilityHidden: function() {
501         var container = this.get(BASE);
502         container.set('aria-hidden', 'true');
504         // Restore the sibling nodes back to their original values.
505         Y.Array.each(this._hiddenSiblings, function(node) {
506             var previousValue = node.getData('previous-aria-hidden');
507             // If the element didn't previously have an aria-hidden attribute
508             // then we can just remove the one we set.
509             if (previousValue === null) {
510                 node.removeAttribute('aria-hidden');
511             } else {
512                 // Otherwise set it back to the old value (which will be false).
513                 node.set('aria-hidden', previousValue);
514             }
515         });
517         // Clear the cache. No longer need to store these.
518         this._hiddenSiblings = [];
519     }
520 }, {
521     NAME: DIALOGUE_NAME,
522     CSS_PREFIX: DIALOGUE_PREFIX,
523     ATTRS: {
524         /**
525          * Any additional classes to add to the base Node.
526          *
527          * @attribute additionalBaseClass
528          * @type String
529          * @default ''
530          */
531         additionalBaseClass: {
532             value: ''
533         },
535         /**
536          * The Notification base Node.
537          *
538          * @attribute notificationBase
539          * @type Node
540          */
541         notificationBase: {
543         },
545         /**
546          * Whether to display the dialogue modally and with a
547          * lightbox style.
548          *
549          * @attribute lightbox
550          * @type Boolean
551          * @default true
552          * @deprecated Since Moodle 2.7. Please use modal instead.
553          */
554         lightbox: {
555             lazyAdd: false,
556             setter: function(value) {
557                 Y.log("The lightbox attribute of M.core.dialogue has been deprecated since Moodle 2.7, " +
558                       "please use the modal attribute instead",
559                     'warn', 'moodle-core-notification-dialogue');
560                 this.set('modal', value);
561             }
562         },
564         /**
565          * Whether to display a close button on the dialogue.
566          *
567          * Note, we do not recommend hiding the close button as this has
568          * potential accessibility concerns.
569          *
570          * @attribute closeButton
571          * @type Boolean
572          * @default true
573          */
574         closeButton: {
575             validator: Y.Lang.isBoolean,
576             value: true
577         },
579         /**
580          * The title for the close button if one is to be shown.
581          *
582          * @attribute closeButtonTitle
583          * @type String
584          * @default 'Close'
585          */
586         closeButtonTitle: {
587             validator: Y.Lang.isString,
588             value: M.util.get_string('closebuttontitle', 'moodle')
589         },
591         /**
592          * Whether to display the dialogue centrally on the screen.
593          *
594          * @attribute center
595          * @type Boolean
596          * @default true
597          */
598         center: {
599             validator: Y.Lang.isBoolean,
600             value: true
601         },
603         /**
604          * Whether to make the dialogue movable around the page.
605          *
606          * @attribute draggable
607          * @type Boolean
608          * @default false
609          */
610         draggable: {
611             validator: Y.Lang.isBoolean,
612             value: false
613         },
615         /**
616          * Used to generate a unique id for the dialogue.
617          *
618          * @attribute COUNT
619          * @type String
620          * @default null
621          * @writeonce
622          */
623         COUNT: {
624             writeOnce: true,
625             valueFn: function() {
626                 return Y.stamp(this);
627             }
628         },
630         /**
631          * Used to disable the fullscreen resizing behaviour if required.
632          *
633          * @attribute responsive
634          * @type Boolean
635          * @default true
636          */
637         responsive: {
638             validator: Y.Lang.isBoolean,
639             value: true
640         },
642         /**
643          * The width that this dialogue should be resized to fullscreen.
644          *
645          * @attribute responsiveWidth
646          * @type Number
647          * @default 768
648          */
649         responsiveWidth: {
650             value: 768
651         },
653         /**
654          * Selector to a node that should recieve focus when this dialogue is shown.
655          *
656          * The default behaviour is to focus on the header.
657          *
658          * @attribute focusOnShowSelector
659          * @default null
660          * @type String
661          */
662         focusOnShowSelector: {
663             value: null
664         }
665     }
666 });
668 Y.Base.modifyAttrs(DIALOGUE, {
669     /**
670      * String with units, or number, representing the width of the Widget.
671      * If a number is provided, the default unit, defined by the Widgets
672      * DEF_UNIT, property is used.
673      *
674      * If a value of 'auto' is used, then an empty String is instead
675      * returned.
676      *
677      * @attribute width
678      * @default '400px'
679      * @type {String|Number}
680      */
681     width: {
682         value: '400px',
683         setter: function(value) {
684             if (value === 'auto') {
685                 return '';
686             }
687             return value;
688         }
689     },
691     /**
692      * Boolean indicating whether or not the Widget is visible.
693      *
694      * We override this from the default Widget attribute value.
695      *
696      * @attribute visible
697      * @default false
698      * @type Boolean
699      */
700     visible: {
701         value: false
702     },
704     /**
705      * A convenience Attribute, which can be used as a shortcut for the
706      * `align` Attribute.
707      *
708      * Note: We override this in Moodle such that it sets a value for the
709      * `center` attribute if set. The `centered` will always return false.
710      *
711      * @attribute centered
712      * @type Boolean|Node
713      * @default false
714      */
715     centered: {
716         setter: function(value) {
717             if (value) {
718                 this.set('center', true);
719             }
720             return false;
721         }
722     },
724     /**
725      * Boolean determining whether to render the widget during initialisation.
726      *
727      * We override this to change the default from false to true for the dialogue.
728      * We then proceed to early render the dialogue during our initialisation rather than waiting
729      * for YUI to render it after that.
730      *
731      * @attribute render
732      * @type Boolean
733      * @default true
734      */
735     render: {
736         value: true,
737         writeOnce: true
738     },
740     /**
741      * Any additional classes to add to the boundingBox.
742      *
743      * @attribute extraClasses
744      * @type Array
745      * @default []
746      */
747     extraClasses: {
748         value: []
749     },
751     /**
752      * Identifier for the widget.
753      *
754      * @attribute id
755      * @type String
756      * @default a product of guid().
757      * @writeOnce
758      */
759     id: {
760         writeOnce: true,
761         valueFn: function() {
762             var id = 'moodle-dialogue-' + Y.stamp(this);
763             return id;
764         }
765     },
767     /**
768      * Collection containing the widget's buttons.
769      *
770      * @attribute buttons
771      * @type Object
772      * @default {}
773      */
774     buttons: {
775         getter: Y.WidgetButtons.prototype._getButtons,
776         setter: Y.WidgetButtons.prototype._setButtons,
777         valueFn: function() {
778             if (this.get('closeButton') === false) {
779                 return null;
780             } else {
781                 return [
782                     {
783                         section: Y.WidgetStdMod.HEADER,
784                         classNames: 'closebutton',
785                         action: function() {
786                             this.hide();
787                         }
788                     }
789                 ];
790             }
791         }
792     }
793 });
795 Y.Base.mix(DIALOGUE, [Y.M.core.WidgetFocusAfterHide]);
797 M.core.dialogue = DIALOGUE;