// 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();
}
}