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

/**

 * This module provides change detection to forms, allowing a browser to warn the user before navigating away if changes

 * have been made.

 *

 * Two flags are stored for each form:

 * * a 'dirty' flag; and

 * * a 'submitted' flag.

 *

 * When the page is unloaded each watched form is checked. If the 'dirty' flag is set for any form, and the 'submitted'

 * flag is not set for any form, then a warning is shown.

 *

 * The 'dirty' flag is set when any form element is modified within a watched form.

 * The flag can also be set programatically. This may be required for custom form elements.

 *

 * It is not possible to customise the warning message in any modern browser.

 *

 * Please note that some browsers have controls on when these alerts may or may not be shown.

 * See {@link https://developer.mozilla.org/en-US/docs/Web/API/WindowEventHandlers/onbeforeunload} for browser-specific

 * notes and references.

 *

 * @module     core_form/changechecker

 * @copyright  2021 Andrew Lyons <andrew@nicols.co.uk>

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

 * @example <caption>Usage where the FormElement is already held</caption>

 *

 * import {watchForm} from 'core_form/changechecker';

 *

 * // Fetch the form element somehow.

 * watchForm(formElement);

 *

 * @example <caption>Usage from the child of a form - i.e. an input, button, div, etc.</caption>

 *

 * import {watchForm} from 'core_form/changechecker';

 *

 * // Watch the form by using a child of it.

 * watchForm(document.querySelector('input[data-foo="bar"]'););

 *

 * @example <caption>Usage from within a template</caption>

 * <form id="mod_example-entry-{{uniqid}}" ...>

 *   <!--

 *

 *   -->

 * </form>

 * {{#js}}

 * require(['core_form/changechecker'], function(changeChecker) {

 *     watchFormById('mod_example-entry-{{uniqid}}');

 * });

 * {{/js}}

 */

import {eventTypes} from 'core_editor/events';

import {getString} from 'core/str';

/**

 * @property {Bool} initialised Whether the change checker has been initialised

 * @private

 */

let initialised = false;

/**

 * @property {String} warningString The warning string to show on form change failure

 * @private

 */

let warningString;

/**

 * @property {Array} watchedForms The list of watched forms

 * @private

 */

let watchedForms = [];

/**

 * @property {Bool} formChangeCheckerDisabled Whether the form change checker has been actively disabled

 * @private

 */

let formChangeCheckerDisabled = false;

/**

 * Get the nearest form element from a child element.

 *

 * @param {HTMLElement} formChild

 * @returns {HTMLFormElement|null}

 * @private

 */

const getFormFromChild = formChild => formChild.closest('form');

/**

 * Watch the specified form for changes.

 *

 * @method

 * @param   {HTMLElement} formNode

 */

export const watchForm = formNode => {

    // Normalise the formNode.

    formNode = getFormFromChild(formNode);

    if (!formNode) {

         // No form found.

         return;

    }

    if (isWatchingForm(formNode)) {

        // This form is already watched.

        return;

    }

    watchedForms.push(formNode);

};

/**

 * Stop watching the specified form for changes.

 *

 * If the form was not watched, then no change is made.

 *

 * A child of the form may be passed instead.

 *

 * @method

 * @param   {HTMLElement} formNode

 * @example <caption>Stop watching a form for changes</caption>

 * import {unWatchForm} from 'core_form/changechecker';

 *

 * // ...

 * document.addEventListener('click', e => {

 *     if (e.target.closest('[data-action="changePage"]')) {

 *         unWatchForm(e.target);

 *     }

 * });

 */

export const unWatchForm = formNode => {

    watchedForms = watchedForms.filter(watchedForm => !!watchedForm.contains(formNode));

};

/**

 * Reset the 'dirty' flag for all watched forms.

 *

 * If a form was previously marked as 'dirty', then this flag will be cleared and when the page is unloaded no warning

 * will be shown.

 *

 * @method

 */

export const resetAllFormDirtyStates = () => {

    watchedForms.forEach(watchedForm => {

        watchedForm.dataset.formSubmitted = "false";

        watchedForm.dataset.formDirty = "false";

    });

};

/**

 * Reset the 'dirty' flag of the specified form.

 *

 * @method

 * @param   {HTMLElement} formNode

 */

export const resetFormDirtyState = formNode => {

    formNode = getFormFromChild(formNode);

    if (!formNode) {

         return;

    }

    formNode.dataset.formSubmitted = "false";

    formNode.dataset.formDirty = "false";

};

/**

 * Mark all forms as dirty.

 *

 * This function is only for backwards-compliance with the old YUI module and should not be used in any other situation.

 * It will be removed in Moodle 4.4.

 *

 * @method

 */

export const markAllFormsAsDirty = () => {

    watchedForms.forEach(watchedForm => {

        watchedForm.dataset.formDirty = "true";

    });

};

/**

 * Mark a specific form as dirty.

 *

 * This behaviour may be required for custom form elements which are not caught by the standard change listeners.

 *

 * @method

 * @param   {HTMLElement} formNode

 */

export const markFormAsDirty = formNode => {

    formNode = getFormFromChild(formNode);

    if (!formNode) {

         return;

    }

    // Mark it as dirty.

    formNode.dataset.formDirty = "true";

};

/**

 * Actively disable the form change checker.

 *

 * Please note that it cannot be re-enabled once disabled.

 *

 * @method

 */

export const disableAllChecks = () => {

    formChangeCheckerDisabled = true;

};

/**

 * Check whether any watched from is dirty.

 *

 * @method

 * @returns {Bool}

 */

export const isAnyWatchedFormDirty = () => {

    if (formChangeCheckerDisabled) {

        // The form change checker is disabled.

        return false;

    }

    const hasSubmittedForm = watchedForms.some(watchedForm => watchedForm.dataset.formSubmitted === "true");

    if (hasSubmittedForm) {

        // Do not warn about submitted forms, ever.

        return false;

    }

    const hasDirtyForm = watchedForms.some(watchedForm => {

        if (!watchedForm.isConnected) {

            // The watched form is not connected to the DOM.

            return false;

        }

        if (watchedForm.dataset.formDirty === "true") {

            // The form has been marked as dirty.

            return true;

        }

        // Elements currently holding focus will not have triggered change detection.

        // Check whether the value matches the original value upon form load.

        if (document.activeElement && document.activeElement.dataset.propertyIsEnumerable('initialValue')) {

            const isActiveElementWatched = isWatchingForm(document.activeElement)

                && !shouldIgnoreChangesForNode(document.activeElement);

            const hasValueChanged = document.activeElement.dataset.initialValue !== document.activeElement.value;

            if (isActiveElementWatched && hasValueChanged) {

                return true;

            }

        }

        return false;

    });

    if (hasDirtyForm) {

        // At least one form is dirty.

        return true;

    }

    // Handle TinyMCE editor instances.

    // TinyMCE forms may not have been initialised at the time that startWatching is called.

    // Check whether any tinyMCE editor is dirty.

    if (typeof window.tinyMCE !== 'undefined' && window.tinyMCE.editors) {

        if (window.tinyMCE.editors.some(editor => editor.isDirty())) {

            return true;

        }

    }

    // No dirty forms detected.

    return false;

};

/**

 * Get the watched form for the specified target.

 *

 * @method

 * @param   {HTMLNode} target

 * @returns {HTMLFormElement}

 * @private

 */

const getFormForNode = target => watchedForms.find(watchedForm => watchedForm.contains(target));

/**

 * Whether the specified target is a watched form.

 *

 * @method

 * @param   {HTMLNode} target

 * @returns {Bool}

 * @private

 */

const isWatchingForm = target => watchedForms.some(watchedForm => watchedForm.contains(target));

/**

 * Whether the specified target should ignore changes or not.

 *

 * @method

 * @param   {HTMLNode} target

 * @returns {Bool}

 * @private

 */

const shouldIgnoreChangesForNode = target => !!target.closest('.ignoredirty');

/**

 * Mark a form as changed.

 *

 * @method

 * @param   {HTMLElement} changedNode An element in the form which was changed

 */

export const markFormChangedFromNode = changedNode => {

    if (changedNode.dataset.formChangeCheckerOverride) {

        // Changes to this form node disable the form change checker entirely.

        // This is intended for select fields which cause an immediate redirect.

        disableAllChecks();

        return;

    }

    if (!isWatchingForm(changedNode)) {

        return;

    }

    if (shouldIgnoreChangesForNode(changedNode)) {

        return;

    }

    // Mark the form as dirty.

    const formNode = getFormForNode(changedNode);

    formNode.dataset.formDirty = "true";

};

/**

 * Mark a form as submitted.

 *

 * @method

 * @param   {HTMLElement} formNode An element in the form to mark as submitted

 */

export const markFormSubmitted = formNode => {

    formNode = getFormFromChild(formNode);

    if (!formNode) {

         return;

    }

    formNode.dataset.formSubmitted = "true";

};

/**

 * Mark all forms as submitted.

 *

 * This function is only for backwards-compliance with the old YUI module and should not be used in any other situation.

 * It will be removed in Moodle 4.4.

 *

 * @method

 */

export const markAllFormsSubmitted = () => {

    watchedForms.forEach(watchedForm => markFormSubmitted(watchedForm));

};

/**

 * Handle the beforeunload event.

 *

 * @method

 * @param   {Event} e

 * @returns {string|null}

 * @private

 */

const beforeUnloadHandler = e => {

    // Please note: The use of Promises in this function is forbidden.

    // This is an event handler and _cannot_ be asynchronous.

    let warnBeforeUnload = isAnyWatchedFormDirty() && !M.cfg.behatsiterunning;

    if (warnBeforeUnload) {

        // According to the specification, to show the confirmation dialog an event handler should call preventDefault()

        // on the event.

        e.preventDefault();

        // However note that not all browsers support this method, and some instead require the event handler to

        // implement one of two legacy methods:

        // * assigning a string to the event's returnValue property; and

        // * returning a string from the event handler.

        // Assigning a string to the event's returnValue property.

        e.returnValue = warningString;

        // Returning a string from the event handler.

        return e.returnValue;

    }

    // Attaching an event handler/listener to window or document's beforeunload event prevents browsers from using

    // in-memory page navigation caches, like Firefox's Back-Forward cache or WebKit's Page Cache.

    // Remove the handler.

    window.removeEventListener('beforeunload', beforeUnloadHandler);

    return null;

};

/**

 * Start watching for form changes.

 *

 * This function is called on module load, and should not normally be called.

 *

 * @method

 * @protected

 */

export const startWatching = () => {

    if (initialised) {

        return;

    }

    document.addEventListener('change', e => {

        if (!isWatchingForm(e.target)) {

            return;

        }

        markFormChangedFromNode(e.target);

    });

    document.addEventListener('click', e => {

        const ignoredButton = e.target.closest('[data-formchangechecker-ignore-submit]');

        if (!ignoredButton) {

            return;

        }

        const ownerForm = getFormFromChild(e.target);

        if (ownerForm) {

            ownerForm.dataset.ignoreSubmission = "true";

        }

    });

    document.addEventListener('focusin', e => {

        if (e.target.matches('input, textarea, select')) {

            if (e.target.dataset.propertyIsEnumerable('initialValue')) {

                // The initial value has already been set.

                return;

            }

            e.target.dataset.initialValue = e.target.value;

        }

    });

    document.addEventListener('submit', e => {

        const formNode = getFormFromChild(e.target);

        if (!formNode) {

            // Weird, but watch for this anyway.

            return;

        }

        if (formNode.dataset.ignoreSubmission) {

            // This form was submitted by a button which requested that the form checked should not mark it as submitted.

            formNode.dataset.ignoreSubmission = "false";

            return;

        }

        markFormSubmitted(formNode);

    });

    document.addEventListener(eventTypes.editorContentRestored, e => {

        if (e.target != document) {

            resetFormDirtyState(e.target);

        } else {

            resetAllFormDirtyStates();

        }

    });

    getString('changesmadereallygoaway', 'moodle')

    .then(changesMadeString => {

        warningString = changesMadeString;

        return;

    })

    .catch();

    window.addEventListener('beforeunload', beforeUnloadHandler);

};

/**

 * Watch the form matching the specified ID for changes.

 *

 * @method

 * @param   {String} formId

 */

export const watchFormById = formId => {

    watchForm(document.getElementById(formId));

};

/**

 * Reset the dirty state of the form matching the specified ID..

 *

 * @method

 * @param   {String} formId

 */

export const resetFormDirtyStateById = formId => {

    resetFormDirtyState(document.getElementById(formId));

};

/**

 * Mark the form matching the specified ID as dirty.

 *

 * @method

 * @param   {String} formId

 */

export const markFormAsDirtyById = formId => {

    markFormAsDirty(document.getElementById(formId));

};

// Configure all event listeners.

startWatching();