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

/**

 * Course index main component.

 *

 * @module     core_courseformat/local/content

 * @class      core_courseformat/local/content

 * @copyright  2020 Ferran Recio <ferran@moodle.com>

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

 */

import {BaseComponent} from 'core/reactive';

import {debounce} from 'core/utils';

import {getCurrentCourseEditor} from 'core_courseformat/courseeditor';

import Config from 'core/config';

import inplaceeditable from 'core/inplace_editable';

import Section from 'core_courseformat/local/content/section';

import CmItem from 'core_courseformat/local/content/section/cmitem';

import Fragment from 'core/fragment';

import Templates from 'core/templates';

import DispatchActions from 'core_courseformat/local/content/actions';

import * as CourseEvents from 'core_course/events';

// The jQuery module is only used for interacting with Boostrap 4. It can we removed when MDL-71979 is integrated.

import jQuery from 'jquery';

import Pending from 'core/pending';

export default class Component extends BaseComponent {

    /**

     * Constructor hook.

     *

     * @param {Object} descriptor the component descriptor

     */

    create(descriptor) {

        // Optional component name for debugging.

        this.name = 'course_format';

        // Default query selectors.

        this.selectors = {

            SECTION: `[data-for='section']`,

            SECTION_ITEM: `[data-for='section_title']`,

            SECTION_CMLIST: `[data-for='cmlist']`,

            COURSE_SECTIONLIST: `[data-for='course_sectionlist']`,

            CM: `[data-for='cmitem']`,

            TOGGLER: `[data-action="togglecoursecontentsection"]`,

            COLLAPSE: `[data-toggle="collapse"]`,

            TOGGLEALL: `[data-toggle="toggleall"]`,

            // Formats can override the activity tag but a default one is needed to create new elements.

            ACTIVITYTAG: 'li',

            SECTIONTAG: 'li',

        };

        this.selectorGenerators = {

            cmNameFor: (id) => `[data-cm-name-for='${id}']`,

            sectionNameFor: (id) => `[data-section-name-for='${id}']`,

        };

        // Default classes to toggle on refresh.

        this.classes = {

            COLLAPSED: `collapsed`,

            // Course content classes.

            ACTIVITY: `activity`,

            STATEDREADY: `stateready`,

            SECTION: `section`,

        };

        // Array to save dettached elements during element resorting.

        this.dettachedCms = {};

        this.dettachedSections = {};

        // Index of sections and cms components.

        this.sections = {};

        this.cms = {};

        // The page section return.

        this.sectionReturn = descriptor.sectionReturn ?? null;

        this.debouncedReloads = new Map();

    }

    /**

     * Static method to create a component instance form the mustahce template.

     *

     * @param {string} target the DOM main element or its ID

     * @param {object} selectors optional css selector overrides

     * @param {number} sectionReturn the content section return

     * @return {Component}

     */

    static init(target, selectors, sectionReturn) {

        return new Component({

            element: document.getElementById(target),

            reactive: getCurrentCourseEditor(),

            selectors,

            sectionReturn,

        });

    }

    /**

     * Initial state ready method.

     *

     * @param {Object} state the state data

     */

    stateReady(state) {

        this._indexContents();

        // Activate section togglers.

        this.addEventListener(this.element, 'click', this._sectionTogglers);

        // Collapse/Expand all sections button.

        const toogleAll = this.getElement(this.selectors.TOGGLEALL);

        if (toogleAll) {

            // Ensure collapse menu button adds aria-controls attribute referring to each collapsible element.

            const collapseElements = this.getElements(this.selectors.COLLAPSE);

            const collapseElementIds = [...collapseElements].map(element => element.id);

            toogleAll.setAttribute('aria-controls', collapseElementIds.join(' '));

            this.addEventListener(toogleAll, 'click', this._allSectionToggler);

            this.addEventListener(toogleAll, 'keydown', e => {

                // Collapse/expand all sections when Space key is pressed on the toggle button.

                if (e.key === ' ') {

                    this._allSectionToggler(e);

                }

            });

            this._refreshAllSectionsToggler(state);

        }

        if (this.reactive.supportComponents) {

            // Actions are only available in edit mode.

            if (this.reactive.isEditing) {

                new DispatchActions(this);

            }

            // Mark content as state ready.

            this.element.classList.add(this.classes.STATEDREADY);

        }

        // Capture completion events.

        this.addEventListener(

            this.element,

            CourseEvents.manualCompletionToggled,

            this._completionHandler

        );

        // Capture page scroll to update page item.

        this.addEventListener(

            document,

            "scroll",

            this._scrollHandler

        );

    }

    /**

     * Setup sections toggler.

     *

     * Toggler click is delegated to the main course content element because new sections can

     * appear at any moment and this way we prevent accidental double bindings.

     *

     * @param {Event} event the triggered event

     */

    _sectionTogglers(event) {

        const sectionlink = event.target.closest(this.selectors.TOGGLER);

        const closestCollapse = event.target.closest(this.selectors.COLLAPSE);

        // Assume that chevron is the only collapse toggler in a section heading;

        // I think this is the most efficient way to verify at the moment.

        const isChevron = closestCollapse?.closest(this.selectors.SECTION_ITEM);

        if (sectionlink || isChevron) {

            const section = event.target.closest(this.selectors.SECTION);

            const toggler = section.querySelector(this.selectors.COLLAPSE);

            const isCollapsed = toggler?.classList.contains(this.classes.COLLAPSED) ?? false;

            const sectionId = section.getAttribute('data-id');

            this.reactive.dispatch(

                'sectionContentCollapsed',

                [sectionId],

                !isCollapsed,

            );

        }

    }

    /**

     * Handle the collapse/expand all sections button.

     *

     * Toggler click is delegated to the main course content element because new sections can

     * appear at any moment and this way we prevent accidental double bindings.

     *

     * @param {Event} event the triggered event

     */

    _allSectionToggler(event) {

        event.preventDefault();

        const target = event.target.closest(this.selectors.TOGGLEALL);

        const isAllCollapsed = target.classList.contains(this.classes.COLLAPSED);

        const course = this.reactive.get('course');

        this.reactive.dispatch(

            'sectionContentCollapsed',

            course.sectionlist ?? [],

            !isAllCollapsed

        );

    }

    /**

     * Return the component watchers.

     *

     * @returns {Array} of watchers

     */

    getWatchers() {

        // Section return is a global page variable but most formats define it just before start printing

        // the course content. This is the reason why we define this page setting here.

        this.reactive.sectionReturn = this.sectionReturn;

        // Check if the course format is compatible with reactive components.

        if (!this.reactive.supportComponents) {

            return [];

        }

        return [

            // State changes that require to reload some course modules.

            {watch: `cm.visible:updated`, handler: this._reloadCm},

            {watch: `cm.stealth:updated`, handler: this._reloadCm},

            {watch: `cm.sectionid:updated`, handler: this._reloadCm},

            {watch: `cm.indent:updated`, handler: this._reloadCm},

            {watch: `cm.groupmode:updated`, handler: this._reloadCm},

            {watch: `cm.name:updated`, handler: this._refreshCmName},

            // Update section number and title.

            {watch: `section.number:updated`, handler: this._refreshSectionNumber},

            {watch: `section.title:updated`, handler: this._refreshSectionTitle},

            // Collapse and expand sections.

            {watch: `section.contentcollapsed:updated`, handler: this._refreshSectionCollapsed},

            // Sections and cm sorting.

            {watch: `transaction:start`, handler: this._startProcessing},

            {watch: `course.sectionlist:updated`, handler: this._refreshCourseSectionlist},

            {watch: `section.cmlist:updated`, handler: this._refreshSectionCmlist},

            // Section visibility.

            {watch: `section.visible:updated`, handler: this._reloadSection},

            // Reindex sections and cms.

            {watch: `state:updated`, handler: this._indexContents},

        ];

    }

    /**

     * Update a course module name on the whole page.

     *

     * @param {object} param

     * @param {Object} param.element details the update details.

     */

    _refreshCmName({element}) {

        // Update classes.

        // Replace the text content of the cm name.

        const allCmNamesFor = this.getElements(

            this.selectorGenerators.cmNameFor(element.id)

        );

        allCmNamesFor.forEach((cmNameFor) => {

            cmNameFor.textContent = element.name;

        });

    }

    /**

     * Update section collapsed state via bootstrap 4 if necessary.

     *

     * Formats that do not use bootstrap 4 must override this method in order to keep the section

     * toggling working.

     *

     * @param {object} args

     * @param {Object} args.state The state data

     * @param {Object} args.element The element to update

     */

    _refreshSectionCollapsed({state, element}) {

        const target = this.getElement(this.selectors.SECTION, element.id);

        if (!target) {

            throw new Error(`Unknown section with ID ${element.id}`);

        }

        // Check if it is already done.

        const toggler = target.querySelector(this.selectors.COLLAPSE);

        const isCollapsed = toggler?.classList.contains(this.classes.COLLAPSED) ?? false;

        if (element.contentcollapsed !== isCollapsed) {

            let collapsibleId = toggler.dataset.target ?? toggler.getAttribute("href");

            if (!collapsibleId) {

                return;

            }

            collapsibleId = collapsibleId.replace('#', '');

            const collapsible = document.getElementById(collapsibleId);

            if (!collapsible) {

                return;

            }

            // Course index is based on Bootstrap 4 collapsibles. To collapse them we need jQuery to

            // interact with collapsibles methods. Hopefully, this will change in Bootstrap 5 because

            // it does not require jQuery anymore (when MDL-71979 is integrated).

            jQuery(collapsible).collapse(element.contentcollapsed ? 'hide' : 'show');

        }

        this._refreshAllSectionsToggler(state);

    }

    /**

     * Refresh the collapse/expand all sections element.

     *

     * @param {Object} state The state data

     */

    _refreshAllSectionsToggler(state) {

        const target = this.getElement(this.selectors.TOGGLEALL);

        if (!target) {

            return;

        }

        // Check if we have all sections collapsed/expanded.

        let allcollapsed = true;

        let allexpanded = true;

        state.section.forEach(

            section => {

                allcollapsed = allcollapsed && section.contentcollapsed;

                allexpanded = allexpanded && !section.contentcollapsed;

            }

        );

        if (allcollapsed) {

            target.classList.add(this.classes.COLLAPSED);

            target.setAttribute('aria-expanded', false);

        }

        if (allexpanded) {

            target.classList.remove(this.classes.COLLAPSED);

            target.setAttribute('aria-expanded', true);

        }

    }

    /**

     * Setup the component to start a transaction.

     *

     * Some of the course actions replaces the current DOM element with a new one before updating the

     * course state. This means the component cannot preload any index properly until the transaction starts.

     *

     */

    _startProcessing() {

        // During a section or cm sorting, some elements could be dettached from the DOM and we

        // need to store somewhare in case they are needed later.

        this.dettachedCms = {};

        this.dettachedSections = {};

    }

    /**

     * Activity manual completion listener.

     *

     * @param {Event} event the custom ecent

     */

    _completionHandler({detail}) {

        if (detail === undefined) {

            return;

        }

        this.reactive.dispatch('cmCompletion', [detail.cmid], detail.completed);

    }

    /**

     * Check the current page scroll and update the active element if necessary.

     */

    _scrollHandler() {

        const pageOffset = window.scrollY;

        const items = this.reactive.getExporter().allItemsArray(this.reactive.state);

        // Check what is the active element now.

        let pageItem = null;

        items.every(item => {

            const index = (item.type === 'section') ? this.sections : this.cms;

            if (index[item.id] === undefined) {

                return true;

            }

            const element = index[item.id].element;

            pageItem = item;

            return pageOffset >= element.offsetTop;

        });

        if (pageItem) {

            this.reactive.dispatch('setPageItem', pageItem.type, pageItem.id);

        }

    }

    /**

     * Update a course section when the section number changes.

     *

     * The courseActions module used for most course section tools still depends on css classes and

     * section numbers (not id). To prevent inconsistencies when a section is moved, we need to refresh

     * the

     *

     * Course formats can override the section title rendering so the frontend depends heavily on backend

     * rendering. Luckily in edit mode we can trigger a title update using the inplace_editable module.

     *

     * @param {Object} param

     * @param {Object} param.element details the update details.

     */

    _refreshSectionNumber({element}) {

        // Find the element.

        const target = this.getElement(this.selectors.SECTION, element.id);

        if (!target) {

            // Job done. Nothing to refresh.

            return;

        }

        // Update section numbers in all data, css and YUI attributes.

        target.id = `section-${element.number}`;

        // YUI uses section number as section id in data-sectionid, in principle if a format use components

        // don't need this sectionid attribute anymore, but we keep the compatibility in case some plugin

        // use it for legacy purposes.

        target.dataset.sectionid = element.number;

        // The data-number is the attribute used by components to store the section number.

        target.dataset.number = element.number;

        // Update title and title inplace editable, if any.

        const inplace = inplaceeditable.getInplaceEditable(target.querySelector(this.selectors.SECTION_ITEM));

        if (inplace) {

            // The course content HTML can be modified at any moment, so the function need to do some checkings

            // to make sure the inplace editable still represents the same itemid.

            const currentvalue = inplace.getValue();

            const currentitemid = inplace.getItemId();

            // Unnamed sections must be recalculated.

            if (inplace.getValue() === '') {

                // The value to send can be an empty value if it is a default name.

                if (currentitemid == element.id && (currentvalue != element.rawtitle || element.rawtitle == '')) {

                    inplace.setValue(element.rawtitle);

                }

            }

        }

    }

    /**

     * Update a course section name on the whole page.

     *

     * @param {object} param

     * @param {Object} param.element details the update details.

     */

    _refreshSectionTitle({element}) {

        // Replace the text content of the section name in the whole page.

        const allSectionNamesFor = document.querySelectorAll(

            this.selectorGenerators.sectionNameFor(element.id)

        );

        allSectionNamesFor.forEach((sectionNameFor) => {

            sectionNameFor.textContent = element.title;

        });

    }

    /**

     * Refresh a section cm list.

     *

     * @param {Object} param

     * @param {Object} param.element details the update details.

     */

    _refreshSectionCmlist({element}) {

        const cmlist = element.cmlist ?? [];

        const section = this.getElement(this.selectors.SECTION, element.id);

        const listparent = section?.querySelector(this.selectors.SECTION_CMLIST);

        // A method to create a fake element to be replaced when the item is ready.

        const createCm = this._createCmItem.bind(this);

        if (listparent) {

            this._fixOrder(listparent, cmlist, this.selectors.CM, this.dettachedCms, createCm);

        }

    }

    /**

     * Refresh the section list.

     *

     * @param {Object} param

     * @param {Object} param.state the full state object.

     */

    _refreshCourseSectionlist({state}) {

        // If we have a section return means we only show a single section so no need to fix order.

        if (this.reactive.sectionReturn !== null) {

            return;

        }

        const sectionlist = this.reactive.getExporter().listedSectionIds(state);

        const listparent = this.getElement(this.selectors.COURSE_SECTIONLIST);

        // For now section cannot be created at a frontend level.

        const createSection = this._createSectionItem.bind(this);

        if (listparent) {

            this._fixOrder(listparent, sectionlist, this.selectors.SECTION, this.dettachedSections, createSection);

        }

    }

    /**

     * Regenerate content indexes.

     *

     * This method is used when a legacy action refresh some content element.

     */

    _indexContents() {

        // Find unindexed sections.

        this._scanIndex(

            this.selectors.SECTION,

            this.sections,

            (item) => {

                return new Section(item);

            }

        );

        // Find unindexed cms.

        this._scanIndex(

            this.selectors.CM,

            this.cms,

            (item) => {

                return new CmItem(item);

            }

        );

    }

    /**

     * Reindex a content (section or cm) of the course content.

     *

     * This method is used internally by _indexContents.

     *

     * @param {string} selector the DOM selector to scan

     * @param {*} index the index attribute to update

     * @param {*} creationhandler method to create a new indexed element

     */

    _scanIndex(selector, index, creationhandler) {

        const items = this.getElements(`${selector}:not([data-indexed])`);

        items.forEach((item) => {

            if (!item?.dataset?.id) {

                return;

            }

            // Delete previous item component.

            if (index[item.dataset.id] !== undefined) {

                index[item.dataset.id].unregister();

            }

            // Create the new component.

            index[item.dataset.id] = creationhandler({

                ...this,

                element: item,

            });

            // Mark as indexed.

            item.dataset.indexed = true;

        });

    }

    /**

     * Reload a course module contents.

     *

     * Most course module HTML is still strongly backend dependant.

     * Some changes require to get a new version of the module.

     *

     * @param {object} param0 the watcher details

     * @param {object} param0.element the state object

     */

    _reloadCm({element}) {

        if (!this.getElement(this.selectors.CM, element.id)) {

            return;

        }

        const debouncedReload = this._getDebouncedReloadCm(element.id);

        debouncedReload();

    }

    /**

     * Generate or get a reload CM debounced function.

     * @param {Number} cmId

     * @returns {Function} the debounced reload function

     */

    _getDebouncedReloadCm(cmId) {

        const pendingKey = `courseformat/content:reloadCm_${cmId}`;

        let debouncedReload = this.debouncedReloads.get(pendingKey);

        if (debouncedReload) {

            return debouncedReload;

        }

        const reload = () => {

            const pendingReload = new Pending(pendingKey);

            this.debouncedReloads.delete(pendingKey);

            const cmitem = this.getElement(this.selectors.CM, cmId);

            if (!cmitem) {

                return pendingReload.resolve();

            }

            const promise = Fragment.loadFragment(

                'core_courseformat',

                'cmitem',

                Config.courseContextId,

                {

                    id: cmId,

                    courseid: Config.courseId,

                    sr: this.reactive.sectionReturn ?? null,

                }

            );

            promise.then((html, js) => {

                // Other state change can reload the CM or the section before this one.

                if (!document.contains(cmitem)) {

                    pendingReload.resolve();

                    return false;

                }

                Templates.replaceNode(cmitem, html, js);

                this._indexContents();

                pendingReload.resolve();

                return true;

            }).catch(() => {

                pendingReload.resolve();

            });

            return pendingReload;

        };

        debouncedReload = debounce(

            reload,

            200,

            {

                cancel: true, pending: true

            }

        );

        this.debouncedReloads.set(pendingKey, debouncedReload);

        return debouncedReload;

    }

    /**

     * Cancel the active reload CM debounced function, if any.

     * @param {Number} cmId

     */

    _cancelDebouncedReloadCm(cmId) {

        const pendingKey = `courseformat/content:reloadCm_${cmId}`;

        const debouncedReload = this.debouncedReloads.get(pendingKey);

        if (!debouncedReload) {

            return;

        }

        debouncedReload.cancel();

        this.debouncedReloads.delete(pendingKey);

    }

    /**

     * Reload a course section contents.

     *

     * Section HTML is still strongly backend dependant.

     * Some changes require to get a new version of the section.

     *

     * @param {details} param0 the watcher details

     * @param {object} param0.element the state object

     */

    _reloadSection({element}) {

        const pendingReload = new Pending(`courseformat/content:reloadSection_${element.id}`);

        const sectionitem = this.getElement(this.selectors.SECTION, element.id);

        if (sectionitem) {

            // Cancel any pending reload because the section will reload cms too.

            for (const cmId of element.cmlist) {

                this._cancelDebouncedReloadCm(cmId);

            }

            const promise = Fragment.loadFragment(

                'core_courseformat',

                'section',

                Config.courseContextId,

                {

                    id: element.id,

                    courseid: Config.courseId,

                    sr: this.reactive.sectionReturn ?? null,

                }

            );

            promise.then((html, js) => {

                Templates.replaceNode(sectionitem, html, js);

                this._indexContents();

                pendingReload.resolve();

            }).catch(() => {

                pendingReload.resolve();

            });

        }

    }

    /**

     * Create a new course module item in a section.

     *

     * Thos method will append a fake item in the container and trigger an ajax request to

     * replace the fake element by the real content.

     *

     * @param {Element} container the container element (section)

     * @param {Number} cmid the course-module ID

     * @returns {Element} the created element

     */

    _createCmItem(container, cmid) {

        const newItem = document.createElement(this.selectors.ACTIVITYTAG);

        newItem.dataset.for = 'cmitem';

        newItem.dataset.id = cmid;

        // The legacy actions.js requires a specific ID and class to refresh the CM.

        newItem.id = `module-${cmid}`;

        newItem.classList.add(this.classes.ACTIVITY);

        container.append(newItem);

        this._reloadCm({

            element: this.reactive.get('cm', cmid),

        });

        return newItem;

    }

    /**

     * Create a new section item.

     *

     * This method will append a fake item in the container and trigger an ajax request to

     * replace the fake element by the real content.

     *

     * @param {Element} container the container element (section)

     * @param {Number} sectionid the course-module ID

     * @returns {Element} the created element

     */

    _createSectionItem(container, sectionid) {

        const section = this.reactive.get('section', sectionid);

        const newItem = document.createElement(this.selectors.SECTIONTAG);

        newItem.dataset.for = 'section';

        newItem.dataset.id = sectionid;

        newItem.dataset.number = section.number;

        // The legacy actions.js requires a specific ID and class to refresh the section.

        newItem.id = `section-${sectionid}`;

        newItem.classList.add(this.classes.SECTION);

        container.append(newItem);

        this._reloadSection({

            element: section,

        });

        return newItem;

    }

    /**

     * Fix/reorder the section or cms order.

     *

     * @param {Element} container the HTML element to reorder.

     * @param {Array} neworder an array with the ids order

     * @param {string} selector the element selector

     * @param {Object} dettachedelements a list of dettached elements

     * @param {function} createMethod method to create missing elements

     */

    async _fixOrder(container, neworder, selector, dettachedelements, createMethod) {

        if (container === undefined) {

            return;

        }

        // Empty lists should not be visible.

        if (!neworder.length) {

            container.classList.add('hidden');

            container.innerHTML = '';

            return;

        }

        // Grant the list is visible (in case it was empty).

        container.classList.remove('hidden');

        // Move the elements in order at the beginning of the list.

        neworder.forEach((itemid, index) => {

            let item = this.getElement(selector, itemid) ?? dettachedelements[itemid] ?? createMethod(container, itemid);

            if (item === undefined) {

                // Missing elements cannot be sorted.

                return;

            }

            // Get the current elemnt at that position.

            const currentitem = container.children[index];

            if (currentitem === undefined) {

                container.append(item);

                return;

            }

            if (currentitem !== item) {

                container.insertBefore(item, currentitem);

            }

        });

        // Dndupload add a fake element we need to keep.

        let dndFakeActivity;

        // Remove the remaining elements.

        while (container.children.length > neworder.length) {

            const lastchild = container.lastChild;

            if (lastchild?.classList?.contains('dndupload-preview')) {

                dndFakeActivity = lastchild;

            } else {

                dettachedelements[lastchild?.dataset?.id ?? 0] = lastchild;

            }

            container.removeChild(lastchild);

        }

        // Restore dndupload fake element.

        if (dndFakeActivity) {

            container.append(dndFakeActivity);

        }

    }

}