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