lib/amd/src/bulkactions/bulk_actions.js

  1. // This file is part of Moodle - http://moodle.org/
  2. //
  3. // Moodle is free software: you can redistribute it and/or modify
  4. // it under the terms of the GNU General Public License as published by
  5. // the Free Software Foundation, either version 3 of the License, or
  6. // (at your option) any later version.
  7. //
  8. // Moodle is distributed in the hope that it will be useful,
  9. // but WITHOUT ANY WARRANTY; without even the implied warranty of
  10. // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  11. // GNU General Public License for more details.
  12. //
  13. // You should have received a copy of the GNU General Public License
  14. // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
  16. import Templates from 'core/templates';
  17. import {get_string as getString} from 'core/str';
  18. import {disableStickyFooter, enableStickyFooter} from 'core/sticky-footer';
  20. /**
  21.  * Base class for defining a bulk actions area within a page.
  22.  *
  23.  * @module     core/bulkactions/bulk_actions
  24.  * @copyright  2023 Mihail Geshoski <mihail@moodle.com>
  25.  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  26.  */
  28. /** @constant {Object} The object containing the relevant selectors. */
  29. const Selectors = {
  30.     stickyFooterContainer: '#sticky-footer',
  31.     selectedItemsCountContainer: '[data-type="bulkactions"] [data-for="bulkcount"]',
  32.     cancelBulkActionModeElement: '[data-type="bulkactions"] [data-action="bulkcancel"]',
  33.     bulkModeContainer: '[data-type="bulkactions"]',
  34.     bulkActionsContainer: '[data-type="bulkactions"] [data-for="bulktools"]'
  35. };
  37. export default class BulkActions {
  39.     /** @property {string|null} initialStickyFooterContent The initial content of the sticky footer. */
  40.     initialStickyFooterContent = null;
  42.     /** @property {Array} selectedItems The array of selected item elements. */
  43.     selectedItems = [];
  45.     /** @property {boolean} isBulkActionsModeEnabled Whether the bulk actions mode is enabled. */
  46.     isBulkActionsModeEnabled = false;
  48.     /**
  49.      * @property {int} maxButtons Sets the maximum number of action buttons to display. If exceeded, additional actions
  50.      *                            are shown in a dropdown menu.
  51.      */
  52.     maxButtons = 5;
  54.     /**
  55.      * The class constructor.
  56.      *
  57.      * @param {int|null} maxButtons Sets the maximum number of action buttons to display. If exceeded, additional actions
  58.      *                              are shown in a dropdown menu.
  59.      * @returns {void}
  60.      */
  61.     constructor(maxButtons = null) {
  62.         if (!this.getStickyFooterContainer()) {
  63.             throw new Error('Sticky footer not found.');
  64.         }
  65.         // Store any pre-existing content in the sticky footer. When bulk actions mode is enabled, this content will be
  66.         // replaced with the bulk actions content and restored when bulk actions mode is disabled.
  67.         this.initialStickyFooterContent = this.getStickyFooterContainer().innerHTML;
  68.         if (maxButtons) {
  69.             this.maxButtons = maxButtons;
  70.         }
  71.         // Register and handle the item select change event.
  72.         this.registerItemSelectChangeEvent(async() => {
  73.             this.selectedItems = this.getSelectedItems();
  74.             if (this.selectedItems.length > 0) { // At least one item is selected.
  75.                 // If the bulk actions mode is already enabled only update the selected items count.
  76.                 if (this.isBulkActionsModeEnabled) {
  77.                     await this.updateBulkItemSelection();
  78.                 } else { // Otherwise, enable the bulk action mode.
  79.                     await this.enableBulkActionsMode();
  80.                 }
  81.             } else { // No items are selected, disable the bulk action mode.
  82.                 this.disableBulkActionsMode();
  83.             }
  84.         });
  85.     }
  87.     /**
  88.      * Returns the array of the relevant bulk action objects.
  89.      *
  90.      * @method getBulkActions
  91.      * @returns {Array}
  92.      */
  93.     getBulkActions() {
  94.         throw new Error(`getBulkActions() must be implemented in ${this.constructor.name}`);
  95.     }
  97.     /**
  98.      * Returns the array of selected items.
  99.      *
  100.      * @method getSelectedItems
  101.      * @returns {Array}
  102.      */
  103.     getSelectedItems() {
  104.         throw new Error(`getSelectedItems() must be implemented in ${this.constructor.name}`);
  105.     }
  107.     /**
  108.      * Adds the listener for the item select change event.
  109.      * The event handler function that is passed as a parameter should be called right after the event is triggered.
  110.      *
  111.      * @method registerItemSelectChangeEvent
  112.      * @param {function} eventHandler The event handler function.
  113.      * @returns {void}
  114.      */
  115.     registerItemSelectChangeEvent(eventHandler) {
  116.         throw new Error(`registerItemSelectChangeEvent(${eventHandler}) must be implemented in ${this.constructor.name}`);
  117.     }
  119.     /**
  120.      * Defines the action for deselecting a selected item.
  121.      *
  122.      * The base bulk actions class supports deselecting all selected items but does not have knowledge of the type of the
  123.      * selected element. Therefore, each subclass must explicitly define the action of resetting the attributes that
  124.      * indicate a selected state.
  125.      *
  126.      * @method deselectItem
  127.      * @param {HTMLElement} selectedItem The selected element.
  128.      * @returns {void}
  129.      */
  130.     deselectItem(selectedItem) {
  131.         throw new Error(`deselectItem(${selectedItem}) must be implemented in ${this.constructor.name}`);
  132.     }
  134.     /**
  135.      * Returns the sticky footer container.
  136.      *
  137.      * @method getStickyFooterContainer
  138.      * @returns {HTMLElement}
  139.      */
  140.     getStickyFooterContainer() {
  141.         return document.querySelector(Selectors.stickyFooterContainer);
  142.     }
  144.     /**
  145.      * Enables the bulk action mode.
  146.      *
  147.      * @method enableBulkActionsMode
  148.      * @returns {Promise<void>}
  149.      */
  150.     async enableBulkActionsMode() {
  151.         // Make sure that the sticky footer is enabled.
  152.         enableStickyFooter();
  153.         // Render the bulk actions content in the sticky footer container.
  154.         this.getStickyFooterContainer().innerHTML = await this.renderBulkActions();
  155.         const bulkModeContainer = this.getStickyFooterContainer().querySelector(Selectors.bulkModeContainer);
  156.         const bulkActionsContainer = bulkModeContainer.querySelector(Selectors.bulkActionsContainer);
  157.         this.getBulkActions().forEach((bulkAction) => {
  158.             // Register the listener events for each available bulk action.
  159.             bulkAction.registerListenerEvents(bulkActionsContainer);
  160.             // Set the selected items for each available bulk action.
  161.             bulkAction.setSelectedItems(this.selectedItems);
  162.         });
  163.         // Register the click listener event for the cancel bulk mode button.
  164.         bulkModeContainer.addEventListener('click', (e) => {
  165.             if (e.target.closest(Selectors.cancelBulkActionModeElement)) {
  166.                 // Deselect all selected items.
  167.                 this.selectedItems.forEach((item) => {
  168.                     this.deselectItem(item);
  169.                 });
  170.                 // Disable the bulk action mode.
  171.                 this.disableBulkActionsMode();
  172.             }
  173.         });
  174.         this.isBulkActionsModeEnabled = true;
  175.     }
  177.     /**
  178.      * Disables the bulk action mode.
  179.      *
  180.      * @method disableBulkActionsMode
  181.      * @returns {void}
  182.      */
  183.     disableBulkActionsMode() {
  184.         // If there was any previous (initial) content in the sticky footer, restore it.
  185.         if (this.initialStickyFooterContent.length > 0) {
  186.             this.getStickyFooterContainer().innerHTML = this.initialStickyFooterContent;
  187.         } else { // No previous content to restore, disable the sticky footer.
  188.             disableStickyFooter();
  189.         }
  190.         this.isBulkActionsModeEnabled = false;
  191.     }
  193.     /**
  194.      * Renders the bulk actions content.
  195.      *
  196.      * @method renderBulkActions
  197.      * @returns {Promise<string>}
  198.      */
  199.     async renderBulkActions() {
  200.         const data = {
  201.             bulkselectioncount: this.selectedItems.length,
  202.             actions: [],
  203.             moreactions: [],
  204.             hasmoreactions: false,
  205.         };
  206.         const bulkActions = this.getBulkActions();
  207.         const showMoreButton = bulkActions.length > this.maxButtons;
  209.         // Get all bulk actions and render them in order.
  210.         const actions = await Promise.all(
  211.             bulkActions.map((bulkAction, index) =>
  212.                 bulkAction.renderBulkActionTrigger(
  213.                     showMoreButton && (index >= this.maxButtons - 1),
  214.                     index
  215.                 )
  216.             )
  217.         );
  219.         // Separate rendered actions into data.actions and data.moreactions in the correct order.
  220.         actions.forEach((actionTrigger, index) => {
  221.             if (showMoreButton && (index >= this.maxButtons - 1)) {
  222.                 data.moreactions.push({'actiontrigger': actionTrigger});
  223.             } else {
  224.                 data.actions.push({'actiontrigger': actionTrigger});
  225.             }
  226.         });
  228.         data.hasmoreactions = data.moreactions.length > 0;
  230.         return Templates.render('core/bulkactions/bulk_actions', data);
  231.     }
  233.     /**
  234.      * Updates the selected items count in the bulk actions content.
  235.      *
  236.      * @method updateBulkItemSelection
  237.      * @returns {void}
  238.      */
  239.     async updateBulkItemSelection() {
  240.         const bulkSelection = await getString('bulkselection', 'core', this.selectedItems.length);
  241.         document.querySelector(Selectors.selectedItemsCountContainer).innerHTML = bulkSelection;
  242.     }
  243. }