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

import Templates from 'core/templates';
import {addOverlay, removeOverlay, removeAllOverlays} from 'core/local/reactive/overlay';

/**
 * Reactive UI component base class.
 *
 * Each UI reactive component should extend this class to interact with a reactive state.
 *
 * @module     core/local/reactive/basecomponent
 * @class     core/local/reactive/basecomponent
 * @copyright  2020 Ferran Recio <ferran@moodle.com>
 * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 */
export default class {

    /**
     * The component descriptor data structure.
     *
     * This structure is used by any component and init method to define the way the component will interact
     * with the interface and whith reactive instance operates. The logic behind this object is to avoid
     * unnecessary dependancies between the final interface and the state logic.
     *
     * Any component interacts with a single main DOM element (description.element) but it can use internal
     * selector to select elements within this main element (descriptor.selectors). By default each component
     * will provide it's own default selectors, but those can be overridden by the "descriptor.selectors"
     * property in case the mustache wants to reuse the same component logic but with a different interface.
     *
     * @typedef {object} descriptor
     * @property {Reactive} reactive an optional reactive module to register in
     * @property {DOMElement} element all components needs an element to anchor events
     * @property {object} [selectors] an optional object to override query selectors
     */

    /**
     * The class constructor.
     *
     * The only param this method gets is a constructor with all the mandatory
     * and optional component data. Component will receive the same descriptor
     * as create method param.
     *
     * This method will call the "create" method before registering the component into
     * the reactive module. This way any component can add default selectors and events.
     *
     * @param {descriptor} descriptor data to create the object.
     */
    constructor(descriptor) {

        if (descriptor.element === undefined || !(descriptor.element instanceof HTMLElement)) {
            throw Error(`Reactive components needs a main DOM element to dispatch events`);
        }

        this.element = descriptor.element;

        // Variable to track event listeners.
        this.eventHandlers = new Map([]);
        this.eventListeners = [];

        // Empty default component selectors.
        this.selectors = {};

        // Empty default event list from the static method.
        this.events = this.constructor.getEvents();

        // Call create function to get the component defaults.
        this.create(descriptor);

        // Overwrite the components selectors if necessary.
        if (descriptor.selectors !== undefined) {
            this.addSelectors(descriptor.selectors);
        }

        // Register into a reactive instance.
        if (descriptor.reactive === undefined) {
            // Ask parent components for registration.
            this.element.dispatchEvent(new CustomEvent(
                'core/reactive:requestRegistration',
                {
                    bubbles: true,
                    detail: {component: this},
                }
            ));
        } else {
            this.reactive = descriptor.reactive;
            this.reactive.registerComponent(this);
            // Add a listener to register child components.
            this.addEventListener(
                this.element,
                'core/reactive:requestRegistration',
                (event) => {
                    if (event?.detail?.component) {
                        event.stopPropagation();
                        this.registerChildComponent(event.detail.component);
                    }
                }
            );
        }
    }

    /**
     * Return the component custom event names.
     *
     * Components may override this method to provide their own events.
     *
     * Component custom events is an important part of component reusability. This function
     * is static because is part of the component definition and should be accessible from
     * outsite the instances. However, values will be available at instance level in the
     * this.events object.
     *
     * @returns {Object} the component events.
     */
    static getEvents() {
        return {};
    }

    /**
     * Component create function.
     *
     * Default init method will call "create" when all internal attributes are set
     * but before the component is not yet registered in the reactive module.
     *
     * In this method any component can define its own defaults such as:
     * - this.selectors {object} the default query selectors of this component.
     * - this.events {object} a list of event names this component dispatch
     * - extract any data from the main dom element (this.element)
     * - set any other data the component uses
     *
     * @param {descriptor} descriptor the component descriptor
     */
    // eslint-disable-next-line no-unused-vars
    create(descriptor) {
        // Components may override this method to initialize selects, events or other data.
    }

    /**
     * Component destroy hook.
     *
     * BaseComponent call this method when a component is unregistered or removed.
     *
     * Components may override this method to clean the HTML or do some action when the
     * component is unregistered or removed.
     */
    destroy() {
        // Components can override this method.
    }

    /**
     * Return the list of watchers that component has.
     *
     * Each watcher is represented by an object with two attributes:
     * - watch (string) the specific state event to watch. Example 'section.visible:updated'
     * - handler (function) the function to call when the watching state change happens
     *
     * Any component shoudl override this method to define their state watchers.
     *
     * @returns {array} array of watchers.
     */
    getWatchers() {
        return [];
    }

    /**
     * Reactive module will call this method when the state is ready.
     *
     * Component can override this method to update/load the component HTML or to bind
     * listeners to HTML entities.
     */
    stateReady() {
        // Components can override this method.
    }

    /**
     * Get the main DOM element of this component or a subelement.
     *
     * @param {string|undefined} query optional subelement query
     * @param {string|undefined} dataId optional data-id value
     * @returns {element|undefined} the DOM element (if any)
     */
    getElement(query, dataId) {
        if (query === undefined && dataId === undefined) {
            return this.element;
        }
        const dataSelector = (dataId) ? `[data-id='${dataId}']` : '';
        const selector = `${query ?? ''}${dataSelector}`;
        return this.element.querySelector(selector);
    }

    /**
     * Get the all subelement that match a query selector.
     *
     * @param {string|undefined} query optional subelement query
     * @param {string|undefined} dataId optional data-id value
     * @returns {NodeList} the DOM elements
     */
    getElements(query, dataId) {
        const dataSelector = (dataId) ? `[data-id='${dataId}']` : '';
        const selector = `${query ?? ''}${dataSelector}`;
        return this.element.querySelectorAll(selector);
    }

    /**
     * Add or update the component selectors.
     *
     * @param {Object} newSelectors an object of new selectors.
     */
    addSelectors(newSelectors) {
        for (const [selectorName, selector] of Object.entries(newSelectors)) {
            this.selectors[selectorName] = selector;
        }
    }

    /**
     * Return a component selector.
     *
     * @param {string} selectorName the selector name
     * @return {string|undefined} the query selector
     */
    getSelector(selectorName) {
        return this.selectors[selectorName];
    }

    /**
     * Dispatch a custom event on this.element.
     *
     * This is just a convenient method to dispatch custom events from within a component.
     * Components are free to use an alternative function to dispatch custom
     * events. The only restriction is that it should be dispatched on this.element
     * and specify "bubbles:true" to alert any component listeners.
     *
     * @param {string} eventName the event name
     * @param {*} detail event detail data
     */
    dispatchEvent(eventName, detail) {
        this.element.dispatchEvent(new CustomEvent(eventName, {
            bubbles: true,
            detail: detail,
        }));
    }

    /**
     * Render a new Component using a mustache file.
     *
     * It is important to note that this method should NOT be used for loading regular mustache files
     * as it returns a Promise that will only be resolved if the mustache registers a component instance.
     *
     * @param {element} target the DOM element that contains the component
     * @param {string} file the component mustache file to render
     * @param {*} data the mustache data
     * @return {Promise} a promise of the resulting component instance
     */
    renderComponent(target, file, data) {
        return new Promise((resolve, reject) => {
            target.addEventListener('ComponentRegistration:Success', ({detail}) => {
                resolve(detail.component);
            });
            target.addEventListener('ComponentRegistration:Fail', () => {
                reject(`Registration of ${file} fails.`);
            });
            Templates.renderForPromise(
                file,
                data
            ).then(({html, js}) => {
                Templates.replaceNodeContents(target, html, js);
                return true;
            }).catch(error => {
                reject(`Rendering of ${file} throws an error.`);
                throw error;
            });
        });
    }

    /**
     * Add and bind an event listener to a target and keep track of all event listeners.
     *
     * The native element.addEventListener method is not object oriented friently as the
     * "this" represents the element that triggers the event and not the listener class.
     * As components can be unregister and removed at any time, the BaseComponent provides
     * this method to keep track of all component listeners and do all of the bind stuff.
     *
     * @param {Element} target the event target
     * @param {string} type the event name
     * @param {function} listener the class method that recieve the event
     */
    addEventListener(target, type, listener) {

        // Check if we have the bind version of that listener.
        let bindListener = this.eventHandlers.get(listener);

        if (bindListener === undefined) {
            bindListener = listener.bind(this);
            this.eventHandlers.set(listener, bindListener);
        }

        target.addEventListener(type, bindListener);

        // Keep track of all component event listeners in case we need to remove them.
        this.eventListeners.push({
            target,
            type,
            bindListener,
        });

    }

    /**
     * Remove an event listener from a component.
     *
     * This method allows components to remove listeners without keeping track of the
     * listeners bind versions of the method. Both addEventListener and removeEventListener
     * keeps internally the relation between the original class method and the bind one.
     *
     * @param {Element} target the event target
     * @param {string} type the event name
     * @param {function} listener the class method that recieve the event
     */
    removeEventListener(target, type, listener) {
        // Check if we have the bind version of that listener.
        let bindListener = this.eventHandlers.get(listener);

        if (bindListener === undefined) {
            // This listener has not been added.
            return;
        }

        target.removeEventListener(type, bindListener);
    }

    /**
     * Remove all event listeners from this component.
     *
     * This method is called also when the component is unregistered or removed.
     *
     * Note that only listeners registered with the addEventListener method
     * will be removed. Other manual listeners will keep active.
     */
    removeAllEventListeners() {
        this.eventListeners.forEach(({target, type, bindListener}) => {
            target.removeEventListener(type, bindListener);
        });
        this.eventListeners = [];
    }

    /**
     * Remove a previously rendered component instance.
     *
     * This method will remove the component HTML and unregister it from the
     * reactive module.
     */
    remove() {
        this.unregister();
        this.element.remove();
    }

    /**
     * Unregister the component from the reactive module.
     *
     * This method will disable the component logic, event listeners and watchers
     * but it won't remove any HTML created by the component. However, it will trigger
     * the destroy hook to allow the component to clean parts of the interface.
     */
    unregister() {
        this.reactive.unregisterComponent(this);
        this.removeAllEventListeners();
        this.destroy();
    }

    /**
     * Dispatch a component registration event to inform the parent node.
     *
     * The registration event is different from the rest of the component events because
     * is the only way in which components can communicate its existence to a possible parent.
     * Most components will be created by including a mustache file, child components
     * must emit a registration event to the parent DOM element to alert about the registration.
     */
    dispatchRegistrationSuccess() {
        // The registration event does not bubble because we just want to comunicate with the parentNode.
        // Otherwise, any component can get multiple registrations events and could not differentiate
        // between child components and grand child components.
        if (this.element.parentNode === undefined) {
            return;
        }
        // This custom element is captured by renderComponent method.
        this.element.parentNode.dispatchEvent(new CustomEvent(
            'ComponentRegistration:Success',
            {
                bubbles: false,
                detail: {component: this},
            }
        ));
    }

    /**
     * Dispatch a component registration fail event to inform the parent node.
     *
     * As dispatchRegistrationSuccess, this method will communicate the registration fail to the
     * parent node to inform the possible parent component.
     */
    dispatchRegistrationFail() {
        if (this.element.parentNode === undefined) {
            return;
        }
        // This custom element is captured only by renderComponent method.
        this.element.parentNode.dispatchEvent(new CustomEvent(
            'ComponentRegistration:Fail',
            {
                bubbles: false,
                detail: {component: this},
            }
        ));
    }

    /**
     * Register a child component into the reactive instance.
     *
     * @param {self} component the component to register.
     */
    registerChildComponent(component) {
        component.reactive = this.reactive;
        this.reactive.registerComponent(component);
    }

    /**
     * Set the lock value and locks or unlocks the element.
     *
     * @param {boolean} locked the new locked value
     */
    set locked(locked) {
        this.setElementLocked(this.element, locked);
    }

    /**
     * Get the current locked value from the element.
     *
     * @return {boolean}
     */
    get locked() {
        return this.getElementLocked(this.element);
    }

    /**
     * Lock/unlock an element.
     *
     * @param {Element} target the event target
     * @param {boolean} locked the new locked value
     */
    setElementLocked(target, locked) {
        target.dataset.locked = locked ?? false;
        if (locked) {
            // Disable interactions.
            target.style.pointerEvents = 'none';
            target.style.userSelect = 'none';
            // Check if it is draggable.
            if (target.hasAttribute('draggable')) {
                target.setAttribute('draggable', false);
            }
            target.setAttribute('aria-busy', true);
        } else {
            // Enable interactions.
            target.style.pointerEvents = null;
            target.style.userSelect = null;
            // Check if it was draggable.
            if (target.hasAttribute('draggable')) {
                target.setAttribute('draggable', true);
            }
            target.setAttribute('aria-busy', false);
        }
    }

    /**
     * Get the current locked value from the element.
     *
     * @param {Element} target the event target
     * @return {boolean}
     */
    getElementLocked(target) {
        return target.dataset.locked ?? false;
    }

    /**
     * Adds an overlay to a specific page element.
     *
     * @param {Object} definition the overlay definition.
     * @param {String} definition.content an optional overlay content.
     * @param {String} definition.classes an optional CSS classes
     * @param {Element} target optional parent object (this.element will be used if none provided)
     */
    async addOverlay(definition, target) {
        if (this._overlay) {
            this.removeOverlay();
        }
        this._overlay = await addOverlay(
            {
                content: definition.content,
                css: definition.classes ?? 'file-drop-zone',
            },
            target ?? this.element
        );
    }

    /**
     * Remove the current overlay.
     */
    removeOverlay() {
        if (!this._overlay) {
            return;
        }
        removeOverlay(this._overlay);
        this._overlay = null;
    }

    /**
     * Remove all page overlais.
     */
    removeAllOverlays() {
        removeAllOverlays();
    }
}