// 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),
};