Commit b58e7806 authored by Ferran Recio Calderó's avatar Ferran Recio Calderó
Browse files

MDL-71995 core: reactive debug tools

parent 9145d80b
......@@ -140,6 +140,7 @@ $string['cliupgradefinished'] = 'Command line upgrade from {$a->oldversion} to {
$string['cliupgradenoneed'] = 'No upgrade needed for the installed version {$a}. Thanks for coming anyway!';
$string['cliupgradepending'] = 'An upgrade is pending';
$string['cliyesnoprompt'] = 'type y (means yes) or n (means no)';
$string['close'] = 'Close';
$string['commentsperpage'] = 'Comments displayed per page';
$string['commonactivitysettings'] = 'Common activity settings';
$string['commonfiltersettings'] = 'Common filter settings';
......
......@@ -52,6 +52,17 @@ $string['notables'] = 'No tables!';
$string['outputbuffer'] = 'Output buffer';
$string['phpvaroff'] = 'The PHP server variable \'{$a->name}\' should be Off - {$a->link}';
$string['phpvaron'] = 'The PHP server variable \'{$a->name}\' is not turned On - {$a->link}';
$string['reactive_instances'] = 'Reactive instances:';
$string['reactive_noinstances'] = 'this page has no reactive instances';
$string['reactive_pin'] = 'Pin';
$string['reactive_unpin'] = 'Unpin';
$string['reactive_highlightoff'] = 'Highlight OFF';
$string['reactive_highlighton'] = 'Highlight ON';
$string['reactive_readmodeon'] = 'Read mode ON';
$string['reactive_readmodeoff'] = 'Read mode OFF';
$string['reactive_resetpanel'] = 'Reset panel';
$string['reactive_statedata'] = 'State data';
$string['reactive_saveingwarning'] = 'Edit the state can cause inexpected results';
$string['sessionmissing'] = '{$a} object missing from session';
$string['sqlrelyonobsoletetable'] = 'This SQL relies on obsolete table(s): {$a}! Your code must be fixed by a developer.';
$string['stacktrace'] = 'Stack trace';
......
File suppressed by a .gitattributes entry or the file's encoding is unsupported.
File suppressed by a .gitattributes entry or the file's encoding is unsupported.
File suppressed by a .gitattributes entry or the file's encoding is unsupported.
File suppressed by a .gitattributes entry or the file's encoding is unsupported.
File suppressed by a .gitattributes entry or the file's encoding is unsupported.
File suppressed by a .gitattributes entry or the file's encoding is unsupported.
File suppressed by a .gitattributes entry or the file's encoding is unsupported.
File suppressed by a .gitattributes entry or the file's encoding is unsupported.
File suppressed by a .gitattributes entry or the file's encoding is unsupported.
File suppressed by a .gitattributes entry or the file's encoding is unsupported.
// 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/>.
/**
* Reactive module debug tools.
*
* @module core/reactive/local/reactive/debug
* @copyright 2021 Ferran Recio <ferran@moodle.com>
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
import Reactive from 'core/local/reactive/reactive';
import log from 'core/log';
// The list of reactives instances.
const reactiveInstances = {};
// The reactive debugging objects.
const reactiveDebuggers = {};
/**
* Reactive module debug tools.
*
* If debug is enabled, this reactive module will spy all the reactive instances and keep a record
* of the changes and components they have.
*
* It is important to note that the Debug class is also a Reactive module. The debug instance keeps
* the reactive instances data as its own state. This way it is possible to implement development tools
* that whatches this data.
*
* @class core/reactive/local/reactive/debug/Debug
* @copyright 2021 Ferran Recio <ferran@moodle.com>
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
class Debug extends Reactive {
/**
* Set the initial state.
*
* @param {object} stateData the initial state data.
*/
setInitialState(stateData) {
super.setInitialState(stateData);
log.debug(`Debug module "M.reactive" loaded.`);
}
/**
* List the currents page reactives instances.
*/
get list() {
return JSON.parse(JSON.stringify(this.state.reactives));
}
/**
* Register a new Reactive instance.
*
* This method is called every time a "new Reactive" is executed.
*
* @param {Reactive} instance the reactive instance
*/
registerNewInstance(instance) {
// Generate a valid variable name for that instance.
let name = instance.name ?? `instance${this.state.reactives.length}`;
name = name.replace(/\W/g, '');
log.debug(`Registering new reactive instance "M.reactive.${name}"`);
reactiveInstances[name] = instance;
reactiveDebuggers[name] = new DebugInstance(reactiveInstances[name]);
// Register also in the state.
this.dispatch('putInstance', name, instance);
// Add debug watchers to instance.
const refreshMethod = () => {
this.dispatch('putInstance', name, instance);
};
instance.target.addEventListener('readmode:on', refreshMethod);
instance.target.addEventListener('readmode:off', refreshMethod);
instance.target.addEventListener('registerComponent:success', refreshMethod);
instance.target.addEventListener('transaction:end', refreshMethod);
// We store the last transaction into the state.
const storeTransaction = ({detail}) => {
const changes = detail?.changes;
this.dispatch('lastTransaction', name, changes);
};
instance.target.addEventListener('transaction:start', storeTransaction);
}
/**
* Returns a debugging object for a specific Reactive instance.
*
* A debugging object is a class that wraps a Reactive instance to quick access some of the
* reactive methods using the browser JS console.
*
* @param {string} name the Reactive instance name
* @returns {DebugInstance} a debug object wrapping the Reactive instance
*/
debug(name) {
return reactiveDebuggers[name];
}
}
/**
* The debug state mutations class.
*
* @class core/reactive/local/reactive/debug/Mutations
*/
class Mutations {
/**
* Insert or update a new instance into the debug state.
*
* @param {StateManager} stateManager the debug state manager
* @param {string} name the instance name
* @param {Reactive} instance the reactive instance
*/
putInstance(stateManager, name, instance) {
const state = stateManager.state;
stateManager.setReadOnly(false);
if (state.reactives.has(name)) {
state.reactives.get(name).countcomponents = instance.components.length;
state.reactives.get(name).readOnly = instance.stateManager.readonly;
state.reactives.get(name).modified = new Date().getTime();
} else {
state.reactives.add({
id: name,
countcomponents: instance.components.length,
readOnly: instance.stateManager.readonly,
lastChanges: [],
modified: new Date().getTime(),
});
}
stateManager.setReadOnly(true);
}
/**
* Update the lastChanges attribute with a list of changes
*
* @param {StateManager} stateManager the debug reactive state
* @param {string} name tje instance name
* @param {array} changes the list of changes
*/
lastTransaction(stateManager, name, changes) {
if (!changes || changes.length === 0) {
return;
}
const state = stateManager.state;
const lastChanges = ['transaction:start'];
changes.forEach(change => {
lastChanges.push(change.eventName);
});
lastChanges.push('transaction:end');
stateManager.setReadOnly(false);
state.reactives.get(name).lastChanges = lastChanges;
stateManager.setReadOnly(true);
}
}
/**
* Class used to debug a specific instance and manipulate the state from the JS console.
*
* @class core/reactive/local/reactive/debug/DebugInstance
* @copyright 2021 Ferran Recio <ferran@moodle.com>
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
class DebugInstance {
/**
* Constructor.
*
* @param {Reactive} instance the reactive instance
*/
constructor(instance) {
this.instance = instance;
// Add some debug data directly into the instance. This way we avoid having attributes
// that will confuse the console aoutocomplete.
if (instance._reactiveDebugData === undefined) {
instance._reactiveDebugData = {
highlighted: false,
};
}
}
/**
* Set the read only mode.
*
* Quick access to the instance setReadOnly method.
*
* @param {bool} value: the new read only value
*/
set readOnly(value) {
this.instance.stateManager.setReadOnly(value);
}
/**
* Get the read only value
*
* @return {bool}
*/
get readOnly() {
return this.instance.stateManager.readonly;
}
/**
* Return the current state object.
*
* @return {object}
*/
get state() {
return this.instance.state;
}
/**
* Tooggle the reactive HTML element highlight registered in this reactive instance.
*
* @param {bool} value the highlight value
*/
set highlight(value) {
this.instance._reactiveDebugData.highlighted = value;
this.instance.components.forEach(({element}) => {
const border = (value) ? `thick solid #0000FF` : '';
element.style.border = border;
});
}
/**
* Get the current highligh value.
*
* @return {bool}
*/
get highlight() {
return this.instance._reactiveDebugData.highlighted;
}
/**
* List all the components registered in this instance.
*
* @return {array}
*/
get components() {
return [...this.instance.components];
}
/**
* List all the state changes evenet pending to dispatch.
*
* @return {array}
*/
get changes() {
const result = [];
this.instance.stateManager.eventsToPublish.forEach(
(element) => {
result.push(element.eventName);
}
);
return result;
}
/**
* Dispatch a change in the state.
*
* Usually reactive modules throw an error directly to the components when something
* goes wrong. However, course editor can directly display a notification.
*
* @method dispatch
* @param {string} actionName the action name (usually the mutation name)
* @param {*} param any number of params the mutation needs.
*/
async dispatch(...args) {
this.instance.dispatch(...args);
}
/**
* Return all the HTML elements registered in the instance components.
*
* @return {array}
*/
get elements() {
const result = [];
this.instance.components.forEach(({element}) => {
result.push(element);
});
return result;
}
/**
* Return a plain copy of the state data.
*
* @return {object}
*/
get stateData() {
return JSON.parse(JSON.stringify(this.state));
}
/**
* Process an update state array.
*
* @param {array} updates an array of update state messages
*/
processUpdates(updates) {
this.instance.stateManager.processUpdates(updates);
}
}
const stateChangedEventName = 'core_reactive_debug:stateChanged';
/**
* Internal state changed event.
*
* @method dispatchStateChangedEvent
* @param {object} detail the full state
* @param {object} target the custom event target (document if none provided)
*/
function dispatchStateChangedEvent(detail, target) {
if (target === undefined) {
target = document;
}
target.dispatchEvent(
new CustomEvent(
stateChangedEventName,
{
bubbles: true,
detail: detail,
}
)
);
}
/**
* The main init method to initialize the reactive debug.
* @returns {object}
*/
export const initDebug = () => {
const debug = new Debug({
name: 'CoreReactiveDebug',
eventName: stateChangedEventName,
eventDispatch: dispatchStateChangedEvent,
mutations: new Mutations(),
state: {
reactives: [],
},
});
// The reactiveDebuggers will be used as a way of access the debug instances but also to register every new
// instance. To ensure this will update the reactive debug state we add the registerNewInstance method to it.
reactiveDebuggers.registerNewInstance = debug.registerNewInstance.bind(debug);
return {
debug,
debuggers: reactiveDebuggers,
};
};
// 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/>.
/**
* Reactive module debug panel.
*
* This module contains all the UI components for the reactive debug tools.
* Those tools are only available if the debug is enables and could be used
* from the footer.
*
* @module core/local/reactive/debugpanel
* @copyright 2021 Ferran Recio <ferran@moodle.com>
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
import {BaseComponent, DragDrop, debug} from 'core/reactive';
import log from 'core/log';
import {debounce} from 'core/utils';
/**
* Init the main reactive panel.
*
* @param {element|string} target the DOM main element or its ID
* @param {object} selectors optional css selector overrides
*/
export const init = (target, selectors) => {
const element = document.getElementById(target);
// Check if the debug reactive module is available.
if (debug === undefined) {
element.remove();
return;
}
// Create the main component.
new GlobalDebugPanel({
element,
reactive: debug,
selectors,
});
};
/**
* Init an instance reactive subpanel.
*
* @param {element|string} target the DOM main element or its ID
* @param {object} selectors optional css selector overrides
*/
export const initsubpanel = (target, selectors) => {
const element = document.getElementById(target);
// Check if the debug reactive module is available.
if (debug === undefined) {
element.remove();
return;
}
// Create the main component.
new DebugInstanceSubpanel({
element,
reactive: debug,
selectors,
});
};
/**
* Component for the main reactive dev panel.
*
* This component shows the list of reactive instances and handle the buttons
* to open a specific instance panel.
*/
class GlobalDebugPanel extends BaseComponent {
/**
* Constructor hook.
*/
create() {
// Optional component name for debugging.
this.name = 'GlobalDebugPanel';
// Default query selectors.
this.selectors = {
LOADERS: `[data-for='loaders']`,
SUBPANEL: `[data-for='subpanel']`,
LOG: `[data-for='log']`,
};
}
/**
* Initial state ready method.
*
* @param {object} state the initial state
*/
stateReady(state) {
if (state.reactives.size > 0) {
this.getElement(this.selectors.LOADERS).innerHTML = '';
}
// Generate loading buttons.
state.reactives.forEach(
instance => {
this._createLoader(instance);
}
);
// Remove loading wheel.
this.getElement(this.selectors.SUBPANEL).innerHTML = '';
}
/**
* Create a debug panel button for a specific reactive instance.
*
* @param {object} instance hte instance data
*/
_createLoader(instance) {
const loaders = this.getElement(this.selectors.LOADERS);
const btn = document.createElement("button");
btn.innerHTML = instance.id;
btn.dataset.id = instance.id;
loaders.appendChild(btn);
// Add click event.
this.addEventListener(btn, 'click', () => this._openPanel(btn, instance));
}
/**
* Open a debug panel.
*
* @param {Element} btn the button element
* @param {object} instance the instance data
*/
async _openPanel(btn, instance) {
try {
const target = this.getElement(this.selectors.SUBPANEL);
const data = {...instance};
await this.renderComponent(target, 'core/local/reactive/debuginstancepanel', data);
} catch (error) {
log.error('Cannot load reactive debug subpanel');
throw error;
}
}
}
/**
* Component for the main reactive dev panel.
*
* This component shows the list of reactive instances and handle the buttons
* to open a specific instance panel.
*/
class DebugInstanceSubpanel extends BaseComponent {
/**
* Constructor hook.
*/
create() {
// Optional component name for debugging.
this.name = 'DebugInstanceSubpanel';
// Default query selectors.
this.selectors = {
NAME: `[data-for='name']`,
CLOSE: `[data-for='close']`,
READMODE: `[data-for='readmode']`,
HIGHLIGHT: `[data-for='highlight']`,
LOG: `[data-for='log']`,
STATE: `[data-for='state']`,
CLEAN: `[data-for='clean']`,
PIN: `[data-for='pin']`,
SAVE: `[data-for='save']`,
INVALID: `[data-for='invalid']`,
};
this.id = this.element.dataset.id;
this.controller = M.reactive[this.id];
// The component is created always pinned.
this.draggable = false;
// We want the element to be dragged like modal.
this.relativeDrag = true;
// Save warning (will be loaded when state is ready.
this.strings = {
savewarning: '',
};
}
/**
* Initial state ready method.
*
*/
stateReady() {
// Enable drag and drop.
this.dragdrop = new DragDrop(this);
// Close button.
this.addEventListener(
this.getElement(this.selectors.CLOSE),