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/>.
  15
  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) {
  30
  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     };
  37
  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     };
  52
  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     };
  64
  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     };
  74
  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     };
  84
  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     };
  94
  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     };
 107
 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         }
 120
 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     };
 127
 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         }
 140
 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     };
 147
 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     };
 164
 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     };
 178
 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     };
 192
 193     /**
 194      * Sets the focus on the menu toggle.
 195      *
 196      * @method focusMenuToggle
 197      */
 198     MdlPopoverController.prototype.focusMenuToggle = function() {
 199         this.menuToggle.focus();
 200     };
 201
 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);
 212
 213         if (!currentItem.length) {
 214             currentItem = items.has(currentFocus);
 215         }
 216
 217         return currentItem;
 218     };
 219
 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     };
 228
 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     };
 237
 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();
 246
 247         if (currentItem.length && currentItem.next()) {
 248             currentItem.next().focus();
 249         }
 250     };
 251
 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();
 260
 261         if (currentItem.length && currentItem.prev()) {
 262             currentItem.prev().focus();
 263         }
 264     };
 265
 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         ]);
 276
 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));
 281
 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));
 287
 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));
 295
 296         customEvents.define(this.getContentContainer(), [
 297             customEvents.events.scrollBottom
 298         ]);
 299     };
 300
 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         ]);
 313
 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));
 324
 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));
 329
 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));
 334
 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     };
 340
 341     return MdlPopoverController;
 342 });