Resource Loader

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

NameDescriptionValuesDefault
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:

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

Events

NameDescriptionArguments
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");