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

import $ from 'jquery';
import ajax from 'core/ajax';
import * as str from 'core/str';
import * as config from 'core/config';
import mustache from 'core/mustache';
import storage from 'core/localstorage';
import {getNormalisedComponent} from 'core/utils';

/**
 * Template this.
 *
 * @module     core/local/templates/loader
 * @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 Loader {
    /** @var {String} themeName for the current render */
    currentThemeName = '';

    /** @var {Object[]} loadTemplateBuffer - List of templates to be loaded */
    static loadTemplateBuffer = [];

    /** @var {Bool} isLoadingTemplates - Whether templates are currently being loaded */
    static isLoadingTemplates = false;

    /** @var {Map} templateCache - Cache of already loaded template strings */
    static templateCache = new Map();

    /** @var {Promise[]} templatePromises - Cache of already loaded template promises */
    static templatePromises = {};

    /** @var {Promise[]} cachePartialPromises - Cache of already loaded template partial promises */
    static cachePartialPromises = [];

    /**
     * A helper to get the search key
     *
     * @param {string} theme
     * @param {string} templateName
     * @returns {string}
     */
    static getSearchKey(theme, templateName) {
        return `${theme}/${templateName}`;
    }

    /**
     * Load a template.
     *
     * @method getTemplate
     * @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 {string} [themeName=config.theme] - The theme to load the template from
     * @return {Promise} JQuery promise object resolved when the template has been fetched.
     */
    static getTemplate(templateName, themeName = config.theme) {
        const searchKey = this.getSearchKey(themeName, templateName);

        // If we haven't already seen this template then buffer it.
        const cachedPromise = this.getTemplatePromiseFromCache(searchKey);
        if (cachedPromise) {
            return cachedPromise;
        }

        // Check the buffer to see if this template has already been added.
        const existingBufferRecords = this.loadTemplateBuffer.filter((record) => record.searchKey === searchKey);
        if (existingBufferRecords.length) {
            // This template is already in the buffer so just return the existing
            // promise. No need to add it to the buffer again.
            return existingBufferRecords[0].deferred.promise();
        }

        // This is the first time this has been requested so let's add it to the buffer
        // to be loaded.
        const parts = templateName.split('/');
        const component = getNormalisedComponent(parts.shift());
        const name = parts.join('/');
        const deferred = $.Deferred();

        // Add this template to the buffer to be loaded.
        this.loadTemplateBuffer.push({
            component,
            name,
            theme: themeName,
            searchKey,
            deferred,
        });

        // We know there is at least one thing in the buffer so kick off a processing run.
        this.processLoadTemplateBuffer();
        return deferred.promise();
    }

    /**
     * Store a template in the cache.
     *
     * @param {string} searchKey
     * @param {string} templateSource
     */
    static setTemplateInCache(searchKey, templateSource) {
        // Cache all of the dependent templates because we'll need them to render
        // the requested template.
        this.templateCache.set(searchKey, templateSource);
    }

    /**
     * Fetch a template from the cache.
     *
     * @param {string} searchKey
     * @returns {string}
     */
    static getTemplateFromCache(searchKey) {
        return this.templateCache.get(searchKey);
    }

    /**
     * Check whether a template is in the cache.
     *
     * @param {string} searchKey
     * @returns {bool}
     */
    static hasTemplateInCache(searchKey) {
        return this.templateCache.has(searchKey);
    }

    /**
     * Prefetch a set of templates without rendering them.
     *
     * @param {Array} templateNames The list of templates to fetch
     * @param {string} themeName
     */
    static prefetchTemplates(templateNames, themeName) {
        templateNames.forEach((templateName) => this.prefetchTemplate(templateName, themeName));
    }

    /**
     * Prefetech a sginle template without rendering it.
     *
     * @param {string} templateName
     * @param {string} themeName
     */
    static prefetchTemplate(templateName, themeName) {
        const searchKey = this.getSearchKey(themeName, templateName);

        // If we haven't already seen this template then buffer it.
        if (this.hasTemplateInCache(searchKey)) {
            return;
        }

        // Check the buffer to see if this template has already been added.
        const existingBufferRecords = this.loadTemplateBuffer.filter((record) => record.searchKey === searchKey);

        if (existingBufferRecords.length) {
            // This template is already in the buffer so just return the existing promise.
            // No need to add it to the buffer again.
            return;
        }

        // This is the first time this has been requested so let's add it to the buffer to be loaded.
        const parts = templateName.split('/');
        const component = getNormalisedComponent(parts.shift());
        const name = parts.join('/');

        // Add this template to the buffer to be loaded.
        this.loadTemplateBuffer.push({
            component,
            name,
            theme: themeName,
            searchKey,
            deferred: $.Deferred(),
        });

        this.processLoadTemplateBuffer();
    }

    /**
     * Load a partial from the cache or ajax.
     *
     * @method partialHelper
     * @param {string} name The partial name to load.
     * @param {string} [themeName = config.theme] The theme to load the partial from.
     * @return {string}
     */
    static partialHelper(name, themeName = config.theme) {
        const searchKey = this.getSearchKey(themeName, name);

        if (!this.hasTemplateInCache(searchKey)) {
            new Error(`Failed to pre-fetch the template: ${name}`);
        }
        return this.getTemplateFromCache(searchKey);
    }

    /**
     * Scan a template source for partial tags and return a list of the found partials.
     *
     * @method scanForPartials
     * @param {string} templateSource - source template to scan.
     * @return {Array} List of partials.
     */
    static scanForPartials(templateSource) {
        const tokens = mustache.parse(templateSource);
        const partials = [];

        const findPartial = (tokens, partials) => {
            let i;
            for (i = 0; i < tokens.length; i++) {
                const token = tokens[i];
                if (token[0] == '>' || token[0] == '<') {
                    partials.push(token[1]);
                }
                if (token.length > 4) {
                    findPartial(token[4], partials);
                }
            }
        };

        findPartial(tokens, partials);

        return partials;
    }

    /**
     * Load a template and scan it for partials. Recursively fetch the partials.
     *
     * @method cachePartials
     * @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 {string} [themeName=config.theme]
     * @param {Array} parentage - A list of requested partials in this render chain.
     * @return {Promise} JQuery promise object resolved when all partials are in the cache.
     */
    static cachePartials(templateName, themeName = config.theme, parentage = []) {
        const searchKey = this.getSearchKey(themeName, templateName);

        if (searchKey in this.cachePartialPromises) {
            return this.cachePartialPromises[searchKey];
        }

        // This promise will not be resolved until all child partials are also resolved and ready.
        // We create it here to allow us to check for recursive inclusion of templates.
        // Keep track of the requested partials in this chain.
        if (!parentage.length) {
            parentage.push(searchKey);
        }

        this.cachePartialPromises[searchKey] = $.Deferred();
        this._cachePartials(templateName, themeName, parentage).catch((error) => {
            this.cachePartialPromises[searchKey].reject(error);
        });

        return this.cachePartialPromises[searchKey];
    }

    /**
     * Cache the template partials for the specified template.
     *
     * @param {string} templateName
     * @param {string} themeName
     * @param {array} parentage
     * @returns {promise<string>}
     */
    static async _cachePartials(templateName, themeName, parentage) {
        const searchKey = this.getSearchKey(themeName, templateName);
        const templateSource = await this.getTemplate(templateName, themeName);
        const partials = this.scanForPartials(templateSource);
        const uniquePartials = partials.filter((partialName) => {
            // Check for recursion.
            if (parentage.indexOf(`${themeName}/${partialName}`) >= 0) {
                // Ignore templates which include a parent template already requested in the current chain.
                return false;
            }

            // Ignore templates that include themselves.
            return partialName !== templateName;
        });

        // Fetch any partial which has not already been fetched.
        const fetchThemAll = uniquePartials.map((partialName) => {
            parentage.push(`${themeName}/${partialName}`);
            return this.cachePartials(partialName, themeName, parentage);
        });

        await Promise.all(fetchThemAll);
        return this.cachePartialPromises[searchKey].resolve(templateSource);
    }

    /**
     * Take all of the templates waiting in the buffer and load them from the server
     * or from the cache.
     *
     * All of the templates that need to be loaded from the server will be batched up
     * and sent in a single network request.
     */
    static processLoadTemplateBuffer() {
        if (!this.loadTemplateBuffer.length) {
            return;
        }

        if (this.isLoadingTemplates) {
            return;
        }

        this.isLoadingTemplates = true;
        // Grab any templates waiting in the buffer.
        const templatesToLoad = this.loadTemplateBuffer.slice();
        // This will be resolved with the list of promises for the server request.
        const serverRequestsDeferred = $.Deferred();
        const requests = [];
        // Get a list of promises for each of the templates we need to load.
        const templatePromises = templatesToLoad.map((templateData) => {
            const component = getNormalisedComponent(templateData.component);
            const name = templateData.name;
            const searchKey = templateData.searchKey;
            const theme = templateData.theme;
            const templateDeferred = templateData.deferred;
            let promise = null;

            // Double check to see if this template happened to have landed in the
            // cache as a dependency of an earlier template.
            if (this.hasTemplateInCache(searchKey)) {
                // We've seen this template so immediately resolve the existing promise.
                promise = this.getTemplatePromiseFromCache(searchKey);
            } else {
                // We haven't seen this template yet so we need to request it from
                // the server.
                requests.push({
                    methodname: 'core_output_load_template_with_dependencies',
                    args: {
                        component,
                        template: name,
                        themename: theme,
                        lang: config.language,
                    }
                });
                // Remember the index in the requests list for this template so that
                // we can get the appropriate promise back.
                const index = requests.length - 1;

                // The server deferred will be resolved with a list of all of the promises
                // that were sent in the order that they were added to the requests array.
                promise = serverRequestsDeferred.promise()
                    .then((promises) => {
                        // The promise for this template will be the one that matches the index
                        // for it's entry in the requests array.
                        //
                        // Make sure the promise is added to the promises cache for this template
                        // search key so that we don't request it again.
                        templatePromises[searchKey] = promises[index].then((response) => {
                            // Process all of the template dependencies for this template and add
                            // them to the caches so that we don't request them again later.
                            response.templates.forEach((data) => {
                                data.component = getNormalisedComponent(data.component);
                                const tempSearchKey = this.getSearchKey(
                                    theme,
                                    [data.component, data.name].join('/'),
                                );

                                // Cache all of the dependent templates because we'll need them to render
                                // the requested template.
                                this.setTemplateInCache(tempSearchKey, data.value);

                                if (config.templaterev > 0) {
                                    // The template cache is enabled - set the value there.
                                    storage.set(`core_template/${config.templaterev}:${tempSearchKey}`, data.value);
                                }
                            });

                            if (response.strings.length) {
                                // If we have strings that the template needs then warm the string cache
                                // with them now so that we don't need to re-fetch them.
                                str.cache_strings(response.strings.map(({component, name, value}) => ({
                                    component: getNormalisedComponent(component),
                                    key: name,
                                    value,
                                })));
                            }

                            // Return the original template source that the user requested.
                            if (this.hasTemplateInCache(searchKey)) {
                                return this.getTemplateFromCache(searchKey);
                            }

                            return null;
                        });

                        return templatePromises[searchKey];
                    });
            }

            return promise
                // When we've successfully loaded the template then resolve the deferred
                // in the buffer so that all of the calling code can proceed.
                .then((source) => templateDeferred.resolve(source))
                .catch((error) => {
                    // If there was an error loading the template then reject the deferred
                    // in the buffer so that all of the calling code can proceed.
                    templateDeferred.reject(error);
                    // Rethrow for anyone else listening.
                    throw error;
                });
        });

        if (requests.length) {
            // We have requests to send so resolve the deferred with the promises.
            serverRequestsDeferred.resolve(ajax.call(requests, true, false, false, 0, config.templaterev));
        } else {
            // Nothing to load so we can resolve our deferred.
            serverRequestsDeferred.resolve();
        }

        // Once we've finished loading all of the templates then recurse to process
        // any templates that may have been added to the buffer in the time that we
        // were fetching.
        $.when.apply(null, templatePromises)
            .then(() => {
                // Remove the templates we've loaded from the buffer.
                this.loadTemplateBuffer.splice(0, templatesToLoad.length);
                this.isLoadingTemplates = false;
                this.processLoadTemplateBuffer();
                return;
            })
            .catch(() => {
                // Remove the templates we've loaded from the buffer.
                this.loadTemplateBuffer.splice(0, templatesToLoad.length);
                this.isLoadingTemplates = false;
                this.processLoadTemplateBuffer();
            });
    }

    /**
     * Search the various caches for a template promise for the given search key.
     * The search key should be in the format <theme>/<component>/<template> e.g. boost/core/modal.
     *
     * If the template is found in any of the caches it will populate the other caches with
     * the same data as well.
     *
     * @param {String} searchKey The template search key in the format <theme>/<component>/<template> e.g. boost/core/modal
     * @returns {Object|null} jQuery promise resolved with the template source
     */
    static getTemplatePromiseFromCache(searchKey) {
        // First try the cache of promises.
        if (searchKey in this.templatePromises) {
            return this.templatePromises[searchKey];
        }

        // Check the module cache.
        if (this.hasTemplateInCache(searchKey)) {
            const templateSource = this.getTemplateFromCache(searchKey);
            // Add this to the promises cache for future.
            this.templatePromises[searchKey] = $.Deferred().resolve(templateSource).promise();
            return this.templatePromises[searchKey];
        }

        if (config.templaterev <= 0) {
            // Template caching is disabled. Do not store in persistent storage.
            return null;
        }

        // Now try local storage.
        const cached = storage.get(`core_template/${config.templaterev}:${searchKey}`);
        if (cached) {
            // Add this to the module cache for future.
            this.setTemplateInCache(searchKey, cached);

            // Add to the promises cache for future.
            this.templatePromises[searchKey] = $.Deferred().resolve(cached).promise();
            return this.templatePromises[searchKey];
        }

        return null;
    }
}