MDL-54708 message: add notification popover to nav bar
[moodle.git] / lib / amd / src / mdl_popover_controller.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  * Controls the mdl popover element.
18  *
19  * See template: core/mdl_popover
20  *
21  * @module     core/mdl_popover_controller
22  * @class      mdl_popover_controller
23  * @package    core
24  * @copyright  2015 Ryan Wyllie <ryan@moodle.com>
25  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
26  * @since      3.2
27  */
28 define(['jquery', 'core/str', 'core/custom_interaction_events'],
29         function($, str, customEvents) {
31     var SELECTORS = {
32         CONTENT: '.mdl-popover-content',
33         CONTENT_CONTAINER: '.mdl-popover-content-container',
34         MENU_CONTAINER: '.mdl-popover-container',
35         MENU_TOGGLE: '.mdl-popover-toggle',
36     };
38     /**
39      * Constructor for the MdlPopoverController.
40      *
41      * @param element jQuery object root element of the popover
42      * @return object MdlPopoverController
43      */
44     var MdlPopoverController = function(element) {
45         this.root = $(element);
46         this.content = this.root.find(SELECTORS.CONTENT);
47         this.contentContainer = this.root.find(SELECTORS.CONTENT_CONTAINER);
48         this.menuContainer = this.root.find(SELECTORS.MENU_CONTAINER);
49         this.menuToggle = this.root.find(SELECTORS.MENU_TOGGLE);
50         this.isLoading = false;
51     };
53     /**
54      * The collection of events triggered by this controller.
55      */
56     MdlPopoverController.prototype.events = function() {
57         return {
58             menuOpened: 'mdlpopover:menuopened',
59             menuClosed: 'mdlpopover:menuclosed',
60             startLoading: 'mdlpopover:startLoading',
61             stopLoading: 'mdlpopover:stopLoading',
62         };
63     };
65     /**
66      * Return the container element for the content element.
67      *
68      * @method getContentContainer
69      * @return jQuery object
70      */
71     MdlPopoverController.prototype.getContentContainer = function() {
72         return this.contentContainer;
73     };
75     /**
76      * Return the content element.
77      *
78      * @method getContent
79      * @return jQuery object
80      */
81     MdlPopoverController.prototype.getContent = function() {
82         return this.content;
83     };
85     /**
86      * Checks if the popover is displayed.
87      *
88      * @method isMenuOpen
89      * @return bool
90      */
91     MdlPopoverController.prototype.isMenuOpen = function() {
92         return !this.root.hasClass('collapsed');
93     };
95     /**
96      * Toggle the visibility of the popover.
97      *
98      * @method toggleMenu
99      */
100     MdlPopoverController.prototype.toggleMenu = function() {
101         if (this.isMenuOpen()) {
102             this.closeMenu();
103         } else {
104             this.openMenu();
105         }
106     };
108     /**
109      * Hide the popover.
110      *
111      * Note: This triggers the menuClosed event.
112      *
113      * @method closeMenu
114      */
115     MdlPopoverController.prototype.closeMenu = function() {
116         // We're already closed.
117         if (!this.isMenuOpen()) {
118             return;
119         }
121         this.root.addClass('collapsed');
122         this.menuContainer.attr('aria-expanded', 'false');
123         this.menuContainer.attr('aria-hidden', 'true');
124         this.updateButtonAriaLabel();
125         this.root.trigger(this.events().menuClosed);
126     };
128     /**
129      * Show the popover.
130      *
131      * Note: This triggers the menuOpened event.
132      *
133      * @method openMenu
134      */
135     MdlPopoverController.prototype.openMenu = function() {
136         // We're already open.
137         if (this.isMenuOpen()) {
138             return;
139         }
141         this.root.removeClass('collapsed');
142         this.menuContainer.attr('aria-expanded', 'true');
143         this.menuContainer.attr('aria-hidden', 'false');
144         this.updateButtonAriaLabel();
145         this.root.trigger(this.events().menuOpened);
146     };
148     /**
149      * Set the appropriate aria label on the popover toggle.
150      *
151      * @method updateButtonAriaLabel
152      */
153     MdlPopoverController.prototype.updateButtonAriaLabel = function() {
154         if (this.isMenuOpen()) {
155             str.get_string('hidepopoverwindow').done(function(string) {
156                 this.menuToggle.attr('aria-label', string);
157             }.bind(this));
158         } else {
159             str.get_string('showpopoverwindow').done(function(string) {
160                 this.menuToggle.attr('aria-label', string);
161             }.bind(this));
162         }
163     };
165     /**
166      * Set the loading state on this popover.
167      *
168      * Note: This triggers the startLoading event.
169      *
170      * @method startLoading
171      */
172     MdlPopoverController.prototype.startLoading = function() {
173         this.isLoading = true;
174         this.getContentContainer().addClass('loading');
175         this.getContentContainer().attr('aria-busy', 'true');
176         this.root.trigger(this.events().startLoading);
177     };
179     /**
180      * Undo the loading state on this popover.
181      *
182      * Note: This triggers the stopLoading event.
183      *
184      * @method stopLoading
185      */
186     MdlPopoverController.prototype.stopLoading = function() {
187         this.isLoading = false;
188         this.getContentContainer().removeClass('loading');
189         this.getContentContainer().attr('aria-busy', 'false');
190         this.root.trigger(this.events().stopLoading);
191     };
193     /**
194      * Sets the focus on the menu toggle.
195      *
196      * @method focusMenuToggle
197      */
198     MdlPopoverController.prototype.focusMenuToggle = function() {
199         this.menuToggle.focus();
200     };
202     /**
203      * Return the currently focused content item.
204      *
205      * @method getContentItemWithFocus
206      * @return jQuery object
207      */
208     MdlPopoverController.prototype.getContentItemWithFocus = function() {
209         var currentFocus = $(document.activeElement);
210         var items = this.getContent().children();
211         var currentItem = items.filter(currentFocus);
213         if (!currentItem.length) {
214             currentItem = items.has(currentFocus);
215         }
217         return currentItem;
218     };
220     /**
221      * Set focus on the first content item in the list.
222      *
223      * @method focusFirstContentItem
224      */
225     MdlPopoverController.prototype.focusFirstContentItem = function() {
226         this.getContent().children().first().focus();
227     };
229     /**
230      * Set focus on the last content item in the list.
231      *
232      * @method focusLastContentItem
233      */
234     MdlPopoverController.prototype.focusLastContentItem = function() {
235         this.getContent().children().last().focus();
236     };
238     /**
239      * Set focus on the content item after the item that currently has focus
240      * in the list.
241      *
242      * @method focusNextContentItem
243      */
244     MdlPopoverController.prototype.focusNextContentItem = function() {
245         var currentItem = this.getContentItemWithFocus();
247         if (currentItem.length && currentItem.next()) {
248             currentItem.next().focus();
249         }
250     };
252     /**
253      * Set focus on the content item preceding the item that currently has focus
254      * in the list.
255      *
256      * @method focusPreviousContentItem
257      */
258     MdlPopoverController.prototype.focusPreviousContentItem = function() {
259         var currentItem = this.getContentItemWithFocus();
261         if (currentItem.length && currentItem.prev()) {
262             currentItem.prev().focus();
263         }
264     };
266     /**
267      * Register the minimal amount of listeners for the popover to function.
268      *
269      * @method registerBaseEventListeners
270      */
271     MdlPopoverController.prototype.registerBaseEventListeners = function() {
272         customEvents.define(this.root, [
273             customEvents.events.activate,
274             customEvents.events.escape,
275         ]);
277         // Toggle the popover visibility on activation (click/enter/space) of the toggle button.
278         this.root.on(customEvents.events.activate, SELECTORS.MENU_TOGGLE, function() {
279             this.toggleMenu();
280         }.bind(this));
282         // Close the popover if escape is pressed.
283         this.root.on(customEvents.events.escape, function() {
284             this.closeMenu();
285             this.focusMenuToggle();
286         }.bind(this));
288         // Close the popover if any other part of the page is clicked.
289         $('html').click(function(e) {
290             var target = $(e.target);
291             if (!this.root.is(target) && !this.root.has(target).length) {
292                 this.closeMenu();
293             }
294         }.bind(this));
296         customEvents.define(this.getContentContainer(), [
297             customEvents.events.scrollBottom
298         ]);
299     };
301     /**
302      * Set up the event listeners for keyboard navigating a list of content items.
303      *
304      * @method registerListNavigationEventListeners
305      */
306     MdlPopoverController.prototype.registerListNavigationEventListeners = function() {
307         customEvents.define(this.root, [
308             customEvents.events.down,
309             customEvents.events.up,
310             customEvents.events.home,
311             customEvents.events.end,
312         ]);
314         // If the down arrow is pressed then open the menu and focus the first content
315         // item or focus the next content item if the menu is open.
316         this.root.on(customEvents.events.down, function() {
317             if (!this.isMenuOpen()) {
318                 this.openMenu();
319                 this.focusFirstContentItem();
320             } else {
321                 this.focusNextContentItem();
322             }
323         }.bind(this));
325         // Shift focus to the previous content item if the up key is pressed.
326         this.root.on(customEvents.events.up, function() {
327             this.focusPreviousContentItem();
328         }.bind(this));
330         // Jump focus to the first content item if the home key is pressed.
331         this.root.on(customEvents.events.home, function() {
332             this.focusFirstContentItem();
333         }.bind(this));
335         // Jump focus to the last content item if the end key is pressed.
336         this.root.on(customEvents.events.end, function() {
337             this.focusLastContentItem();
338         }.bind(this));
339     };
341     return MdlPopoverController;
342 });