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

/**

 * Fetch and return language strings.

 *

 * @module     core/str

 * @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 Ajax from 'core/ajax';

import Config from 'core/config';

import LocalStorage from 'core/localstorage';

/**

 * @typedef StringRequest

 * @type {object}

 * @param {string} requests.key The string identifer to fetch

 * @param {string} [requests.component='core'] The componet to fetch from

 * @param {string} [requests.lang] The language to fetch a string for. Defaults to current page language.

 * @param {object|string} [requests.param] The param for variable expansion in the string.

 */

// Module cache for the promises so that we don't make multiple

// unnecessary requests.

let promiseCache = [];

/* eslint-disable no-restricted-properties */

/**

 * Return a Promise that resolves to a string.

 *

 * If the string has previously been cached, then the Promise will be resolved immediately, otherwise it will be fetched

 * from the server and resolved when available.

 *

 * @param {string} key The language string key

 * @param {string} [component='core'] The language string component

 * @param {object|string} [param] The param for variable expansion in the string.

 * @param {string} [lang] The users language - if not passed it is deduced.

 * @return {jQuery.Promise} A jQuery Promise containing the translated string

 *

 * @example <caption>Fetching a string</caption>

 *

 * import {getString} from 'core/str';

 * get_string('cannotfindteacher', 'error')

 * .then((str) => window.console.log(str)); // Cannot find teacher

 */

// eslint-disable-next-line camelcase

export const get_string = (key, component, param, lang) => {

    return get_strings([{key, component, param, lang}])

        .then(results => results[0]);

};

/**

 * Return a Promise that resolves to a string.

 *

 * If the string has previously been cached, then the Promise will be resolved immediately, otherwise it will be fetched

 * from the server and resolved when available.

 *

 * @param {string} key The language string key

 * @param {string} [component='core'] The language string component

 * @param {object|string} [param] The param for variable expansion in the string.

 * @param {string} [lang] The users language - if not passed it is deduced.

 * @return {Promise<string>} A native Promise containing the translated string

 *

 * @example <caption>Fetching a string</caption>

 *

 * import {getString} from 'core/str';

 *

 * getString('cannotfindteacher', 'error')

 * .then((str) => window.console.log(str)); // Cannot find teacher

 */

export const getString = (key, component, param, lang) =>

    getRequestedStrings([{key, component, param, lang}])[0];

/**

 * Make a batch request to load a set of strings.

 *

 * Any missing string will be fetched from the server.

 * The Promise will only be resolved once all strings are available, or an attempt has been made to fetch them.

 *

 * @param {Array.<StringRequest>} requests List of strings to fetch

 * @return {Promise<string[]>} A native promise containing an array of the translated strings

 *

 * @example <caption>Fetching a set of strings</caption>

 *

 * import {getStrings} from 'core/str';

 * getStrings([

 *     {

 *         key: 'cannotfindteacher',

 *         component: 'error',

 *     },

 *     {

 *         key: 'yes',

 *         component: 'core',

 *     },

 *     {

 *         key: 'no',

 *         component: 'core',

 *     },

 * ])

 * .then((cannotFindTeacher, yes, no) => {

 *     window.console.log(cannotFindTeacher); // Cannot find teacher

 *     window.console.log(yes); // Yes

 *     window.console.log(no); // No

 * });

 */

export const getStrings = (requests) => Promise.all(getRequestedStrings(requests));

/**

 * Internal function to perform the string requests.

 *

 * @param {Array.<StringRequest>} requests List of strings to fetch

 * @returns {Promise[]}

 */

const getRequestedStrings = (requests) => {

    let requestData = [];

    const pageLang = Config.language;

    // Helper function to construct the cache key.

    const getCacheKey = ({key, component, lang = pageLang}) => `core_str/${key}/${component}/${lang}`;

    const stringPromises = requests.map((request) => {

        let {component, key, param, lang = pageLang} = request;

        if (!component) {

            component = 'core';

        }

        const cacheKey = getCacheKey({key, component, lang});

        // Helper function to add the promise to cache.

        const buildReturn = (promise) => {

            // Make sure the promise cache contains our promise.

            promiseCache[cacheKey] = promise;

            return promise;

        };

        // Check if we can serve the string straight from M.str.

        if (component in M.str && key in M.str[component]) {

            return buildReturn(new Promise((resolve) => {

                resolve(M.util.get_string(key, component, param));

            }));

        }

        // Check if the string is in the browser's local storage.

        const cached = LocalStorage.get(cacheKey);

        if (cached) {

            M.str[component] = {...M.str[component], [key]: cached};

            return buildReturn(new Promise((resolve) => {

                resolve(M.util.get_string(key, component, param));

            }));

        }

        // Check if we've already loaded this string from the server.

        if (cacheKey in promiseCache) {

            return buildReturn(promiseCache[cacheKey]).then(() => {

                return M.util.get_string(key, component, param);

            });

        } else {

            // We're going to have to ask the server for the string so

            // add this string to the list of requests to be sent.

            return buildReturn(new Promise((resolve, reject) => {

                requestData.push({

                    methodname: 'core_get_string',

                    args: {

                        stringid: key,

                        stringparams: [],

                        component,

                        lang,

                    },

                    done: (str) => {

                        // When we get the response from the server

                        // we should update M.str and the browser's

                        // local storage before resolving this promise.

                        M.str[component] = {...M.str[component], [key]: str};

                        LocalStorage.set(cacheKey, str);

                        resolve(M.util.get_string(key, component, param));

                    },

                    fail: reject

                });

            }));

        }

    });

    if (requestData.length) {

        // If we need to load any strings from the server then send

        // off the request.

        Ajax.call(requestData, true, false, false, 0, M.cfg.langrev);

    }

    return stringPromises;

};

/**

 * Make a batch request to load a set of strings.

 *

 * Any missing string will be fetched from the server.

 * The Promise will only be resolved once all strings are available, or an attempt has been made to fetch them.

 *

 * @param {Array.<StringRequest>} requests List of strings to fetch

 * @return {jquery.Promise<string[]>} A jquery promise containing an array of the translated strings

 *

 * @example <caption>Fetching a set of strings</caption>

 *

 * import {getStrings} from 'core/str';

 * get_strings([

 *     {

 *         key: 'cannotfindteacher',

 *         component: 'error',

 *     },

 *     {

 *         key: 'yes',

 *         component: 'core',

 *     },

 *     {

 *         key: 'no',

 *         component: 'core',

 *     },

 * ])

 * .then((cannotFindTeacher, yes, no) => {

 *     window.console.log(cannotFindTeacher); // Cannot find teacher

 *     window.console.log(yes); // Yes

 *     window.console.log(no); // No

 * });

 */

// eslint-disable-next-line camelcase

export const get_strings = (requests) => {

    // We need to use jQuery here because some calling code uses the

    // .done handler instead of the .then handler.

    return $.when.apply($, getRequestedStrings(requests))

        .then((...strings) => strings);

};

/**

 * Add a list of strings to the caches.

 *

 * This function should typically only be called from core APIs to pre-cache values.

 *

 * @method cache_strings

 * @protected

 * @param {Object[]} strings List of strings to fetch

 * @param {string} strings.key The string identifer to fetch

 * @param {string} strings.value The string value

 * @param {string} [strings.component='core'] The componet to fetch from

 * @param {string} [strings.lang=Config.language] The language to fetch a string for. Defaults to current page language.

 */

// eslint-disable-next-line camelcase

export const cache_strings = (strings) => {

    strings.forEach(({key, component, value, lang = Config.language}) => {

        const cacheKey = ['core_str', key, component, lang].join('/');

        // Check M.str caching.

        if (!(component in M.str) || !(key in M.str[component])) {

            if (!(component in M.str)) {

                M.str[component] = {};

            }

            M.str[component][key] = value;

        }

        // Check local storage.

        if (!LocalStorage.get(cacheKey)) {

            LocalStorage.set(cacheKey, value);

        }

        // Check the promises cache.

        if (!(cacheKey in promiseCache)) {

            promiseCache[cacheKey] = $.Deferred().resolve(value).promise();

        }

    });

};

/* eslint-enable no-restricted-properties */