moodle/lib/amd/src/popover_region_controller.js

// This file is part of Moodle - http://moodle.org/
//
// Moodle is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// Moodle is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.

/**
 * Controls the popover region element.
 *
 * See template: core/popover_region
 *
 * @module     core/popover_region_controller
 * @class      popover_region_controller
 * @package    core
 * @copyright  2015 Ryan Wyllie <ryan@moodle.com>
 * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 * @since      3.2
 */
define(['jquery', 'core/str', 'core/custom_interaction_events'],
        function($, str, customEvents) {

    var SELECTORS = {
        CONTENT: '.popover-region-content',
        CONTENT_CONTAINER: '.popover-region-content-container',
        MENU_CONTAINER: '.popover-region-container',
        MENU_TOGGLE: '.popover-region-toggle',
        CAN_RECEIVE_FOCUS: 'input:not([type="hidden"]), a[href], button, textarea, select, [tabindex]',
    };

    /**
     * Constructor for the PopoverRegionController.
     *
     * @param {jQuery} element object root element of the popover
     */
    var PopoverRegionController = function(element) {
        this.root = $(element);
        this.content = this.root.find(SELECTORS.CONTENT);
        this.contentContainer = this.root.find(SELECTORS.CONTENT_CONTAINER);
        this.menuContainer = this.root.find(SELECTORS.MENU_CONTAINER);
        this.menuToggle = this.root.find(SELECTORS.MENU_TOGGLE);
        this.isLoading = false;
        this.promises = {
            closeHandlers: $.Deferred(),
            navigationHandlers: $.Deferred(),
        };

        // Core event listeners to open and close.
        this.registerBaseEventListeners();
    };

    /**
     * The collection of events triggered by this controller.
     *
     * @returns {object}
     */
    PopoverRegionController.prototype.events = function() {
        return {
            menuOpened: 'popoverregion:menuopened',
            menuClosed: 'popoverregion:menuclosed',
            startLoading: 'popoverregion:startLoading',
            stopLoading: 'popoverregion:stopLoading',
        };
    };

    /**
     * Return the container element for the content element.
     *
     * @method getContentContainer
     * @return {jQuery} object
     */
    PopoverRegionController.prototype.getContentContainer = function() {
        return this.contentContainer;
    };

    /**
     * Return the content element.
     *
     * @method getContent
     * @return {jQuery} object
     */
    PopoverRegionController.prototype.getContent = function() {
        return this.content;
    };

    /**
     * Checks if the popover is displayed.
     *
     * @method isMenuOpen
     * @return {bool}
     */
    PopoverRegionController.prototype.isMenuOpen = function() {
        return !this.root.hasClass('collapsed');
    };

    /**
     * Toggle the visibility of the popover.
     *
     * @method toggleMenu
     */
    PopoverRegionController.prototype.toggleMenu = function() {
        if (this.isMenuOpen()) {
            this.closeMenu();
        } else {
            this.openMenu();
        }
    };

    /**
     * Hide the popover.
     *
     * Note: This triggers the menuClosed event.
     *
     * @method closeMenu
     */
    PopoverRegionController.prototype.closeMenu = function() {
        // We're already closed.
        if (!this.isMenuOpen()) {
            return;
        }

        this.root.addClass('collapsed');
        this.menuContainer.attr('aria-expanded', 'false');
        this.menuContainer.attr('aria-hidden', 'true');
        this.updateButtonAriaLabel();
        this.root.trigger(this.events().menuClosed);
    };

    /**
     * Show the popover.
     *
     * Note: This triggers the menuOpened event.
     *
     * @method openMenu
     */
    PopoverRegionController.prototype.openMenu = function() {
        // We're already open.
        if (this.isMenuOpen()) {
            return;
        }

        this.root.removeClass('collapsed');
        this.menuContainer.attr('aria-expanded', 'true');
        this.menuContainer.attr('aria-hidden', 'false');
        this.updateButtonAriaLabel();
        // Resolve the promises to allow the handlers to be added
        // to the DOM, if they have been requested.
        this.promises.closeHandlers.resolve();
        this.promises.navigationHandlers.resolve();
        this.root.trigger(this.events().menuOpened);
    };

    /**
     * Set the appropriate aria label on the popover toggle.
     *
     * @method updateButtonAriaLabel
     */
    PopoverRegionController.prototype.updateButtonAriaLabel = function() {
        if (this.isMenuOpen()) {
            str.get_string('hidepopoverwindow').done(function(string) {
                this.menuToggle.attr('aria-label', string);
            }.bind(this));
        } else {
            str.get_string('showpopoverwindow').done(function(string) {
                this.menuToggle.attr('aria-label', string);
            }.bind(this));
        }
    };

    /**
     * Set the loading state on this popover.
     *
     * Note: This triggers the startLoading event.
     *
     * @method startLoading
     */
    PopoverRegionController.prototype.startLoading = function() {
        this.isLoading = true;
        this.getContentContainer().addClass('loading');
        this.getContentContainer().attr('aria-busy', 'true');
        this.root.trigger(this.events().startLoading);
    };

    /**
     * Undo the loading state on this popover.
     *
     * Note: This triggers the stopLoading event.
     *
     * @method stopLoading
     */
    PopoverRegionController.prototype.stopLoading = function() {
        this.isLoading = false;
        this.getContentContainer().removeClass('loading');
        this.getContentContainer().attr('aria-busy', 'false');
        this.root.trigger(this.events().stopLoading);
    };

    /**
     * Sets the focus on the menu toggle.
     *
     * @method focusMenuToggle
     */
    PopoverRegionController.prototype.focusMenuToggle = function() {
        this.menuToggle.focus();
    };

    /**
     * Check if a content item has focus.
     *
     * @method contentItemHasFocus
     * @return {bool}
     */
    PopoverRegionController.prototype.contentItemHasFocus = function() {
        return this.getContentItemWithFocus().length > 0;
    };

    /**
     * Return the currently focused content item.
     *
     * @method getContentItemWithFocus
     * @return {jQuery} object
     */
    PopoverRegionController.prototype.getContentItemWithFocus = function() {
        var currentFocus = $(document.activeElement);
        var items = this.getContent().children();
        var currentItem = items.filter(currentFocus);

        if (!currentItem.length) {
            currentItem = items.has(currentFocus);
        }

        return currentItem;
    };

    /**
     * Focus the given content item or the first focusable element within
     * the content item.
     *
     * @method focusContentItem
     * @param {object} item The content item jQuery element
     */
    PopoverRegionController.prototype.focusContentItem = function(item) {
        if (item.is(SELECTORS.CAN_RECEIVE_FOCUS)) {
            item.focus();
        } else {
            item.find(SELECTORS.CAN_RECEIVE_FOCUS).first().focus();
        }
    };

    /**
     * Set focus on the first content item in the list.
     *
     * @method focusFirstContentItem
     */
    PopoverRegionController.prototype.focusFirstContentItem = function() {
        this.focusContentItem(this.getContent().children().first());
    };

    /**
     * Set focus on the last content item in the list.
     *
     * @method focusLastContentItem
     */
    PopoverRegionController.prototype.focusLastContentItem = function() {
        this.focusContentItem(this.getContent().children().last());
    };

    /**
     * Set focus on the content item after the item that currently has focus
     * in the list.
     *
     * @method focusNextContentItem
     */
    PopoverRegionController.prototype.focusNextContentItem = function() {
        var currentItem = this.getContentItemWithFocus();

        if (currentItem.length && currentItem.next()) {
            this.focusContentItem(currentItem.next());
        }
    };

    /**
     * Set focus on the content item preceding the item that currently has focus
     * in the list.
     *
     * @method focusPreviousContentItem
     */
    PopoverRegionController.prototype.focusPreviousContentItem = function() {
        var currentItem = this.getContentItemWithFocus();

        if (currentItem.length && currentItem.prev()) {
            this.focusContentItem(currentItem.prev());
        }
    };

    /**
     * Register the minimal amount of listeners for the popover to function.
     *
     * @method registerBaseEventListeners
     */
    PopoverRegionController.prototype.registerBaseEventListeners = function() {
        customEvents.define(this.root, [
            customEvents.events.activate,
            customEvents.events.escape,
        ]);

        // Toggle the popover visibility on activation (click/enter/space) of the toggle button.
        this.root.on(customEvents.events.activate, SELECTORS.MENU_TOGGLE, function() {
            this.toggleMenu();
        }.bind(this));

        // Delay the binding of these handlers until the region has been opened.
        this.promises.closeHandlers.done(function() {
            // Close the popover if escape is pressed.
            this.root.on(customEvents.events.escape, function() {
                this.closeMenu();
                this.focusMenuToggle();
            }.bind(this));

            // Close the popover if any other part of the page is clicked.
            $('html').click(function(e) {
                var target = $(e.target);
                if (!this.root.is(target) && !this.root.has(target).length) {
                    this.closeMenu();
                }
            }.bind(this));

            customEvents.define(this.getContentContainer(), [
                customEvents.events.scrollBottom
            ]);
        }.bind(this));
    };

    /**
     * Set up the event listeners for keyboard navigating a list of content items.
     *
     * @method registerListNavigationEventListeners
     */
    PopoverRegionController.prototype.registerListNavigationEventListeners = function() {
        customEvents.define(this.root, [
            customEvents.events.down
        ]);

        // If the down arrow is pressed then open the menu and focus the first content
        // item or focus the next content item if the menu is open.
        this.root.on(customEvents.events.down, function(e, data) {
            if (!this.isMenuOpen()) {
                this.openMenu();
                this.focusFirstContentItem();
            } else {
                if (this.contentItemHasFocus()) {
                    this.focusNextContentItem();
                } else {
                    this.focusFirstContentItem();
                }
            }

            data.originalEvent.preventDefault();
        }.bind(this));

        // Delay the binding of these handlers until the region has been opened.
        this.promises.navigationHandlers.done(function() {
            customEvents.define(this.root, [
                customEvents.events.up,
                customEvents.events.home,
                customEvents.events.end,
            ]);

            // Shift focus to the previous content item if the up key is pressed.
            this.root.on(customEvents.events.up, function(e, data) {
                this.focusPreviousContentItem();
                data.originalEvent.preventDefault();
            }.bind(this));

            // Jump focus to the first content item if the home key is pressed.
            this.root.on(customEvents.events.home, function(e, data) {
                this.focusFirstContentItem();
                data.originalEvent.preventDefault();
            }.bind(this));

            // Jump focus to the last content item if the end key is pressed.
            this.root.on(customEvents.events.end, function(e, data) {
                this.focusLastContentItem();
                data.originalEvent.preventDefault();
            }.bind(this));
        }.bind(this));
    };

    return PopoverRegionController;
});