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

/**

 * Template renderer for Moodle. Load and render Moodle templates with Mustache.

 *

 * @module     core/templates

 * @copyright  2015 Damyon Wiese <damyon@moodle.com>

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

 * @since      2.9

 */

import $ from 'jquery';

import * as config from 'core/config';

import * as filterEvents from 'core_filters/events';

import * as Y from 'core/yui';

import Renderer from './local/templates/renderer';

import {getNormalisedComponent} from 'core/utils';

/**

 * Execute a block of JS returned from a template.

 * Call this AFTER adding the template HTML into the DOM so the nodes can be found.

 *

 * @method runTemplateJS

 * @param {string} source - A block of javascript.

 */

const runTemplateJS = (source) => {

    if (source.trim() !== '') {

        // Note. We continue to use jQuery here because people are doing some dumb things

        // and we need to find, seek, and destroy first.

        // In particular, people are providing a mixture of JS, and HTML content here.

        // jQuery is someohow, magically, detecting this and putting tags into tags.

        const newScript = $('<script>').attr('type', 'text/javascript').html(source);

        $('head').append(newScript);

        if (newScript.find('script').length) {

            window.console.error(

                'Template JS contains a script tag. This is not allowed. Only raw JS should be present here.',

                source,

            );

        }

    }

};

/**

 * Do some DOM replacement and trigger correct events and fire javascript.

 *

 * @method domReplace

 * @param {JQuery} element - Element or selector to replace.

 * @param {String} newHTML - HTML to insert / replace.

 * @param {String} newJS - Javascript to run after the insertion.

 * @param {Boolean} replaceChildNodes - Replace only the childnodes, alternative is to replace the entire node.

 * @return {Array} The list of new DOM Nodes

 * @fires event:filterContentUpdated

 */

const domReplace = (element, newHTML, newJS, replaceChildNodes) => {

    const replaceNode = $(element);

    if (!replaceNode.length) {

        return [];

    }

    // First create the dom nodes so we have a reference to them.

    const newNodes = $(newHTML);

    // Do the replacement in the page.

    if (replaceChildNodes) {

        // Cleanup any YUI event listeners attached to any of these nodes.

        const yuiNodes = new Y.NodeList(replaceNode.children().get());

        yuiNodes.destroy(true);

        // JQuery will cleanup after itself.

        replaceNode.empty();

        replaceNode.append(newNodes);

    } else {

        // Cleanup any YUI event listeners attached to any of these nodes.

        const yuiNodes = new Y.NodeList(replaceNode.get());

        yuiNodes.destroy(true);

        // JQuery will cleanup after itself.

        replaceNode.replaceWith(newNodes);

    }

    // Run any javascript associated with the new HTML.

    runTemplateJS(newJS);

    // Notify all filters about the new content.

    filterEvents.notifyFilterContentUpdated(newNodes);

    return newNodes.get();

};

/**

 * Prepend some HTML to a node and trigger events and fire javascript.

 *

 * @method domPrepend

 * @param {jQuery|String} element - Element or selector to prepend HTML to

 * @param {String} html - HTML to prepend

 * @param {String} js - Javascript to run after we prepend the html

 * @return {Array} The list of new DOM Nodes

 * @fires event:filterContentUpdated

 */

const domPrepend = (element, html, js) => {

    const node = $(element);

    if (!node.length) {

        return [];

    }

    // Prepend the html.

    const newContent = $(html);

    node.prepend(newContent);

    // Run any javascript associated with the new HTML.

    runTemplateJS(js);

    // Notify all filters about the new content.

    filterEvents.notifyFilterContentUpdated(node);

    return newContent.get();

};

/**

 * Append some HTML to a node and trigger events and fire javascript.

 *

 * @method domAppend

 * @param {jQuery|String} element - Element or selector to append HTML to

 * @param {String} html - HTML to append

 * @param {String} js - Javascript to run after we append the html

 * @return {Array} The list of new DOM Nodes

 * @fires event:filterContentUpdated

 */

const domAppend = (element, html, js) => {

    const node = $(element);

    if (!node.length) {

        return [];

    }

    // Append the html.

    const newContent = $(html);

    node.append(newContent);

    // Run any javascript associated with the new HTML.

    runTemplateJS(js);

    // Notify all filters about the new content.

    filterEvents.notifyFilterContentUpdated(node);

    return newContent.get();

};

const wrapPromiseInWhenable = (promise) => $.when(new Promise((resolve, reject) => {

    promise.then(resolve).catch(reject);

}));

export default {

    // Public variables and functions.

    /**

     * Every call to render creates a new instance of the class and calls render on it. This

     * means each render call has it's own class variables.

     *

     * @method render

     * @param {string} templateName - should consist of the component and the name of the template like this:

     *                              core/menu (lib/templates/menu.mustache) or

     *                              tool_bananas/yellow (admin/tool/bananas/templates/yellow.mustache)

     * @param {Object} context - Could be array, string or simple value for the context of the template.

     * @param {string} themeName - Name of the current theme.

     * @return {Promise} JQuery promise object resolved when the template has been rendered.

     */

    render: (templateName, context, themeName = config.theme) => {

        const renderer = new Renderer();

        // Turn the Native Promise into a jQuery Promise for backwards compatability.

        return $.when(new Promise((resolve, reject) => {

            renderer.render(templateName, context, themeName)

            .then(resolve)

            .catch(reject);

        }))

        .then(({html, js}) => $.Deferred().resolve(html, js));

    },

    /**

     * Prefetch a set of templates without rendering them.

     *

     * @method getTemplate

     * @param {Array} templateNames The list of templates to fetch

     * @param {String} [themeName=config.themeName] The name of the theme to use

     * @returns {Promise}

     */

    prefetchTemplates: (templateNames, themeName = config.theme) => {

        const Loader = Renderer.getLoader();

        return Loader.prefetchTemplates(templateNames, themeName);

    },

    /**

     * Every call to render creates a new instance of the class and calls render on it. This

     * means each render call has it's own class variables.

     *

     * This alernate to the standard .render() function returns the html and js in a single object suitable for a

     * native Promise.

     *

     * @method renderForPromise

     * @param {string} templateName - should consist of the component and the name of the template like this:

     *                              core/menu (lib/templates/menu.mustache) or

     *                              tool_bananas/yellow (admin/tool/bananas/templates/yellow.mustache)

     * @param {Object} context - Could be array, string or simple value for the context of the template.

     * @param {string} themeName - Name of the current theme.

     * @return {Promise} JQuery promise object resolved when the template has been rendered.

     */

    renderForPromise: (templateName, context, themeName) => {

        const renderer = new Renderer();

        return renderer.render(templateName, context, themeName);

    },

    /**

     * Every call to renderIcon creates a new instance of the class and calls renderIcon on it. This

     * means each render call has it's own class variables.

     *

     * @method renderPix

     * @param {string} key - Icon key.

     * @param {string} component - Icon component

     * @param {string} title - Icon title

     * @return {Promise} JQuery promise object resolved when the pix has been rendered.

     */

    renderPix: (key, component, title) => {

        const renderer = new Renderer();

        return wrapPromiseInWhenable(renderer.renderIcon(

            key,

            getNormalisedComponent(component),

            title

        ));

    },

    /**

     * Execute a block of JS returned from a template.

     * Call this AFTER adding the template HTML into the DOM so the nodes can be found.

     *

     * @method runTemplateJS

     * @param {string} source - A block of javascript.

     */

    runTemplateJS: runTemplateJS,

    /**

     * Replace a node in the page with some new HTML and run the JS.

     *

     * @method replaceNodeContents

     * @param {JQuery} element - Element or selector to replace.

     * @param {String} newHTML - HTML to insert / replace.

     * @param {String} newJS - Javascript to run after the insertion.

     * @return {Array} The list of new DOM Nodes

     */

    replaceNodeContents: (element, newHTML, newJS) => domReplace(element, newHTML, newJS, true),

    /**

     * Insert a node in the page with some new HTML and run the JS.

     *

     * @method replaceNode

     * @param {JQuery} element - Element or selector to replace.

     * @param {String} newHTML - HTML to insert / replace.

     * @param {String} newJS - Javascript to run after the insertion.

     * @return {Array} The list of new DOM Nodes

     */

    replaceNode: (element, newHTML, newJS) => domReplace(element, newHTML, newJS, false),

    /**

     * Prepend some HTML to a node and trigger events and fire javascript.

     *

     * @method prependNodeContents

     * @param {jQuery|String} element - Element or selector to prepend HTML to

     * @param {String} html - HTML to prepend

     * @param {String} js - Javascript to run after we prepend the html

     * @return {Array} The list of new DOM Nodes

     */

    prependNodeContents: (element, html, js) => domPrepend(element, html, js),

    /**

     * Append some HTML to a node and trigger events and fire javascript.

     *

     * @method appendNodeContents

     * @param {jQuery|String} element - Element or selector to append HTML to

     * @param {String} html - HTML to append

     * @param {String} js - Javascript to run after we append the html

     * @return {Array} The list of new DOM Nodes

     */

    appendNodeContents: (element, html, js) => domAppend(element, html, js),

};