Resource Loader

Edit on GitHub

The Infusion Resource Loader fluid.resourceLoader is an Infusion component which offers a mechanism to load multiple physical files in one shot. These resources can be HTML templates, JSON objects or any other resources. On completion, the resource loader fires an onResourcesLoaded event with an argument of the populated structure with fetched resource text in the field "resourceText" for each entry. This populated structure can also be retrieved directly on the resource loader instance via the path resources.

The underlying implementation of fluid.resourceLoader is the low-level fluid.fetchResources API which in turn defers to jQuery.ajax.

Although we show an example here of constructing the resource loader as a free-standing component, a more typical usage would be as a subcomponent in a wider component tree:

var resourceLoader = fluid.resourceLoader([options]);

Parameters

options (Object) Configuration options. See Options below for more information.

Return Value

Object

(Object) The resource loader instance.

Options

Name	Description	Values	Default
`terms`	Contains a map of variable names and replacement values to compose the path to each physical file. The map structure complies with the format of the second `terms` argument of fluid.stringTemplate() API. Also see Using String Templates for more information.	Object	`{}`
`resources`	Contains a map of resource names and paths to these resources. These paths can be actual path strings, for example, `../data/template.html`, or templating strings with embedded variables that have mapped replacement values defined in the `term` option, for example, `%prefix/template.html`. The format of templating paths complies with the format of the `template` argument of fluid.stringTemplate() API.	Object	`{}`
`locale`	Specifies the language code with the desired localization. Language codes are expected in a form similar to BCP 47 tags but with a "_" instead of a "-" separating the language code from the country code. When specified, the resource loader will add a suffix of the locale value to each entry defined in the `resources` and look for them at the first attempt. If any such resource is not located, the resource loader follows Fallback Rules to attempt to find aother localization.	String	`null`
`defaultLocale`	Specifies the default language code. Provides a fallback to use if the desired localization cannot be located. See `locale` option for the format of language codes. Also See Fallback Rules for when `defaultLocale` value will be used.	String	`null`
`resourceOptions`	Contains "options" holding raw options to be forwarded to jQuery.ajax().	Object	`{}`

Fallback Rules with locale and defaultLocale

locale and defaultLocale options can be used to load localized resources, for example, to load messages in different languages.

fluid.defaults("fluid.messageLoader", {
    gradeNames: ["fluid.resourceLoader"],
    resources: {
        translation: "../data/translation.json"
    },
    locale: "fr_CA",
    defaultLocale: "en_US"
});

This example requests to load a JSON file that contains translations. The fluid.messageLoader follows fallback rules below to satisfy the request:

look for a suffixed resource corresponding to the language code specified by the locale option: ../data/translation-fr_CA.json
look for a suffixed resource with the same language as the language code specified by the locale option: ../data/translation-fr.json
look for a suffixed resource corresponding to the language code specified by the defaultLocale option: ../data/translation-en_US.json
look for a suffixed resource with the same language as the language code specified by the defaultLocale option: ../data/translation-en.json
look for a resource with the exact URL as specified through the resources option: ../data/translation.json

Events

Name	Description	Arguments
`onResourcesLoaded`	Fired when all resources are finished loading.	A populated object with fetched resource text in the field `resourceText` for each entry. If an error occurs during a fetch, the `fetchError` field will be populated for that entry. This object can also be retrieved directly on the resource loader instance via the path `resources`.

Using fluid.resourceLoader

The example below demonstrates when and how to use the fetched resource text in an IoC component tree. Generally speaking, the part that requires the fetched resources needs to postpone the instantiation via createOnEvent until resources are ready.

fluid.defaults("fluid.UI", {
    gradeNames: ["fluid.viewComponent"],
    components: {
        templateLoader: {
            type: "fluid.resourceLoader",
            options: {
                terms: {
                    prefix: "../data"
                },
                resources: {
                    template: "%prefix/testTemplate.html"
                },
                listeners: {
                    "onResourcesLoaded.escalate": "{fluid.UI}.events.onTemplatesReady"
                }
            }
        },
        renderUI: {
            type: "fluid.viewComponent",
            container: "{fluid.UI}.container",
            createOnEvent: "onTemplatesReady",
            options: {
                listeners: {
                    "onCreate.appendTemplate": {
                        "this": "{that}.container",
                        "method": "append",
                        args: ["{templateLoader}.resources.template.resourceText"]
                    }
                }
            }
        }
    },
    events: {
        onTemplatesReady: null
    }
});

var UI = fluid.UI(".flc-UI");