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

/**
 * A JavaScript module that enhances a button and text container to support copy-to-clipboard functionality.
 *
 * This module needs to be loaded by pages/templates/modules that require this functionality.
 *
 * To enable copy-to-clipboard functionality, we need a trigger element (usually a button) and a copy target element
 * (e.g. a div, span, text input, or text area).
 *
 * In the trigger element, we need to declare the <code>data-action="copytoclipboard"</code> attribute and set the
 * <code>data-clipboard-target</code> attribute which is the CSS selector that points to the target element that contains the text
 * to be copied.
 *
 * When the text is successfully copied to the clipboard, a toast message that indicates that the copy operation was a success
 * will be shown. This success message can be customised by setting the <code>data-clipboard-success-message</code> attribute in the
 * trigger element.
 *
 * @module     core/copy_to_clipboard
 * @copyright  2021 Jun Pataleta
 * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 *
 * @example <caption>Markup for the trigger and target elements</caption>
 * <input type="text" id="textinputtocopy" class="form-control" value="Copy me!" readonly />
 * <button id="copybutton" data-action="copytoclipboard" data-clipboard-target="#textinputtocopy"
 *         data-clipboard-success-message="Success!" class="btn btn-secondary">
 *     Copy to clipboard
 * </button>
 */
import {getString} from 'core/str';
import {add as addToast} from 'core/toast';
import {prefetchStrings} from 'core/prefetch';

/**
 * Add event listeners to trigger elements through event delegation.
 *
 * @private
 */
const addEventListeners = () => {
    document.addEventListener('click', e => {
        const copyButton = e.target.closest('[data-action="copytoclipboard"]');
        if (!copyButton) {
            return;
        }

        if (!copyButton.dataset.clipboardTarget) {
            return;
        }

        const copyTarget = document.querySelector(copyButton.dataset.clipboardTarget);
        if (!copyTarget) {
            return;
        }

        // This is a copy target and there is content.
        // Prevent the default action.
        e.preventDefault();

        // We have a copy target - great. Let's copy its content.
        const textToCopy = getTextFromContainer(copyTarget);
        if (!textToCopy) {
            displayFailureToast();
            return;
        }

        if (navigator.clipboard) {
            navigator.clipboard.writeText(textToCopy)
                .then(() => displaySuccessToast(copyButton)).catch();

            return;
        }

        // The clipboard API is not available.
        // This may happen when the page is not served over SSL.
        // Try to fall back to document.execCommand() approach of copying the text.
        // WARNING: This is deprecated functionality that may get dropped at anytime by browsers.

        if (copyTarget instanceof HTMLInputElement || copyTarget instanceof HTMLTextAreaElement) {
            // Focus and select the text in the target element.
            // If the execCommand fails, at least the user can readily copy the text.
            copyTarget.focus();

            if (copyNodeContentToClipboard(copyButton, copyTarget)) {
                // If the copy was successful then focus back on the copy button.
                copyButton.focus();
            }
        } else {
            // This copyTarget is not an input, or text area so cannot be used with the execCommand('copy') command.
            // To work around this we create a new textarea and copy that.
            // This textarea must be part of the DOM and must be visible.
            // We (ab)use the sr-only tag to ensure that it is considered visible to the browser, whilst being
            // hidden from view by the user.
            const copyRegion = document.createElement('textarea');
            copyRegion.value = textToCopy;
            copyRegion.classList.add('sr-only');
            document.body.appendChild(copyRegion);

            copyNodeContentToClipboard(copyButton, copyRegion);

            // After copying, remove the temporary element and move focus back to the triggering button.
            copyRegion.remove();
            copyButton.focus();
        }
    });
};

/**
 * Copy the content of the selected element to the clipboard, and display a notifiction if successful.
 *
 * @param {HTMLElement} copyButton
 * @param {HTMLElement} copyTarget
 * @returns {boolean}
 * @private
 */
const copyNodeContentToClipboard = (copyButton, copyTarget) => {
    copyTarget.select();

    // Try to copy the text from the target element.
    if (document.execCommand('copy')) {
        displaySuccessToast(copyButton);
        return true;
    }

    displayFailureToast();
    return false;
};

/**
 * Displays a toast containing the success message.
 *
 * @param {HTMLElement} copyButton The element that copies the text from the container.
 * @returns {Promise<void>}
 * @private
 */
const displaySuccessToast = copyButton => getSuccessText(copyButton)
    .then(successMessage => addToast(successMessage, {}));

/**
 * Displays a toast containing the failure message.
 *
 * @returns {Promise<void>}
 * @private
 */
const displayFailureToast = () => getFailureText()
    .then(message => addToast(message, {type: 'warning'}));

/**
 * Fetches the failure message to show to the user.
 *
 * @returns {Promise}
 * @private
 */
const getFailureText = () => getString('unabletocopytoclipboard', 'core');

/**
 * Fetches the success message to show to the user.
 *
 * @param {HTMLElement} copyButton The element that copies the text from the container. This may contain the custom success message
 * via its data-clipboard-success-message attribute.
 * @returns {Promise|*}
 * @private
 */
const getSuccessText = copyButton => {
    if (copyButton.dataset.clipboardSuccessMessage) {
        return Promise.resolve(copyButton.dataset.clipboardSuccessMessage);
    }

    return getString('textcopiedtoclipboard', 'core');
};

/**
 * Fetches the text to be copied from the container.
 *
 * @param {HTMLElement} container The element containing the text to be copied.
 * @returns {null|string}
 * @private
 */
const getTextFromContainer = container => {
    if (container.value) {
        // For containers which are form elements (e.g. text area, text input), get the element's value.
        return container.value;
    } else if (container.innerText) {
        // For other elements, try to use the innerText attribute.
        return container.innerText;
    }

    return null;
};

let loaded = false;
if (!loaded) {
    prefetchStrings('core', [
        'textcopiedtoclipboard',
        'unabletocopytoclipboard',
    ]);

    // Add event listeners.
    addEventListeners();
    loaded = true;
}