lib/amd/src/local/templates/renderer.js

// 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/>.
import * as Log from 'core/log';
import * as Truncate from 'core/truncate';
import * as UserDate from 'core/user_date';
import Pending from 'core/pending';
import {getStrings} from 'core/str';
import IconSystem from 'core/icon_system';
import config from 'core/config';
import mustache from 'core/mustache';
import Loader from './loader';
import {getNormalisedComponent} from 'core/utils';
/** @var {string} The placeholder character used for standard strings (unclean) */
const placeholderString = 's';
/** @var {string} The placeholder character used for cleaned strings */
const placeholderCleanedString = 'c';
/**
 * Template Renderer Class.
 *
 * Note: This class is not intended to be instantiated directly. Instead, use the core/templates module.
 *
 * @module     core/local/templates/renderer
 * @copyright  2023 Andrew Lyons <andrew@nicols.co.uk>
 * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 * @since      4.3
 */
export default class Renderer {
    /** @var {string[]} requiredStrings - Collection of strings found during the rendering of one template */
    requiredStrings = null;
    /** @var {object[]} requiredDates - Collection of dates found during the rendering of one template */
    requiredDates = [];
    /** @var {string[]} requiredJS - Collection of js blocks found during the rendering of one template */
    requiredJS = null;
    /** @var {String} themeName for the current render */
    currentThemeName = '';
    /** @var {Number} uniqInstances Count of times this constructor has been called. */
    static uniqInstances = 0;
    /** @var {Object[]} loadTemplateBuffer - List of templates to be loaded */
    static loadTemplateBuffer = [];
    /** @var {Bool} isLoadingTemplates - Whether templates are currently being loaded */
    static isLoadingTemplates = false;
    /** @var {Object} iconSystem - Object extending core/iconsystem */
    iconSystem = null;
    /** @var {Array} disallowedNestedHelpers - List of helpers that can't be called within other helpers */
    static disallowedNestedHelpers = [
        'js',
    ];
    /** @var {String[]} templateCache - Cache of already loaded template strings */
    static templateCache = {};
    /**
     * Cache of already loaded template promises.
     *
     * @type {Promise[]}
     * @static
     * @private
     */
    static templatePromises = {};
    /**
     * The loader used to fetch templates.
     * @type {Loader}
     * @static
     * @private
     */
    static loader = Loader;
    /**
     * Constructor
     *
     * Each call to templates.render gets it's own instance of this class.
     */
    constructor() {
        this.requiredStrings = [];
        this.requiredJS = [];
        this.requiredDates = [];
        this.currentThemeName = '';
    }
    /**
     * Set the template loader to use for all Template renderers.
     *
     * @param {Loader} loader
     */
    static setLoader(loader) {
        this.loader = loader;
    }
    /**
     * Get the Loader used to fetch templates.
     *
     * @returns {Loader}
     */
    static getLoader() {
        return this.loader;
    }
    /**
     * Render a single image icon.
     *
     * @method renderIcon
     * @private
     * @param {string} key The icon key.
     * @param {string} component The component name.
     * @param {string} title The icon title
     * @returns {Promise}
     */
    async renderIcon(key, component, title) {
        // Preload the module to do the icon rendering based on the theme iconsystem.
        component = getNormalisedComponent(component);
        await this.setupIconSystem();
        const template = await Renderer.getLoader().getTemplate(
            this.iconSystem.getTemplateName(),
            this.currentThemeName,
        );
        return this.iconSystem.renderIcon(
            key,
            component,
            title,
            template
        );
    }
    /**
     * Helper to set up the icon system.
     */
    async setupIconSystem() {
        if (!this.iconSystem) {
            this.iconSystem = await IconSystem.instance();
        }
        return this.iconSystem;
    }
    /**
     * Render image icons.
     *
     * @method pixHelper
     * @private
     * @param {object} context The mustache context
     * @param {string} sectionText The text to parse arguments from.
     * @param {function} helper Used to render the alt attribute of the text.
     * @returns {string}
     */
    pixHelper(context, sectionText, helper) {
        const parts = sectionText.split(',');
        let key = '';
        let component = '';
        let text = '';
        if (parts.length > 0) {
            key = helper(parts.shift().trim(), context);
        }
        if (parts.length > 0) {
            component = helper(parts.shift().trim(), context);
        }
        if (parts.length > 0) {
            text = helper(parts.join(',').trim(), context);
        }
        // Note: We cannot use Promises in Mustache helpers.
        // We must fetch straight from the Loader cache.
        // The Loader cache is statically defined on the Loader class and should be used by all children.
        const Loader = Renderer.getLoader();
        const templateName = this.iconSystem.getTemplateName();
        const searchKey = Loader.getSearchKey(this.currentThemeName, templateName);
        const template = Loader.getTemplateFromCache(searchKey);
        component = getNormalisedComponent(component);
        // The key might have been escaped by the JS Mustache engine which
        // converts forward slashes to HTML entities. Let us undo that here.
        key = key.replace(/&#x2F;/gi, '/');
        return this.iconSystem.renderIcon(
            key,
            component,
            text,
            template
        );
    }
    /**
     * Render blocks of javascript and save them in an array.
     *
     * @method jsHelper
     * @private
     * @param {object} context The current mustache context.
     * @param {string} sectionText The text to save as a js block.
     * @param {function} helper Used to render the block.
     * @returns {string}
     */
    jsHelper(context, sectionText, helper) {
        this.requiredJS.push(helper(sectionText, context));
        return '';
    }
    /**
     * String helper used to render {{#str}}abd component { a : 'fish'}{{/str}}
     * into a get_string call.
     *
     * @method stringHelper
     * @private
     * @param {object} context The current mustache context.
     * @param {string} sectionText The text to parse the arguments from.
     * @param {function} helper Used to render subsections of the text.
     * @returns {string}
     */
    stringHelper(context, sectionText, helper) {
        // A string instruction is in the format:
        // key, component, params.
        let parts = sectionText.split(',');
        const key = parts.length > 0 ? parts.shift().trim() : '';
        const component = parts.length > 0 ? getNormalisedComponent(parts.shift().trim()) : '';
        let param = parts.length > 0 ? parts.join(',').trim() : '';
        if (param !== '') {
            // Allow variable expansion in the param part only.
            param = helper(param, context);
        }
        if (param.match(/^{\s*"/gm)) {
            // If it can't be parsed then the string is not a JSON format.
            try {
                const parsedParam = JSON.parse(param);
                // Handle non-exception-throwing cases, e.g. null, integer, boolean.
                if (parsedParam && typeof parsedParam === "object") {
                    param = parsedParam;
                }
            } catch (err) {
                // This was probably not JSON.
                // Keep the error message visible but do not promote it because it may not be an error.
                window.console.warn(err.message);
            }
        }
        const index = this.requiredStrings.length;
        this.requiredStrings.push({
            key,
            component,
            param,
        });
        // The placeholder must not use {{}} as those can be misinterpreted by the engine.
        return `[[_s${index}]]`;
    }
    /**
     * String helper to render {{#cleanstr}}abd component { a : 'fish'}{{/cleanstr}}
     * into a get_string following by an HTML escape.
     *
     * @method cleanStringHelper
     * @private
     * @param {object} context The current mustache context.
     * @param {string} sectionText The text to parse the arguments from.
     * @param {function} helper Used to render subsections of the text.
     * @returns {string}
     */
    cleanStringHelper(context, sectionText, helper) {
        // We're going to use [[_cx]] format for clean strings, where x is a number.
        // Hence, replacing 's' with 'c' in the placeholder that stringHelper returns.
        return this
            .stringHelper(context, sectionText, helper)
            .replace(placeholderString, placeholderCleanedString);
    }
    /**
     * Quote helper used to wrap content in quotes, and escape all special JSON characters present in the content.
     *
     * @method quoteHelper
     * @private
     * @param {object} context The current mustache context.
     * @param {string} sectionText The text to parse the arguments from.
     * @param {function} helper Used to render subsections of the text.
     * @returns {string}
     */
    quoteHelper(context, sectionText, helper) {
        let content = helper(sectionText.trim(), context);
        // Escape the {{ and JSON encode.
        // This involves wrapping {{, and }} in change delimeter tags.
        content = JSON.stringify(content);
        content = content.replace(/([{}]{2,3})/g, '{{=<% %>=}}$1<%={{ }}=%>');
        return content;
    }
    /**
     * Shorten text helper to truncate text and append a trailing ellipsis.
     *
     * @method shortenTextHelper
     * @private
     * @param {object} context The current mustache context.
     * @param {string} sectionText The text to parse the arguments from.
     * @param {function} helper Used to render subsections of the text.
     * @returns {string}
     */
    shortenTextHelper(context, sectionText, helper) {
        // Non-greedy split on comma to grab section text into the length and
        // text parts.
        const parts = sectionText.match(/(.*?),(.*)/);
        // The length is the part matched in the first set of parethesis.
        const length = parts[1].trim();
        // The length is the part matched in the second set of parethesis.
        const text = parts[2].trim();
        const content = helper(text, context);
        return Truncate.truncate(content, {
            length,
            words: true,
            ellipsis: '...'
        });
    }
    /**
     * User date helper to render user dates from timestamps.
     *
     * @method userDateHelper
     * @private
     * @param {object} context The current mustache context.
     * @param {string} sectionText The text to parse the arguments from.
     * @param {function} helper Used to render subsections of the text.
     * @returns {string}
     */
    userDateHelper(context, sectionText, helper) {
        // Non-greedy split on comma to grab the timestamp and format.
        const parts = sectionText.match(/(.*?),(.*)/);
        const timestamp = helper(parts[1].trim(), context);
        const format = helper(parts[2].trim(), context);
        const index = this.requiredDates.length;
        this.requiredDates.push({
            timestamp: timestamp,
            format: format
        });
        return `[[_t_${index}]]`;
    }
    /**
     * Return a helper function to be added to the context for rendering the a
     * template.
     *
     * This will parse the provided text before giving it to the helper function
     * in order to remove any disallowed nested helpers to prevent one helper
     * from calling another.
     *
     * In particular to prevent the JS helper from being called from within another
     * helper because it can lead to security issues when the JS portion is user
     * provided.
     *
     * @param  {function} helperFunction The helper function to add
     * @param  {object} context The template context for the helper function
     * @returns {Function} To be set in the context
     */
    addHelperFunction(helperFunction, context) {
        return function() {
            return function(sectionText, helper) {
                // Override the disallowed helpers in the template context with
                // a function that returns an empty string for use when executing
                // other helpers. This is to prevent these helpers from being
                // executed as part of the rendering of another helper in order to
                // prevent any potential security issues.
                const originalHelpers = Renderer.disallowedNestedHelpers.reduce((carry, name) => {
                    if (context.hasOwnProperty(name)) {
                        carry[name] = context[name];
                    }
                    return carry;
                }, {});
                Renderer.disallowedNestedHelpers.forEach((helperName) => {
                    context[helperName] = () => '';
                });
                // Execute the helper with the modified context that doesn't include
                // the disallowed nested helpers. This prevents the disallowed
                // helpers from being called from within other helpers.
                const result = helperFunction.apply(this, [context, sectionText, helper]);
                // Restore the original helper implementation in the context so that
                // any further rendering has access to them again.
                for (const name in originalHelpers) {
                    context[name] = originalHelpers[name];
                }
                return result;
            }.bind(this);
        }.bind(this);
    }
    /**
     * Add some common helper functions to all context objects passed to templates.
     * These helpers match exactly the helpers available in php.
     *
     * @method addHelpers
     * @private
     * @param {Object} context Simple types used as the context for the template.
     * @param {String} themeName We set this multiple times, because there are async calls.
     */
    addHelpers(context, themeName) {
        this.currentThemeName = themeName;
        this.requiredStrings = [];
        this.requiredJS = [];
        context.uniqid = (Renderer.uniqInstances++);
        // Please note that these helpers _must_ not return a Promise.
        context.str = this.addHelperFunction(this.stringHelper, context);
        context.cleanstr = this.addHelperFunction(this.cleanStringHelper, context);
        context.pix = this.addHelperFunction(this.pixHelper, context);
        context.js = this.addHelperFunction(this.jsHelper, context);
        context.quote = this.addHelperFunction(this.quoteHelper, context);
        context.shortentext = this.addHelperFunction(this.shortenTextHelper, context);
        context.userdate = this.addHelperFunction(this.userDateHelper, context);
        context.globals = {config: config};
        context.currentTheme = themeName;
    }
    /**
     * Get all the JS blocks from the last rendered template.
     *
     * @method getJS
     * @private
     * @returns {string}
     */
    getJS() {
        return this.requiredJS.join(";\n");
    }
    /**
     * Treat strings in content.
     *
     * The purpose of this method is to replace the placeholders found in a string
     * with the their respective translated strings.
     *
     * Previously we were relying on String.replace() but the complexity increased with
     * the numbers of strings to replace. Now we manually walk the string and stop at each
     * placeholder we find, only then we replace it. Most of the time we will
     * replace all the placeholders in a single run, at times we will need a few
     * more runs when placeholders are replaced with strings that contain placeholders
     * themselves.
     *
     * @param {String} content The content in which string placeholders are to be found.
     * @param {Map} stringMap The strings to replace with.
     * @returns {String} The treated content.
     */
    treatStringsInContent(content, stringMap) {
        // Placeholders are in the for [[_sX]] or [[_cX]] where X is the string index.
        const stringPattern = /(?<placeholder>\[\[_(?<stringType>[cs])(?<stringIndex>\d+)\]\])/g;
        // A helper to fetch the string for a given placeholder.
        const getUpdatedString = ({placeholder, stringType, stringIndex}) => {
            if (stringMap.has(placeholder)) {
                return stringMap.get(placeholder);
            }
            if (stringType === placeholderCleanedString) {
                // Attempt to find the unclean string and clean it. Store it for later use.
                const uncleanString = stringMap.get(`[[_s${stringIndex}]]`);
                if (uncleanString) {
                    stringMap.set(placeholder, mustache.escape(uncleanString));
                    return stringMap.get(placeholder);
                }
            }
            Log.debug(`Could not find string for pattern ${placeholder}`);
            return ''; // Fallback if no match is found.
        };
        let updatedContent = content; // Start with the original content.
        let placeholderFound = true; // Flag to track if we are still finding placeholders.
        // Continue looping until no more placeholders are found in the updated content.
        while (placeholderFound) {
            let match;
            let result = [];
            let lastIndex = 0;
            placeholderFound = false; // Assume no placeholders are found.
            // Find all placeholders in the content and replace them with their respective strings.
            while ((match = stringPattern.exec(updatedContent)) !== null) {
                placeholderFound = true; // A placeholder was found, so continue looping.
                // Add the content before the matched placeholder.
                result.push(updatedContent.slice(lastIndex, match.index));
                // Add the updated string for the placeholder.
                result.push(getUpdatedString(match.groups));
                // Update lastIndex to move past the current match.
                lastIndex = match.index + match[0].length;
            }
            // Add the remaining part of the content after the last match.
            result.push(updatedContent.slice(lastIndex));
            // Join the parts of the result array into the updated content.
            updatedContent = result.join('');
        }
        return updatedContent; // Return the fully updated content after all loops.
    }
    /**
     * Treat strings in content.
     *
     * The purpose of this method is to replace the date placeholders found in the
     * content with the their respective translated dates.
     *
     * @param {String} content The content in which string placeholders are to be found.
     * @param {Array} dates The dates to replace with.
     * @returns {String} The treated content.
     */
    treatDatesInContent(content, dates) {
        dates.forEach((date, index) => {
            content = content.replace(
                new RegExp(`\\[\\[_t_${index}\\]\\]`, 'g'),
                date,
            );
        });
        return content;
    }
    /**
     * Render a template and then call the callback with the result.
     *
     * @method doRender
     * @private
     * @param {string|Promise} templateSourcePromise The mustache template to render.
     * @param {Object} context Simple types used as the context for the template.
     * @param {String} themeName Name of the current theme.
     * @returns {Promise<object<string, string>>} The rendered HTML and JS.
     */
    async doRender(templateSourcePromise, context, themeName) {
        this.currentThemeName = themeName;
        const iconTemplate = this.iconSystem.getTemplateName();
        const pendingPromise = new Pending('core/templates:doRender');
        const [templateSource] = await Promise.all([
            templateSourcePromise,
            Renderer.getLoader().getTemplate(iconTemplate, themeName),
        ]);
        this.addHelpers(context, themeName);
        // Render the template.
        const renderedContent = await mustache.render(
            templateSource,
            context,
            // Note: The third parameter is a function that will be called to process partials.
            (partialName) => Renderer.getLoader().partialHelper(partialName, themeName),
        );
        const {html, js} = await this.processRenderedContent(renderedContent);
        pendingPromise.resolve();
        return {html, js};
    }
    /**
     * Process the rendered content, treating any strings and applying and helper strings, dates, etc.
     * @param {string} renderedContent
     * @returns {Promise<object<string, string>>} The rendered HTML and JS.
     */
    async processRenderedContent(renderedContent) {
        let html = renderedContent.trim();
        let js = this.getJS();
        if (this.requiredStrings.length > 0) {
            // Fetch the strings into a new Map using the placeholder as an index.
            // Note: We only fetch the unclean version. Cleaning of strings happens lazily in treatStringsInContent.
            const stringMap = new Map(
                (await getStrings(this.requiredStrings)).map((string, index) => (
                    [`[[_s${index}]]`, string]
                ))
            );
            // Make sure string substitutions are done for the userdate
            // values as well.
            this.requiredDates = this.requiredDates.map(function(date) {
                return {
                    timestamp: this.treatStringsInContent(date.timestamp, stringMap),
                    format: this.treatStringsInContent(date.format, stringMap)
                };
            }.bind(this));
            // Why do we not do another call the render here?
            //
            // Because that would expose DOS holes. E.g.
            // I create an assignment called "{{fish" which
            // would get inserted in the template in the first pass
            // and cause the template to die on the second pass (unbalanced).
            html = this.treatStringsInContent(html, stringMap);
            js = this.treatStringsInContent(js, stringMap);
        }
        // This has to happen after the strings replacement because you can
        // use the string helper in content for the user date helper.
        if (this.requiredDates.length > 0) {
            const dates = await UserDate.get(this.requiredDates);
            html = this.treatDatesInContent(html, dates);
            js = this.treatDatesInContent(js, dates);
        }
        return {html, js};
    }
    /**
     * Load a template and call doRender on it.
     *
     * @method render
     * @private
     * @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.
     * @returns {Promise<object>} Native promise object resolved when the template has been rendered.}
     */
    async render(
        templateName,
        context = {},
        themeName = config.theme,
    ) {
        this.currentThemeName = themeName;
        // Preload the module to do the icon rendering based on the theme iconsystem.
        await this.setupIconSystem();
        const templateSource = Renderer.getLoader().cachePartials(templateName, themeName);
        return this.doRender(templateSource, context, themeName);
    }
}