infusion/src/framework/core/js/MessageResolver.js

Infusion is an application framework for developing flexible stuff with JavaScript

/*
Copyright 2011-2016 OCAD University
Copyright 2011 Lucendo Development Ltd.

Licensed under the Educational Community License (ECL), Version 2.0 or the New
BSD license. You may not use this file except in compliance with one these
Licenses.

You may obtain a copy of the ECL 2.0 License and BSD License at
https://github.com/fluid-project/infusion/raw/master/Infusion-LICENSE.txt
*/

var fluid_3_0_0 = fluid_3_0_0 || {};

(function ($, fluid) {
    "use strict";

    fluid.defaults("fluid.messageResolver", {
        gradeNames: ["fluid.component"],
        mergePolicy: {
            messageBase: "nomerge",
            parents: "nomerge"
        },
        resolveFunc: fluid.stringTemplate,
        parseFunc: fluid.identity,
        messageBase: {},
        members: {
            messageBase: "@expand:{that}.options.parseFunc({that}.options.messageBase)"
        },
        invokers: {
            lookup: "fluid.messageResolver.lookup({that}, {arguments}.0)", // messagecodes
            resolve: "fluid.messageResolver.resolve({that}, {arguments}.0, {arguments}.1)" // messagecodes, args
        },
        parents: []
    });

    /**
     *
     * Look up the first matching message template, starting with the current grade and working up through its parents.
     * Returns both the template for the message and the function used to resolve the localised value.  By default
     * the resolve function is `fluid.stringTemplate`, and the template returned uses its syntax.
     *
     * @param {Object} that - The component itself.
     * @param {Array} messagecodes - One or more message codes to look up templates for.
     * @return {Object} - An object that contains`template` and `resolveFunc` members (see above).
     *
     */
    fluid.messageResolver.lookup = function (that, messagecodes) {
        var resolved = fluid.messageResolver.resolveOne(that.messageBase, messagecodes);
        if (resolved === undefined) {
            return fluid.find(that.options.parents, function (parent) {
                return parent ? parent.lookup(messagecodes) : undefined;
            });
        } else {
            return {template: resolved, resolveFunc: that.options.resolveFunc};
        }
    };

    /**
     *
     * Look up the first message that corresponds to a message code found in `messageCodes`.  Then, resolve its
     * localised value.  By default, supports variable substitutions using `fluid.stringTemplate`.
     *
     * @param {Object} that - The component itself.
     * @param {Array} messagecodes - A list of message codes to look for.
     * @param {Object} args - A map of variables that may potentially be used as part of the final output.
     * @return {String} - The final message, localised, with any variables found in `args`.
     *
     */
    fluid.messageResolver.resolve = function (that, messagecodes, args) {
        if (!messagecodes) {
            return "[No messagecodes provided]";
        }
        messagecodes = fluid.makeArray(messagecodes);
        var looked = that.lookup(messagecodes);
        return looked ? looked.resolveFunc(looked.template, args) :
            "[Message string for key " + messagecodes[0] + " not found]";
    };


    // unsupported, NON-API function
    fluid.messageResolver.resolveOne = function (messageBase, messagecodes) {
        for (var i = 0; i < messagecodes.length; ++i) {
            var code = messagecodes[i];
            var message = messageBase[code];
            if (message !== undefined) {
                return message;
            }
        }
    };

    /**
     *
     * Converts a data structure consisting of a mapping of keys to message strings, into a "messageLocator" function
     * which maps an array of message codes, to be tried in sequence until a key is found, and an array of substitution
     * arguments, into a substituted message string.
     *
     * @param {Object} messageBase - A body of messages to wrap in a resolver function.
     * @param {Function} resolveFunc (Optional) - A "resolver" function to use instead of the default `fluid.stringTemplate`.
     * @return {Function} - A "messageLocator" function (see above).
     *
     */
    fluid.messageLocator = function (messageBase, resolveFunc) {
        var resolver = fluid.messageResolver({messageBase: messageBase, resolveFunc: resolveFunc});
        return function (messagecodes, args) {
            return resolver.resolve(messagecodes, args);
        };
    };

    /**
     *
     * Resolve a "message source", which is either itself a resolver, or an object representing a bundle of messages
     * and the associated resolution function.
     *
     * When passing a "data" object, it is expected to have a `type` element that is set to `data`, and to have a
     * `messages` array and a `resolveFunc` function that can be used to resolve messages.
     *
     * A "resolver" is expected to be an object with a `type` element that is set to `resolver` that exposes a `resolve`
     * function.
     *
     * @param {Object} messageSource - See above.
     * @return {Function|String} - A resolve function or a `String` representing the final resolved output.
     *
     */
    fluid.resolveMessageSource = function (messageSource) {
        if (messageSource.type === "data") {
            if (messageSource.url === undefined) {
                return fluid.messageLocator(messageSource.messages, messageSource.resolveFunc);
            }
            else {
                // TODO: fetch via AJAX, and convert format if necessary
            }
        }
        else if (messageSource.type === "resolver") {
            return messageSource.resolver.resolve;
        }
    };
})(jQuery, fluid_3_0_0);