class sap.ui.model.resource.ResourceModel

Visiblity: public
UX Guidelines:
Implements:
Available since: N/A
Module: sap/ui/model/resource/ResourceModel
Application Component: CA-UI5-COR

Model implementation for resource bundles.

This model is not prepared to be inherited from.

This model allows to bind control properties against translatable texts. Its data is taken from a module:sap/base/i18n/ResourceBundle and it only supports property bindings.

In contrast to most other models, binding paths for a ResourceModel must not start with a slash; they are absolute by default, and there's no further structure. Each key in the underlying resource bundle is a valid binding path.

In extensibility scenarios, the texts of the resource bundle can be enhanced with additional resource bundles. These additional bundles can define new texts for existing keys, texts for new keys, or both. When texts for existing keys are replaced, the latest enhancement wins.

This model supports the binding modes OneWay and OneTime, but not TwoWay. When the recommended asynchronous loading of the bundle is used, binding mode OneTime can't be used.


Constructor

Constructor for a new ResourceModel.

Declarative Usage

The ResourceModel can be created using configuration objects instead of ResourceBundle instances. This is the recommended way and enables:

Programmatic Usage

The ResourceModel can be created in a programmatic manner which means that ResourceBundle instances are used instead of configurations. Existing ResourceBundles can either be used in the bundle parameter or in the enhanceWith array. Runtime errors are thrown when ResourceBundle instances are used with terminologies. Also when using ResourceModel#enhance with terminologies.

new sap.ui.model.resource.ResourceModel(oData)
Param Type Default Value Description
oData object

Parameters used to initialize the ResourceModel; at least one of bundle, bundleName or bundleUrl must be set; if more than one property is set, they are evaluated in the mentioned order

activeTerminologies? string[]

The list of active terminologies, e.g. ["oil", "retail"]. This parameter is passed to the underlying ResourceBundle (see module:sap/base/i18n/ResourceBundle.create). This parameter is ignored when bundle is set. Will cause an error if enhanceWith contains instances of ResourceBundle. Supported since 1.77.0.

async? boolean false

Whether the language bundle should be loaded asynchronously

bundle? module:sap/base/i18n/ResourceBundle

A resource bundle instance; when given, this bundle is used instead of creating a bundle from the provided bundleUrl, bundleName and bundleLocale properties. However, to support reloading the bundle when the current session locale changes, the corresponding bundleName or bundleUrl should be specified if known. Otherwise, the bundle is not updated on locale changes. Note: This parameter should not be used when using enhancements. Terminologies require enhancements with bundleUrl, bundleName and bundleLocale in combination with enhanceWith which contains a list of ResourceBundle.Configurations. Terminologies must be defined in a declarative way, with configurations and not with instances of ResourceBundle.

bundleLocale? string

A locale in "BCP-47 language tag" notation specifying the locale in which to load the bundle; when not given, the current session locale of UI5 is used (recommended)

bundleName? string

UI5 module name in dot notation referring to the base ".properties" file; this name is resolved to a path just as for normal UI5 modules, to which ".properties" is then appended (e.g. a name like "myapp.i18n.myBundle" can be given); relative module names are not supported

bundleUrl? string

URL pointing to the base ".properties" file of a bundle (".properties" file without any locale information, e.g. "../../i18n/mybundle.properties"); relative URLs are evaluated relative to the document.baseURI

defaultBindingMode? sap.ui.model.BindingMode OneWay

The default binding mode to use; it can be OneWay or OneTime (only when synchronous loading is used); the TwoWay mode is not supported

enhanceWith? module:sap/base/i18n/ResourceBundle[] module:sap/base/i18n/ResourceBundle.Configuration[]

A list of resource bundles or resource bundle configurations that enhance the texts from the main bundle; intended for extensibility scenarios; see also the class documentation. ResourceBundles use the ResourceModel's enhance mechanism and ResourceBundle.Configurations get passed to the underlying ResourceBundle (see module:sap/base/i18n/ResourceBundle.create). Supported since 1.77.0.

fallbackLocale? string "en"

A fallback locale to be used after all locales derived from bundleLocale have been tried, but before the 'raw' bundle is used. Can either be a BCP47 language tag or a JDK compatible locale string (e.g. "en-GB", "en_GB" or "en").

To prevent a generic fallback, use the empty string (""). E.g. by providing fallbackLocale: "" and supportedLocales: ["en"], only the bundle "en" is requested without any fallback. This parameter is passed to the underlying ResourceBundle (see module:sap/base/i18n/ResourceBundle.create). Supported since 1.77.0.

supportedLocales? string[]

List of supported locales (aka 'language tags') to restrict the fallback chain. Each entry in the array can either be a BCP47 language tag or a JDK compatible locale string (e.g. "en-GB", "en_GB" or "en"). An empty string ("") represents the 'raw' bundle.

Note: The given language tags can use modern or legacy ISO639 language codes. Whatever language code is used in the list of supported locales will also be used when requesting a file from the server. If the bundleLocale contains a legacy language code like "sh" and the supportedLocales contains [...,"sr",...], "sr" will be used in the URL. This mapping works in both directions. This parameter is passed to the underlying ResourceBundle (see module:sap/base/i18n/ResourceBundle.create). Supported since 1.77.0.

terminologies? Object<string,module:sap/base/i18n/ResourceBundle.TerminologyConfiguration>

An object, mapping a terminology identifier (e.g. "oil") to a ResourceBundle.TerminologyConfiguration. A terminology is a resource bundle configuration for a specific use case (e.g. "oil"). It does neither have a fallbackLocale nor can it be enhanced with enhanceWith. This parameter is passed to the underlying ResourceBundle (see module:sap/base/i18n/ResourceBundle.create). This parameter is ignored when bundle is set. Will cause an error if enhanceWith contains instances of ResourceBundle. Supported since 1.77.0.


Methods Overview

Method Description
bindProperty

Gets a property binding for the given path in the resource model. Only sPath from sap.ui.model.Model#bindProperty is supported; other parameters are ignored.

enhance

Enhances the resource model with a custom resource bundle.

The custom bundle can define new texts for keys existing in the main bundle, texts for new keys, or both. A resource model can be enhanced with multiple resource bundles by calling this method multiple times. Each call appends to the list of enhancements, but no bundle can be removed from the list.

When looking up a text for a key, the enhancements are processed in reverse order. Texts from the last added resource bundle are preferred over texts from previously added bundles or texts from the main bundle.

sap.ui.model.resource.ResourceModel.extend

Creates a new subclass of class sap.ui.model.resource.ResourceModel with name sClassName and enriches it with the information contained in oClassInfo.

oClassInfo might contain the same kind of information as described in sap.ui.model.Model.extend.

sap.ui.model.resource.ResourceModel.getMetadata

Returns a metadata object for class sap.ui.model.resource.ResourceModel.

getProperty

Returns the value for the property with the given path.

getResourceBundle

Gets the resource bundle of this model.

sap.ui.model.resource.ResourceModel.loadResourceBundle

Returns the resource bundle or a promise resolving with the resource bundle.

bindProperty

Gets a property binding for the given path in the resource model. Only sPath from sap.ui.model.Model#bindProperty is supported; other parameters are ignored.

Param Type DefaultValue Description
sPath string

The path pointing to the property that should be bound; in contrast to most other models, the binding path for a ResourceModel must not start with a slash, it is absolute by default and there's no further structure. Each key in the underlying resource bundle is a valid binding path.

enhance

Enhances the resource model with a custom resource bundle.

The custom bundle can define new texts for keys existing in the main bundle, texts for new keys, or both. A resource model can be enhanced with multiple resource bundles by calling this method multiple times. Each call appends to the list of enhancements, but no bundle can be removed from the list.

When looking up a text for a key, the enhancements are processed in reverse order. Texts from the last added resource bundle are preferred over texts from previously added bundles or texts from the main bundle.

Param Type DefaultValue Description
oData module:sap/base/i18n/ResourceBundle object

Either an already loaded bundle instance, or a configuration object with parameters to load a new resource bundle. When a configuration object is given, at least one of bundleUrl or bundleName must be set; if both are set, bundleName wins

bundleLocale string

A locale in "BCP-47 language tag" notation specifying the locale in which to load the bundle; when not given, the current session locale of UI5 is used (recommended)

bundleName string

UI5 module name in dot notation, referring to the base ".properties" file; this name is resolved to a path like the paths of normal UI5 modules, and ".properties" is then appended (e.g. a name like "myapp.i18n.myBundle" can be given); relative module names are not supported

bundleUrl string

URL pointing to the base ".properties" file of a bundle (".properties" file without any locale information, e.g. "../../i18n/mybundle.properties"); relative URLs are evaluated relative to the document.baseURI

sap.ui.model.resource.ResourceModel.extend

Creates a new subclass of class sap.ui.model.resource.ResourceModel with name sClassName and enriches it with the information contained in oClassInfo.

oClassInfo might contain the same kind of information as described in sap.ui.model.Model.extend.

Param Type DefaultValue Description
sClassName string

Name of the class being created

oClassInfo object

Object literal with information about the class

FNMetaImpl function

Constructor function for the metadata object; if not given, it defaults to the metadata implementation used by this class

sap.ui.model.resource.ResourceModel.getMetadata

Returns a metadata object for class sap.ui.model.resource.ResourceModel.

getProperty

Returns the value for the property with the given path.

Param Type DefaultValue Description
sPath string

The path to the property

getResourceBundle

Gets the resource bundle of this model.

sap.ui.model.resource.ResourceModel.loadResourceBundle

Returns the resource bundle or a promise resolving with the resource bundle.

Param Type DefaultValue Description
oData object

Parameters used to load the resource bundle; see constructor of the sap.ui.model.resource.ResourceModel

activeTerminologies string[]

The list of active terminologies, e.g. ["oil", "retail"]. This parameter is passed to the underlying ResourceBundle (see module:sap/base/i18n/ResourceBundle.create). Supported since 1.77.0.

bundleLocale string

A locale in "BCP-47 language tag" notation specifying the locale in which to load the bundle; when not given, the current session locale of UI5 is used (recommended)

bundleName string

UI5 module name in dot notation referring to the base ".properties" file

bundleUrl string

URL pointing to the base ".properties" file of a bundle

enhanceWith module:sap/base/i18n/ResourceBundle[] module:sap/base/i18n/ResourceBundle.Configuration[]

A list of resource bundles or resource bundle configurations that enhance the texts from the main bundle; intended for extensibility scenarios; see also the class documentation. ResourceBundles use the ResourceModel's enhance mechanism and ResourceBundle.Configurations get passed to the underlying ResourceBundle (see module:sap/base/i18n/ResourceBundle.create). Supported since 1.77.0.

fallbackLocale string "en"

A fallback locale to be used after all locales derived from bundleLocale have been tried, but before the 'raw' bundle is used. Can either be a BCP47 language tag or a JDK compatible locale string (e.g. "en-GB", "en_GB" or "en").

To prevent a generic fallback, use the empty string (""). E.g. by providing fallbackLocale: "" and supportedLocales: ["en"], only the bundle "en" is requested without any fallback. This parameter is passed to the underlying ResourceBundle (see module:sap/base/i18n/ResourceBundle.create).

supportedLocales string[]

List of supported locales (aka 'language tags') to restrict the fallback chain. Each entry in the array can either be a BCP47 language tag or a JDK compatible locale string (e.g. "en-GB", "en_GB" or "en"). An empty string ("") represents the 'raw' bundle. Note: The given language tags can use modern or legacy ISO639 language codes. Whatever language code is used in the list of supported locales will also be used when requesting a file from the server. If the bundleLocale contains a legacy language code like "sh" and the supportedLocales contains [...,"sr",...], "sr" will be used in the URL. This mapping works in both directions. This parameter is passed to the underlying ResourceBundle (see module:sap/base/i18n/ResourceBundle.create).

terminologies Object<string,module:sap/base/i18n/ResourceBundle.TerminologyConfiguration>

An object mapping a terminology identifier (e.g. "oil") to a ResourceBundle.TerminologyConfiguration. A terminology is a resource bundle configuration for a specific use case (e.g. "oil"). It does neither have a fallbackLocale nor can it be enhanced with enhanceWith. This parameter is passed to the underlying ResourceBundle (see module:sap/base/i18n/ResourceBundle.create). Supported since 1.77.0.

bAsync boolean

Whether the resource bundle should be loaded asynchronously