Proyectos de Subversion Moodle

// 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/>.

/**

 * A type of dialogue used as for choosing options.

 *

 * @module     core_course/local/activitychooser/dialogue

 * @copyright  2019 Mihail Geshoski <mihail@moodle.com>

 * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later

 */

import $ from 'jquery';

import * as ModalEvents from 'core/modal_events';

import selectors from 'core_course/local/activitychooser/selectors';

import * as Templates from 'core/templates';

import {end, arrowLeft, arrowRight, home, enter, space} from 'core/key_codes';

import {addIconToContainer} from 'core/loadingicon';

import * as Repository from 'core_course/local/activitychooser/repository';

import Notification from 'core/notification';

import {debounce} from 'core/utils';

const getPlugin = pluginName => import(pluginName);

/**

 * Given an event from the main module 'page' navigate to it's help section via a carousel.

 *

 * @method showModuleHelp

 * @param {jQuery} carousel Our initialized carousel to manipulate

 * @param {Object} moduleData Data of the module to carousel to

 * @param {jQuery} modal We need to figure out if the current modal has a footer.

 */

const showModuleHelp = (carousel, moduleData, modal = null) => {

    // If we have a real footer then we need to change temporarily.

    if (modal !== null && moduleData.showFooter === true) {

        modal.setFooter(Templates.render('core_course/local/activitychooser/footer_partial', moduleData));

    }

    const help = carousel.find(selectors.regions.help)[0];

    help.innerHTML = '';

    help.classList.add('m-auto');

    // Add a spinner.

    const spinnerPromise = addIconToContainer(help);

    // Used later...

    let transitionPromiseResolver = null;

    const transitionPromise = new Promise(resolve => {

        transitionPromiseResolver = resolve;

    });

    // Build up the html & js ready to place into the help section.

    const contentPromise = Templates.renderForPromise('core_course/local/activitychooser/help', moduleData);

    // Wait for the content to be ready, and for the transition to be complet.

    Promise.all([contentPromise, spinnerPromise, transitionPromise])

        .then(([{html, js}]) => Templates.replaceNodeContents(help, html, js))

        .then(() => {

            help.querySelector(selectors.regions.chooserSummary.header).focus();

            return help;

        })

        .catch(Notification.exception);

    // Move to the next slide, and resolve the transition promise when it's done.

    carousel.one('slid.bs.carousel', () => {

        transitionPromiseResolver();

    });

    // Trigger the transition between 'pages'.

    carousel.carousel('next');

};

/**

 * Given a user wants to change the favourite state of a module we either add or remove the status.

 * We also propergate this change across our map of modals.

 *

 * @method manageFavouriteState

 * @param {HTMLElement} modalBody The DOM node of the modal to manipulate

 * @param {HTMLElement} caller

 * @param {Function} partialFavourite Partially applied function we need to manage favourite status

 */

const manageFavouriteState = async(modalBody, caller, partialFavourite) => {

    const isFavourite = caller.dataset.favourited;

    const id = caller.dataset.id;

    const name = caller.dataset.name;

    const internal = caller.dataset.internal;

    // Switch on fave or not.

    if (isFavourite === 'true') {

        await Repository.unfavouriteModule(name, id);

        partialFavourite(internal, false, modalBody);

    } else {

        await Repository.favouriteModule(name, id);

        partialFavourite(internal, true, modalBody);

    }

};

/**

 * Register chooser related event listeners.

 *

 * @method registerListenerEvents

 * @param {Promise} modal Our modal that we are working with

 * @param {Map} mappedModules A map of all of the modules we are working with with K: mod_name V: {Object}

 * @param {Function} partialFavourite Partially applied function we need to manage favourite status

 * @param {Object} footerData Our base footer object.

 */

const registerListenerEvents = (modal, mappedModules, partialFavourite, footerData) => {

    const bodyClickListener = async(e) => {

        if (e.target.closest(selectors.actions.optionActions.showSummary)) {

            const carousel = $(modal.getBody()[0].querySelector(selectors.regions.carousel));

            const module = e.target.closest(selectors.regions.chooserOption.container);

            const moduleName = module.dataset.modname;

            const moduleData = mappedModules.get(moduleName);

            // We need to know if the overall modal has a footer so we know when to show a real / vs fake footer.

            moduleData.showFooter = modal.hasFooterContent();

            showModuleHelp(carousel, moduleData, modal);

        }

        if (e.target.closest(selectors.actions.optionActions.manageFavourite)) {

            const caller = e.target.closest(selectors.actions.optionActions.manageFavourite);

            await manageFavouriteState(modal.getBody()[0], caller, partialFavourite);

            const activeSectionId = modal.getBody()[0].querySelector(selectors.elements.activetab).getAttribute("href");

            const sectionChooserOptions = modal.getBody()[0]

                .querySelector(selectors.regions.getSectionChooserOptions(activeSectionId));

            const firstChooserOption = sectionChooserOptions

                .querySelector(selectors.regions.chooserOption.container);

            toggleFocusableChooserOption(firstChooserOption, true);

            initChooserOptionsKeyboardNavigation(modal.getBody()[0], mappedModules, sectionChooserOptions, modal);

        }

        // From the help screen go back to the module overview.

        if (e.target.matches(selectors.actions.closeOption)) {

            const carousel = $(modal.getBody()[0].querySelector(selectors.regions.carousel));

            // Trigger the transition between 'pages'.

            carousel.carousel('prev');

            carousel.on('slid.bs.carousel', () => {

                const allModules = modal.getBody()[0].querySelector(selectors.regions.modules);

                const caller = allModules.querySelector(selectors.regions.getModuleSelector(e.target.dataset.modname));

                caller.focus();

            });

        }

        // The "clear search" button is triggered.

        if (e.target.closest(selectors.actions.clearSearch)) {

            // Clear the entered search query in the search bar and hide the search results container.

            const searchInput = modal.getBody()[0].querySelector(selectors.actions.search);

            searchInput.value = "";

            searchInput.focus();

            toggleSearchResultsView(modal, mappedModules, searchInput.value);

        }

    };

    // We essentially have two types of footer.

    // A fake one that is handled within the template for chooser_help and then all of the stuff for

    // modal.footer. We need to ensure we know exactly what type of footer we are using so we know what we

    // need to manage. The below code handles a real footer going to a mnet carousel item.

    const footerClickListener = async(e) => {

        if (footerData.footer === true) {

            const footerjs = await getPlugin(footerData.customfooterjs);

            await footerjs.footerClickListener(e, footerData, modal);

        }

    };

    modal.getBodyPromise()

    // The return value of getBodyPromise is a jquery object containing the body NodeElement.

    .then(body => body[0])

    // Set up the carousel.

    .then(body => {

        $(body.querySelector(selectors.regions.carousel))

            .carousel({

                interval: false,

                pause: true,

                keyboard: false

            });

        return body;

    })

    // Add the listener for clicks on the body.

    .then(body => {

        body.addEventListener('click', bodyClickListener);

        return body;

    })

    // Add a listener for an input change in the activity chooser's search bar.

    .then(body => {

        const searchInput = body.querySelector(selectors.actions.search);

        // The search input is triggered.

        searchInput.addEventListener('input', debounce(() => {

            // Display the search results.

            toggleSearchResultsView(modal, mappedModules, searchInput.value);

        }, 300));

        return body;

    })

    // Register event listeners related to the keyboard navigation controls.

    .then(body => {

        // Get the active chooser options section.

        const activeSectionId = body.querySelector(selectors.elements.activetab).getAttribute("href");

        const sectionChooserOptions = body.querySelector(selectors.regions.getSectionChooserOptions(activeSectionId));

        const firstChooserOption = sectionChooserOptions.querySelector(selectors.regions.chooserOption.container);

        toggleFocusableChooserOption(firstChooserOption, true);

        initChooserOptionsKeyboardNavigation(body, mappedModules, sectionChooserOptions, modal);

        return body;

    })

    .catch();

    modal.getFooterPromise()

    // The return value of getBodyPromise is a jquery object containing the body NodeElement.

    .then(footer => footer[0])

    // Add the listener for clicks on the footer.

    .then(footer => {

        footer.addEventListener('click', footerClickListener);

        return footer;

    })

    .catch();

};

/**

 * Initialise the keyboard navigation controls for the chooser options.

 *

 * @method initChooserOptionsKeyboardNavigation

 * @param {HTMLElement} body Our modal that we are working with

 * @param {Map} mappedModules A map of all of the modules we are working with with K: mod_name V: {Object}

 * @param {HTMLElement} chooserOptionsContainer The section that contains the chooser items

 * @param {Object} modal Our created modal for the section

 */

const initChooserOptionsKeyboardNavigation = (body, mappedModules, chooserOptionsContainer, modal = null) => {

    const chooserOptions = chooserOptionsContainer.querySelectorAll(selectors.regions.chooserOption.container);

    Array.from(chooserOptions).forEach((element) => {

        return element.addEventListener('keydown', (e) => {

            // Check for enter/ space triggers for showing the help.

            if (e.keyCode === enter || e.keyCode === space) {

                if (e.target.matches(selectors.actions.optionActions.showSummary)) {

                    e.preventDefault();

                    const module = e.target.closest(selectors.regions.chooserOption.container);

                    const moduleName = module.dataset.modname;

                    const moduleData = mappedModules.get(moduleName);

                    const carousel = $(body.querySelector(selectors.regions.carousel));

                    carousel.carousel({

                        interval: false,

                        pause: true,

                        keyboard: false

                    });

                    // We need to know if the overall modal has a footer so we know when to show a real / vs fake footer.

                    moduleData.showFooter = modal.hasFooterContent();

                    showModuleHelp(carousel, moduleData, modal);

                }

            }

            // Next.

            if (e.keyCode === arrowRight) {

                e.preventDefault();

                const currentOption = e.target.closest(selectors.regions.chooserOption.container);

                const nextOption = currentOption.nextElementSibling;

                const firstOption = chooserOptionsContainer.firstElementChild;

                const toFocusOption = clickErrorHandler(nextOption, firstOption);

                focusChooserOption(toFocusOption, currentOption);

            }

            // Previous.

            if (e.keyCode === arrowLeft) {

                e.preventDefault();

                const currentOption = e.target.closest(selectors.regions.chooserOption.container);

                const previousOption = currentOption.previousElementSibling;

                const lastOption = chooserOptionsContainer.lastElementChild;

                const toFocusOption = clickErrorHandler(previousOption, lastOption);

                focusChooserOption(toFocusOption, currentOption);

            }

            if (e.keyCode === home) {

                e.preventDefault();

                const currentOption = e.target.closest(selectors.regions.chooserOption.container);

                const firstOption = chooserOptionsContainer.firstElementChild;

                focusChooserOption(firstOption, currentOption);

            }

            if (e.keyCode === end) {

                e.preventDefault();

                const currentOption = e.target.closest(selectors.regions.chooserOption.container);

                const lastOption = chooserOptionsContainer.lastElementChild;

                focusChooserOption(lastOption, currentOption);

            }

        });

    });

};

/**

 * Focus on a chooser option element and remove the previous chooser element from the focus order

 *

 * @method focusChooserOption

 * @param {HTMLElement} currentChooserOption The current chooser option element that we want to focus

 * @param {HTMLElement|null} previousChooserOption The previous focused option element

 */

const focusChooserOption = (currentChooserOption, previousChooserOption = null) => {

    if (previousChooserOption !== null) {

        toggleFocusableChooserOption(previousChooserOption, false);

    }

    toggleFocusableChooserOption(currentChooserOption, true);

    currentChooserOption.focus();

};

/**

 * Add or remove a chooser option from the focus order.

 *

 * @method toggleFocusableChooserOption

 * @param {HTMLElement} chooserOption The chooser option element which should be added or removed from the focus order

 * @param {Boolean} isFocusable Whether the chooser element is focusable or not

 */

const toggleFocusableChooserOption = (chooserOption, isFocusable) => {

    const chooserOptionLink = chooserOption.querySelector(selectors.actions.addChooser);

    const chooserOptionHelp = chooserOption.querySelector(selectors.actions.optionActions.showSummary);

    const chooserOptionFavourite = chooserOption.querySelector(selectors.actions.optionActions.manageFavourite);

    if (isFocusable) {

        // Set tabindex to 0 to add current chooser option element to the focus order.

        chooserOption.tabIndex = 0;

        chooserOptionLink.tabIndex = 0;

        chooserOptionHelp.tabIndex = 0;

        chooserOptionFavourite.tabIndex = 0;

    } else {

        // Set tabindex to -1 to remove the previous chooser option element from the focus order.

        chooserOption.tabIndex = -1;

        chooserOptionLink.tabIndex = -1;

        chooserOptionHelp.tabIndex = -1;

        chooserOptionFavourite.tabIndex = -1;

    }

};

/**

 * Small error handling function to make sure the navigated to object exists

 *

 * @method clickErrorHandler

 * @param {HTMLElement} item What we want to check exists

 * @param {HTMLElement} fallback If we dont match anything fallback the focus

 * @return {HTMLElement}

 */

const clickErrorHandler = (item, fallback) => {

    if (item !== null) {

        return item;

    } else {

        return fallback;

    }

};

/**

 * Render the search results in a defined container

 *

 * @method renderSearchResults

 * @param {HTMLElement} searchResultsContainer The container where the data should be rendered

 * @param {Object} searchResultsData Data containing the module items that satisfy the search criteria

 */

const renderSearchResults = async(searchResultsContainer, searchResultsData) => {

    const templateData = {

        'searchresultsnumber': searchResultsData.length,

        'searchresults': searchResultsData

    };

    // Build up the html & js ready to place into the help section.

    const {html, js} = await Templates.renderForPromise('core_course/local/activitychooser/search_results', templateData);

    await Templates.replaceNodeContents(searchResultsContainer, html, js);

};

/**

 * Toggle (display/hide) the search results depending on the value of the search query

 *

 * @method toggleSearchResultsView

 * @param {Object} modal Our created modal for the section

 * @param {Map} mappedModules A map of all of the modules we are working with with K: mod_name V: {Object}

 * @param {String} searchQuery The search query

 */

const toggleSearchResultsView = async(modal, mappedModules, searchQuery) => {

    const modalBody = modal.getBody()[0];

    const searchResultsContainer = modalBody.querySelector(selectors.regions.searchResults);

    const chooserContainer = modalBody.querySelector(selectors.regions.chooser);

    const clearSearchButton = modalBody.querySelector(selectors.actions.clearSearch);

    if (searchQuery.length > 0) { // Search query is present.

        const searchResultsData = searchModules(mappedModules, searchQuery);

        await renderSearchResults(searchResultsContainer, searchResultsData);

        const searchResultItemsContainer = searchResultsContainer.querySelector(selectors.regions.searchResultItems);

        const firstSearchResultItem = searchResultItemsContainer.querySelector(selectors.regions.chooserOption.container);

        if (firstSearchResultItem) {

            // Set the first result item to be focusable.

            toggleFocusableChooserOption(firstSearchResultItem, true);

            // Register keyboard events on the created search result items.

            initChooserOptionsKeyboardNavigation(modalBody, mappedModules, searchResultItemsContainer, modal);

        }

        // Display the "clear" search button in the activity chooser search bar.

        clearSearchButton.classList.remove('d-none');

        // Hide the default chooser options container.

        chooserContainer.setAttribute('hidden', 'hidden');

        // Display the search results container.

        searchResultsContainer.removeAttribute('hidden');

    } else { // Search query is not present.

        // Hide the "clear" search button in the activity chooser search bar.

        clearSearchButton.classList.add('d-none');

        // Hide the search results container.

        searchResultsContainer.setAttribute('hidden', 'hidden');

        // Display the default chooser options container.

        chooserContainer.removeAttribute('hidden');

    }

};

/**

 * Return the list of modules which have a name or description that matches the given search term.

 *

 * @method searchModules

 * @param {Array} modules List of available modules

 * @param {String} searchTerm The search term to match

 * @return {Array}

 */

const searchModules = (modules, searchTerm) => {

    if (searchTerm === '') {

        return modules;

    }

    searchTerm = searchTerm.toLowerCase();

    const searchResults = [];

    modules.forEach((activity) => {

        const activityName = activity.title.toLowerCase();

        const activityDesc = activity.help.toLowerCase();

        if (activityName.includes(searchTerm) || activityDesc.includes(searchTerm)) {

            searchResults.push(activity);

        }

    });

    return searchResults;

};

/**

 * Set up our tabindex information across the chooser.

 *

 * @method setupKeyboardAccessibility

 * @param {Promise} modal Our created modal for the section

 * @param {Map} mappedModules A map of all of the built module information

 */

const setupKeyboardAccessibility = (modal, mappedModules) => {

    modal.getModal()[0].tabIndex = -1;

    modal.getBodyPromise().then(body => {

        $(selectors.elements.tab).on('shown.bs.tab', (e) => {

            const activeSectionId = e.target.getAttribute("href");

            const activeSectionChooserOptions = body[0]

                .querySelector(selectors.regions.getSectionChooserOptions(activeSectionId));

            const firstChooserOption = activeSectionChooserOptions

                .querySelector(selectors.regions.chooserOption.container);

            const prevActiveSectionId = e.relatedTarget.getAttribute("href");

            const prevActiveSectionChooserOptions = body[0]

                .querySelector(selectors.regions.getSectionChooserOptions(prevActiveSectionId));

            // Disable the focus of every chooser option in the previous active section.

            disableFocusAllChooserOptions(prevActiveSectionChooserOptions);

            // Enable the focus of the first chooser option in the current active section.

            toggleFocusableChooserOption(firstChooserOption, true);

            initChooserOptionsKeyboardNavigation(body[0], mappedModules, activeSectionChooserOptions, modal);

        });

        return;

    }).catch(Notification.exception);

};

/**

 * Disable the focus of all chooser options in a specific container (section).

 *

 * @method disableFocusAllChooserOptions

 * @param {HTMLElement} sectionChooserOptions The section that contains the chooser items

 */

const disableFocusAllChooserOptions = (sectionChooserOptions) => {

    const allChooserOptions = sectionChooserOptions.querySelectorAll(selectors.regions.chooserOption.container);

    allChooserOptions.forEach((chooserOption) => {

        toggleFocusableChooserOption(chooserOption, false);

    });

};

/**

 * Display the module chooser.

 *

 * @method displayChooser

 * @param {Promise} modalPromise Our created modal for the section

 * @param {Array} sectionModules An array of all of the built module information

 * @param {Function} partialFavourite Partially applied function we need to manage favourite status

 * @param {Object} footerData Our base footer object.

 */

export const displayChooser = (modalPromise, sectionModules, partialFavourite, footerData) => {

    // Make a map so we can quickly fetch a specific module's object for either rendering or searching.

    const mappedModules = new Map();

    sectionModules.forEach((module) => {

        mappedModules.set(module.componentname + '_' + module.link, module);

    });

    // Register event listeners.

    modalPromise.then(modal => {

        registerListenerEvents(modal, mappedModules, partialFavourite, footerData);

        // We want to focus on the first chooser option element as soon as the modal is opened.

        setupKeyboardAccessibility(modal, mappedModules);

        // We want to focus on the action select when the dialog is closed.

        modal.getRoot().on(ModalEvents.hidden, () => {

            modal.destroy();

        });

        return modal;

    }).catch();

};