This functionality is Sneak Peek status. This means that the APIs may change. We welcome your feedback, ideas, and code, but please use caution if you use this new functionality.

fluid.messageResolver(options)

A message resolver is a small component that can be used to look up message codes, inject string fragments into the messages, and return full strings. For most renderer components, a message resolver is automatically created by the Framework. In most other cases, you will likely create a message resolver as a subcomponent in your component tree. See Notes below for more details.

fluid.messageResolver(options);

File name: Fluid.js

Parameters

options (Object) (optional) A collection of name-value pairs that configure the behaviour of the message resolver. See Options below for more information.

Return Value

Object

A message resolver component object. See below for more information about how to use this object.

Notes

Tutorial - Renderer Components (i.e. components assigned a grade of "fluid.rendererComponent") will automatically have a message resolver if the strings option is provided. (If a message resolver is provided to the renderer component through the messageSource option, it will be attached to the renderer component.)

Options

The options parameter is an optional collection of name-value pairs that configure the message resolver:

Name	Description	Values	Default
`messageBase`	An object containing key/value pairs representing the message keys and the localized text associated with them.	Object	{ }
`parents`	An array of alternative message resolvers that will be searched if a requested key is not found in the current resolver's message base.	Array of fluid.messageResolver	`[]`
`parseFunc`	A function that will be used to pre-process the `messageBase` when the resolver is created.	function	`fluid.identity`
`resolveFunc`	A function that will be used to resolve any templating specified in the strings.	function	`fluid.stringTemplate`
`mergePolicy`	An object specifying how to merge options. This is only used in rare cases; the default is typically adequate.	Object	mergePolicy: { messageBase: "nomerge", parents: "nomerge" }

Functions

lookup(keys)

Accepts an array of keys to look up in the object provided by messageBase for the current and parent resolvers. It searches through keys and returns an object that contains the first found value. If nothing was found, it returns undefined. This function first searches the messageBase from the current resolver, then searches in parent resolvers. Note: The parent bundles are only searched if none of the message keys are found in the current bundle.

NOTE: This function does NOT carry out any template resolution on the resulting string (see fluid.stringTemplate for more information about string templating). If resolution is desired, use resolve() (see below).

Parameters

keys

(Array of strings) The list of keys to look up.

Return Value

Object

an object containing the first matching string and the component's resolver function. The object has the following format

{
    template: <first matching string>,
    resolveFunc: <resolver function provided in options>
}

or, undefined if nothing is found.

Examples

var bundle = {
    key1: "value1",
    key2: "value2"
    key3: "value3"
};
var resolver = fluid.messageResolver({messageBase: bundle});

var looked = resolver.lookup(["nokey", "key2"]);
var result = looked ? looked.template : looked;  // returns "value2"

In the example on the left, the messageResolver searches first for "nokey", then for "key2", and returns the first found value, which is the value for "key2".

var bundle = {
    key1: "value1b",
    key3: "value3b"
};
var parentBundle = {
    key1: "value1a",
    key2: "value2a"
};

var parentResolver = fluid.messageResolver({messageBase: parentBundle});
var resolver = fluid.messageResolver({messageBase: bundle, parents: [parentResolver]});

var looked = resolver.lookup(["key2", "key1"]);
var result = looked ? looked.template : looked;  // returns "value1b"

looked = resolver.lookup(["key4", "key2"]);
result = looked ? looked.template : looked;  // returns "value2a"

In the example on the left, the first lookup (at line 13) searches the current bundle for both "key2" and "key1". Since "key1" is found in the current bundle, it is returned, despite the fact that the first key, "key2" is present in the parent bundle.

The second lookup (at line 16) searches the current bundle for both "key4" and "key2". Since neither exist, it then searches the parent bundle and finds the second key, "key2".

resolve(keys, argsArray)

Accepts a key or an array of keys to look up (as described above, in lookup()). If a string is found the resolver function is used to resolve any string templates (see fluid.stringTemplate for more information about string templating).

Parameters

`keys`	(String or Array of strings) A key to look up, or an array of keys to look up.
`args`	(Optional) arguments that will be forwarded to the resolver function specified by the `resolveFunc` option.

Return Value

String the first found value, resolved for any templating, or undefined if nothing was found.

Example

var bundle = {
    paused: "Paused at: %atFile of %totalFiles files (%atSize of %totalSize)"
};
var data = {
    atFile: 12,
    totalFiles: 14,
    atSize: "100 Kb",
    totalSize: "12000 Gb"
};
var resolver = fluid.messageResolver({messageBase: bundle});

var result = resolver.resolve("paused", data);
// result will contain "Paused at: 12 of 14 files (100 Kb of 12000Gb)"

Infusion Documentation

This documentation is currently being moved to our new documentation site.

Please view or edit the documentation there, instead.

fluid.messageResolver