Merge branch 'MDL-83869-main' of https://github.com/ferranrecio/moodle

2025-01-23 11:15:26 +07:00
parent 2beee5c41e 53886acba6
commit 5fbd4b6555
13 changed files with 1031 additions and 0 deletions
@@ -0,0 +1,138 @@
+// 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/>.
+
+/**
+ * The collapsable sections controls.
+ *
+ * @module     core/local/collapsable_section/controls
+ * @copyright  2024 Ferran Recio <[email protected]>
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ *
+ * @example <caption>Example of controlling a collapsable section.</caption>
+ *
+ * import CollapsableSection from 'core/local/collapsable_section/controls';
+ *
+ * const section = CollapsableSection.instanceFromSelector('#MyCollapsableSection');
+ *
+ * // Use hide, show and toggle methods to control the section.
+ * section.hide();
+ */
+
+import {
+    eventTypes,
+    notifyCollapsableSectionHidden,
+    notifyCollapsableSectionShown
+} from 'core/local/collapsable_section/events';
+
+// The jQuery module is only used for interacting with Boostrap 4. It can we removed when MDL-71979 is integrated.
+import jQuery from 'jquery';
+
+let initialized = false;
+
+export default class {
+    /**
+     * Create a new instance from a query selector.
+     *
+     * @param {String} selector The selector of the collapsable section.
+     * @return {CollapsableSection} The collapsable section controls.
+     * @throws {Error} If no elements are found with the selector.
+     */
+    static instanceFromSelector(selector) {
+        const elements = document.querySelector(selector);
+        if (!elements) {
+            throw new Error('No elements found with the selector: ' + selector);
+        }
+        return new this(elements);
+    }
+
+    /**
+     * Initialize the collapsable section controls.
+     */
+    static init() {
+        if (initialized) {
+            return;
+        }
+        initialized = true;
+
+        // We want to add extra events to the standard bootstrap collapsable events.
+        // TODO: change all jquery events to custom events once MDL-71979 is integrated.
+        jQuery(document).on(eventTypes.hiddenBsCollapse, event => {
+            if (!this.isCollapsableComponent(event.target)) {
+                return;
+            }
+            notifyCollapsableSectionHidden(event.target);
+        });
+        jQuery(document).on(eventTypes.shownBsCollapse, event => {
+            if (!this.isCollapsableComponent(event.target)) {
+                return;
+            }
+            notifyCollapsableSectionShown(event.target);
+        });
+    }
+
+    /**
+     * Check if the element is a collapsable section.
+     *
+     * @private
+     * @param {HTMLElement} element The element to check.
+     * @return {boolean} True if the element is a collapsable section.
+     */
+    static isCollapsableComponent(element) {
+        return element.hasAttribute('data-mdl-component')
+            && element.getAttribute('data-mdl-component') === 'core/local/collapsable_section';
+    }
+
+    /**
+     * Creates an instance of the controls for a collapsable section.
+     *
+     * @param {HTMLElement} element - The DOM element that this control will manage.
+     */
+    constructor(element) {
+        this.element = element;
+    }
+
+    /**
+     * Hides the collapsible section element.
+     */
+    hide() {
+        // TODO: change all jquery once MDL-71979 is integrated.
+        jQuery(this.element).collapse('hide');
+    }
+
+    /**
+     * Shows the collapsible section element.
+     */
+    show() {
+        // TODO: change all jquery once MDL-71979 is integrated.
+        jQuery(this.element).collapse('show');
+    }
+
+    /**
+     * Toggle the collapsible section element.
+     */
+    toggle() {
+        // TODO: change all jquery once MDL-71979 is integrated.
+        jQuery(this.element).collapse('toggle');
+    }
+
+    /**
+     * Check if the collapsable section is visible.
+     *
+     * @return {boolean} True if the collapsable section is visible.
+     */
+    isVisible() {
+        return this.element.classList.contains('show');
+    }
+}
@@ -0,0 +1,86 @@
+// 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/>.
+
+/**
+ * The collapsable section events.
+ *
+ * This module wraps the standard bootstrap collapsable events, but for collapsable sections.
+ *
+ * @module     core/local/collapsable_section/events
+ * @copyright  2024 Ferran Recio <[email protected]>
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ *
+ * @example <caption>Example of listening to a collapsable section events.</caption>
+ * import {eventTypes as collapsableSectionEventTypes} from 'core/local/collapsable_section/events';
+ *
+ * document.addEventListener(collapsableSectionEventTypes.shown, event => {
+ *     window.console.log(event.target); // The HTMLElement relating to the block whose content was updated.
+ * });
+ */
+
+import {dispatchEvent} from 'core/event_dispatcher';
+
+/**
+ * Events for `core_block`.
+ *
+ * @constant
+ * @property {String} blockContentUpdated See {@link event:blockContentUpdated}
+ */
+export const eventTypes = {
+    /**
+     * An event triggered when the content of a block has changed.
+     *
+     * @event blockContentUpdated
+     * @type {CustomEvent}
+     * @property {HTMLElement} target The block element that was updated
+     * @property {object} detail
+     * @property {number} detail.instanceId The block instance id
+     */
+    shown: 'core_collapsable_section_shown',
+    hidden: 'core_collapsable_section_hidden',
+    // All Bootstrap 4 jQuery events are wrapped while MDL-71979 is not integrated.
+    hideBsCollapse: 'hide.bs.collapse',
+    hiddenBsCollapse: 'hidden.bs.collapse',
+    showBsCollapse: 'show.bs.collapse',
+    shownBsCollapse: 'shown.bs.collapse',
+};
+
+/**
+ * Trigger an event to indicate that the content of a block was updated.
+ *
+ * @method notifyBlockContentUpdated
+ * @param {HTMLElement} element The HTMLElement containing the updated block.
+ * @returns {CustomEvent}
+ * @fires blockContentUpdated
+ */
+export const notifyCollapsableSectionShown = element => dispatchEvent(
+    eventTypes.shown,
+    {},
+    element
+);
+
+/**
+ * Trigger an event to indicate that the content of a block was updated.
+ *
+ * @method notifyBlockContentUpdated
+ * @param {HTMLElement} element The HTMLElement containing the updated block.
+ * @returns {CustomEvent}
+ * @fires blockContentUpdated
+ */
+export const notifyCollapsableSectionHidden = element => dispatchEvent(
+    eventTypes.hidden,
+    {},
+    element
+);