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

/**

 * Javascript events for the `core_form` subsystem.

 *

 * @module core_form/events

 * @copyright 2021 Huong Nguyen <huongnv13@gmail.com>

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

 * @since 3.10

 *

 * @example <caption>Example of listening to a form event.</caption>

 * import {eventTypes as formEventTypes} from 'core_form/events';

 *

 * document.addEventListener(formEventTypes.formSubmittedByJavascript, e => {

 *     window.console.log(e.target); // The form that was submitted.

 *     window.console.log(e.detail.skipValidation); // Whether form validation was skipped.

 * });

 */

import {getString} from 'core/str';

import {dispatchEvent} from 'core/event_dispatcher';

let changesMadeString;

/**

 * Prevent user navigate away when upload progress still running.

 * @param {Event} e The event

 */

const changesMadeCheck = e => {

    if (e) {

        e.returnValue = changesMadeString;

    }

};

/**

 * Events for `core_form`.

 *

 * @constant

 * @property {String} formError See {@link event:core_form/error}

 * @property {String} formFieldValidationFailed See {@link event:core_form/fieldValidationFailed}

 * @property {String} formSubmittedByJavascript See {@link event:core_form/submittedByJavascript}

 * @property {String} uploadChanged See {@link event:core_form/uploadChanged}

 * @property {String} fieldStructureChanged See {@link event:core_form/fieldStructureChanged}

 */

export const eventTypes = {

    /**

     * An event triggered when a form contains an error

     *

     * @event formError

     * @type {CustomEvent}

     * @property {HTMLElement} target The form field which errored

     */

    formError: 'core_form/error',

    /**

     * An event triggered when an mform is about to be submitted via javascript.

     *

     * @event core_form/submittedByJavascript

     * @type {CustomEvent}

     * @property {HTMLElement} target The form that was submitted

     * @property {object} detail

     * @property {boolean} detail.skipValidation Whether the form was submitted without validation (i.e. via a Cancel button)

     * @property {boolean} detail.fallbackHandled Whether the legacy YUI event has been handled

     */

    formSubmittedByJavascript: 'core_form/submittedByJavascript',

    /**

     * An event triggered upon form field validation failure.

     *

     * @event core_form/fieldValidationFailed

     * @type {CustomEvent}

     * @property {HTMLElement} target The field that failed validation

     * @property {object} detail

     * @property {String} detail.message The message displayed upon failure

     */

    formFieldValidationFailed: 'core_form/fieldValidationFailed',

    /**

     * An event triggered when an upload is started

     *

     * @event core_form/uploadStarted

     * @type {CustomEvent}

     * @property {HTMLElement} target The location where the upload began

     */

    uploadStarted: 'core_form/uploadStarted',

    /**

     * An event triggered when an upload completes

     *

     * @event core_form/uploadCompleted

     * @type {CustomEvent}

     * @property {HTMLElement} target The location where the upload completed

     */

    uploadCompleted: 'core_form/uploadCompleted',

    /**

     * An event triggered when a file upload field has been changed.

     *

     * @event core_form/uploadChanged

     * @type {CustomEvent}

     * @property {HTMLElement} target The form field which was changed

     */

    uploadChanged: 'core_form/uploadChanged',

    /**

     * An event triggered when a form field structure has changed.

     *

     * @event core_form/fieldStructureChanged

     * @type {CustomEvent}

     * @property {HTMLElement} target The form field that has changed

     */

    fieldStructureChanged: 'core_form/fieldStructureChanged',

};

// These are only imported for legacy.

import jQuery from 'jquery';

import Y from 'core/yui';

/**

 * Trigger an event to indicate that a form field contained an error.

 *

 * @method notifyFormError

 * @param {HTMLElement} field The form field causing the error

 * @returns {CustomEvent}

 * @fires formError

 */

export const notifyFormError = field => dispatchEvent(eventTypes.formError, {}, field);

/**

 * Trigger an event to indiciate that a form was submitted by Javascript.

 *

 * @method

 * @param {HTMLElement} form The form that was submitted

 * @param {Boolean} skipValidation Submit the form without validation. E.g. "Cancel".

 * @param {Boolean} fallbackHandled The legacy YUI event has been handled

 * @returns {CustomEvent}

 * @fires formSubmittedByJavascript

 */

export const notifyFormSubmittedByJavascript = (form, skipValidation = false, fallbackHandled = false) => {

    if (skipValidation) {

        window.skipClientValidation = true;

    }

    const customEvent = dispatchEvent(

        eventTypes.formSubmittedByJavascript,

        {

            skipValidation,

            fallbackHandled,

        },

        form

    );

    if (skipValidation) {

        window.skipClientValidation = false;

    }

    return customEvent;

};

/**

 * Trigger an event to indicate that a form field contained an error.

 *

 * @method notifyFieldValidationFailure

 * @param {HTMLElement} field The field which failed validation

 * @param {String} message The message displayed

 * @returns {CustomEvent}

 * @fires formFieldValidationFailed

 */

export const notifyFieldValidationFailure = (field, message) => dispatchEvent(

    eventTypes.formFieldValidationFailed,

    {

        message,

    },

    field,

    {

        cancelable: true

    }

);

/**

 * Trigger an event to indicate that an upload was started.

 *

 * @method

 * @param {String} elementId The element which was uploaded to

 * @returns {CustomEvent}

 * @fires uploadStarted

 */

export const notifyUploadStarted = async elementId => {

    // Add an additional check for changes made.

    changesMadeString = await getString('changesmadereallygoaway', 'moodle');

    window.addEventListener('beforeunload', changesMadeCheck);

    return dispatchEvent(

        eventTypes.uploadStarted,

        {},

        document.getElementById(elementId),

        {

            bubbles: true,

            cancellable: false,

        }

    );

};

/**

 * Trigger an event to indicate that an upload was completed.

 *

 * @method

 * @param {String} elementId The element which was uploaded to

 * @returns {CustomEvent}

 * @fires uploadCompleted

 */

export const notifyUploadCompleted = elementId => {

    // Remove the additional check for changes made.

    window.removeEventListener('beforeunload', changesMadeCheck);

    return dispatchEvent(

        eventTypes.uploadCompleted,

        {},

        document.getElementById(elementId),

        {

            bubbles: true,

            cancellable: false,

        }

    );

};

/**

 * Trigger upload start event.

 *

 * @method

 * @param {String} elementId

 * @returns {CustomEvent}

 * @fires uploadStarted

 * @deprecated Since Moodle 4.0 See {@link module:core_form/events.notifyUploadStarted notifyUploadStarted}

 */

export const triggerUploadStarted = notifyUploadStarted;

/**

 * Trigger upload complete event.

 *

 * @method

 * @param {String} elementId

 * @returns {CustomEvent}

 * @fires uploadCompleted

 * @deprecated Since Moodle 4.0 See {@link module:core_form/events.notifyUploadCompleted notifyUploadCompleted}

 */

export const triggerUploadCompleted = notifyUploadCompleted;

/**

 * List of the events.

 *

 * @deprecated since Moodle 4.0. See {@link module:core_form/events.eventTypes eventTypes} instead.

 **/

export const types = {

    uploadStarted: 'core_form/uploadStarted',

    uploadCompleted: 'core_form/uploadCompleted',

};

let legacyEventsRegistered = false;

if (!legacyEventsRegistered) {

    // The following event triggers are legacy and will be removed in the future.

    // The following approach provides a backwards-compatability layer for the new events.

    // Code should be updated to make use of native events.

    Y.use('event', 'moodle-core-event', () => {

        // Watch for the new native formError event, and trigger the legacy YUI event.

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

            const element = Y.one(e.target);

            const formElement = Y.one(e.target.closest('form'));

            Y.Global.fire(

                M.core.globalEvents.FORM_ERROR,

                {

                    formid: formElement.generateID(),

                    elementid: element.generateID(),

                }

            );

        });

        // Watch for the new native formSubmittedByJavascript event, and trigger the legacy YUI event.

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

            if (e.detail.fallbackHandled) {

                // This event was originally generated by a YUI event.

                // Do not generate another as this will recurse.

                return;

            }

            if (e.skipValidation) {

                window.skipClientValidation = true;

            }

            // Trigger the legacy YUI event.

            const form = Y.one(e.target);

            form.fire(

                M.core.event.FORM_SUBMIT_AJAX,

                {

                    currentTarget: form,

                    fallbackHandled: true,

                }

            );

            if (e.skipValidation) {

                window.skipClientValidation = false;

            }

        });

    });

    // Watch for the new native formFieldValidationFailed event, and trigger the legacy jQuery event.

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

        // Note: The "core_form-field-validation" event is hard-coded in core/event.

        // This is not included to prevent cyclic module dependencies.

        const legacyEvent = jQuery.Event("core_form-field-validation");

        jQuery(e.target).trigger(legacyEvent, e.detail.message);

    });

    legacyEventsRegistered = true;

}

/**

 * Trigger an event to notify the file upload field has been changed.

 *

 * @method

 * @param {string} elementId The element which was changed

 * @returns {CustomEvent}

 * @fires uploadChanged

 */

export const notifyUploadChanged = elementId => dispatchEvent(

    eventTypes.uploadChanged,

    {},

    document.getElementById(elementId),

    {

        bubbles: true,

        cancellable: false,

    }

);

/**

 * Trigger an event to notify the field structure has changed.

 *

 * @method

 * @param {string} elementId The element which was changed

 * @returns {CustomEvent}

 * @fires fieldStructureChanged

 */

export const notifyFieldStructureChanged = elementId => dispatchEvent(

    eventTypes.fieldStructureChanged,

    {},

    document.getElementById(elementId),

    {

        bubbles: true,

        cancellable: false,

    }

);