lib/amd/src/event_dispatcher.js

  1. // This file is part of Moodle - http://moodle.org/ //
  2. // Moodle is free software: you can redistribute it and/or modify
  3. // it under the terms of the GNU General Public License as published by
  4. // the Free Software Foundation, either version 3 of the License, or
  5. // (at your option) any later version.
  6. //
  7. // Moodle is distributed in the hope that it will be useful,
  8. // but WITHOUT ANY WARRANTY; without even the implied warranty of
  9. // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  10. // GNU General Public License for more details.
  11. //
  12. // You should have received a copy of the GNU General Public License
  13. // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
  15. /**
  16.  * An Event dispatcher used to dispatch Native JS CustomEvent objects with custom default properties.
  17.  *
  18.  * @module     core/event_dispatcher
  19.  * @copyright  2021 Andrew Nicols <andrew@nicols.co.uk>
  20.  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  21.  * @since      4.0
  22.  */
  24. /**
  25.  * Dispatch an event as a CustomEvent on the specified container.
  26.  * By default events are bubbled, and cancelable.
  27.  *
  28.  * The eventName should typically by sourced using a constant. See the supplied examples.
  29.  *
  30.  * Note: This function uses native events. Any additional details are passed to the function in event.detail.
  31.  *
  32.  * This function mimics the behaviour of EventTarget.dispatchEvent but bubbles by default.
  33.  *
  34.  * @method dispatchEvent
  35.  * @param {String} eventName The name of the event
  36.  * @param {Object} detail Any additional details to pass into the eveent
  37.  * @param {HTMLElement} container The point at which to dispatch the event
  38.  * @param {Object} options
  39.  * @param {Boolean} options.bubbles Whether to bubble up the DOM
  40.  * @param {Boolean} options.cancelable Whether preventDefault() can be called
  41.  * @param {Boolean} options.composed Whether the event can bubble across the ShadowDOM bounadry
  42.  * @returns {CustomEvent}
  43.  *
  44.  * @example <caption>Using a native CustomEvent to indicate that some example data was displayed.</caption>
  45.  * // mod/example/amd/src/events.js
  46.  *
  47.  * import {dispatchEvent} from 'core/event_dispatcher';
  48.  *
  49.  * export const eventTypes = {
  50.  *     exampleDataDisplayed: 'mod_example/exampleDataDisplayed',
  51.  * };
  52.  *
  53.  * export const notifyExampleDisplayed = someArgument => dispatchEvent(eventTypes.exampleDataDisplayed, {
  54.  *     someArgument,
  55.  * }, document, {
  56.  *     cancelable: false,
  57.  * });
  58.  */
  59. export const dispatchEvent = (
  60.     eventName,
  61.     detail = {},
  62.     container = document,
  63.     {
  64.         bubbles = true,
  65.         cancelable = false,
  66.         composed = false,
  67.     } = {}
  68. ) => {
  69.     const customEvent = new CustomEvent(
  70.         eventName,
  71.         {
  72.             bubbles,
  73.             cancelable,
  74.             composed,
  75.             detail,
  76.         }
  77.     );
  79.     container.dispatchEvent(customEvent);
  81.     return customEvent;
  82. };