class sap.ui.core.Configuration

Control sample: sap.ui.core.Configuration
Visiblity: public
UX Guidelines:
Implements:
Available since: N/A
Module: sap/ui/core/Configuration
Application Component: CA-UI5-COR

Collects and stores the configuration of the current environment.

The Configuration is initialized once when the sap.ui.core.Core is created. There are different ways to set the environment configuration (in ascending priority):

  1. System defined defaults
  2. Server wide defaults, read from /sap-ui-config.json
  3. Properties of the global configuration object window["sap-ui-config"]
  4. A configuration string in the data-sap-ui-config attribute of the bootstrap tag.
  5. Individual data-sap-ui-xyz attributes of the bootstrap tag
  6. Using URL parameters
  7. Setters in this Configuration object (only for some parameters)

That is, attributes of the DOM reference override the system defaults, URL parameters override the DOM attributes (where empty URL parameters set the parameter back to its system default). Calling setters at runtime will override any previous settings calculated during object creation.

The naming convention for parameters is:

where PARAMETER-NAME is the name of the parameter in lower case.

Values of boolean parameters are case insensitive where "true" and "x" are interpreted as true.


Constructor

Creates a new Configuration object.

new sap.ui.core.Configuration()

Methods Overview

Method Description
applySettings

Applies multiple changes to the configuration at once.

If the changed settings contain localization related settings like language or calendarType, then only a single localizationChanged event will be fired. As the framework has to inform all existing components, elements, models etc. about localization changes, using applySettings can significantly reduce the overhead for multiple changes, esp. when they occur after the UI has been created already.

The mSettings can contain any property xyz for which a setter method setXYZ exists in the API of this class. Similarly, values for the format settings API can be provided in a nested object with name formatSettings.

sap.ui.core.Configuration.extend

Creates a new subclass of class sap.ui.core.Configuration 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.base.Object.extend.

getAccessibility

Returns whether the accessibility mode is used or not.

getActiveTerminologies

Returns the list of active terminologies defined via the Configuration.

getAllowlistService

URL of the allowlist service.

getAnimation

Returns whether the animations are globally used.

Since 1.50.0 replaced by {@link sap.ui.core.Configuration#getAnimationMode}
getAnimationMode

Returns the current animation mode.

getAppCacheBuster

Base URLs to AppCacheBuster ETag-Index files.

getAppCacheBusterHooks

Object defining the callback hooks for the AppCacheBuster like e.g. handleURL, onIndexLoad or onIndexLoaded.

getAppCacheBusterMode

The loading mode (sync|async|batch) of the AppCacheBuster (sync is default)

getApplication

The name of the application to start or empty.

Since 1.15.1 Please use {@link module:sap/ui/core/ComponentSupport} instead. See also {@link topic:82a0fcecc3cb427c91469bc537ebdddf Declarative API for Initial Components}.
getAutoAriaBodyRole

Returns whether the framework automatically adds automatically the ARIA role 'application' to the HTML body or not.

getCompatibilityVersion

Returns the used compatibility version for the given feature.

getControllerCodeDeactivated

Return whether the controller code is deactivated. During design mode the.

getDebug

Returns whether the page runs in debug mode.

getDesignMode

Return whether the design mode is active or not.

getDisableCustomizing

Flag, whether the customizing is disabled or not.

getFiori2Adaptation

Returns whether the Fiori2Adaptation is on.

getFlexibilityServices

Returns the URL from where the UI5 flexibility services are called; if empty, the flexibility services are not called.

getFormatLocale

Returns the format locale string with language and region code. Falls back to language configuration, in case it has not been explicitly defined.

getFormatSettings

Returns a configuration object that bundles the format settings of UI5.

getFrameOptions

frameOptions mode (allow/deny/trusted).

getInspect

Returns whether the UI5 control inspector is displayed. Has only an effect when the sap-ui-debug module has been loaded

getLanguage

Returns a string that identifies the current language.

The value returned by this methods in most cases corresponds to the exact value that has been configured by the user or application or that has been determined from the user agent settings. It has not been normalized, but has been validated against a relaxed version of BCP47 , allowing underscores ('_') instead of the suggested dashes ('-') and not taking the case of letters into account.

The exceptions mentioned above affect languages that have been specified via the URL parameter sap-language. That parameter by definition represents an SAP logon language code ('ABAP language'). Most but not all of these language codes are valid ISO639 two-letter languages and as such are valid BCP47 language tags. For better BCP47 compliance, the framework maps the following non-BCP47 SAP logon codes to a BCP47 substitute:

   "ZH"  -->  "zh-Hans"         // script 'Hans' added to distinguish it from zh-Hant
   "ZF"  -->  "zh-Hant"         // ZF is not a valid ISO639 code, use the compliant language + script 'Hant'
   "1Q"  -->  "en-US-x-saptrc"  // special language code for supportability (tracing),
                                   represented as en-US with a private extension
   "2Q"  -->  "en-US-x-sappsd"  // special language code for supportability (pseudo translation),
                                   represented as en-US with a private extension
   "3Q"  -->  "en-US-x-saprigi" // special language code for the Rigi pseudo language,
                                   represented as en-US with a private extension

For a normalized BCP47 tag, call #getLanguageTag or call #getLocale to get a Locale object matching the language.

getLanguageTag

Returns a BCP47-compliant language tag for the current language.

The return value of this method is especially useful for an HTTP Accept-Language header.

Retrieves the modern locale, e.g. sr-Latn (Serbian (Cyrillic)), he (Hebrew), yi (Yiddish)

getLocale

Returns a Locale object for the current language.

The Locale is derived from the language property.

getManifestFirst

Flag whether a Component should load the manifest first.

sap.ui.core.Configuration.getMetadata

Returns a metadata object for class sap.ui.core.Configuration.

getNoDuplicateIds

Returns whether there should be an exception on any duplicate element IDs.

getOriginInfo

Returns whether the text origin information is collected.

getRootComponent

The name of the root component to start or empty.

Since 1.95 Please use {@link module:sap/ui/core/ComponentSupport} instead. See also {@link topic:82a0fcecc3cb427c91469bc537ebdddf Declarative API for Initial Components}.
getRTL

Returns whether the page uses the RTL text direction.

If no mode has been explicitly set (neither true nor false), the mode is derived from the current language setting.

getSAPLogonLanguage

Returns an SAP logon language for the current language.

It will be returned in uppercase. e.g. "EN", "DE"

getSecurityTokenHandlers

Returns the security token handlers of an OData V4 model.

References:

  • #setSecurityTokenHandlers

getSuppressDeactivationOfControllerCode

Return whether the activation of the controller code is suppressed.

getTheme

Returns the theme name

getUIDPrefix

Prefix to be used for automatically generated control IDs. Default is a double underscore "__".

getVersion

Returns the version of the framework.

Similar to sap.ui.version.

getWhitelistService

URL of the whitelist service.

Since 1.85.0 Use {@link sap.ui.core.Configuration#getAllowlistService} instead. SAP strives to replace insensitive terms with inclusive language. Since APIs cannot be renamed or immediately removed for compatibility reasons, this API has been deprecated.
setAnimationMode

Sets the current animation mode.

Expects an animation mode as string and validates it. If a wrong animation mode was set, an error is thrown. If the mode is valid it is set, then the attributes data-sap-ui-animation and data-sap-ui-animation-mode of the HTML document root element are also updated. If the animationMode is Configuration.AnimationMode.none the old animation property is set to false, otherwise it is set to true.

setCalendarType

Sets the new calendar type to be used from now on in locale dependent functionality (for example, formatting, translation texts, etc.).

setFlexibilityServices

Sets the UI5 flexibility services configuration.

setFormatLocale

Sets a new format locale to be used from now on for retrieving locale specific formatters. Modifying this setting does not have an impact on the retrieval of translated texts!

Can either be set to a concrete value (a BCP47 or Java locale compliant language tag) or to null. When set to null (default value) then locale specific formatters are retrieved for the current language.

After changing the format locale, the framework tries to update localization specific parts of the UI. See the documentation of #setLanguage for details and restrictions.

Note: When a format locale is set, it has higher priority than a number, date or time format defined with a call to setLegacyNumberFormat, setLegacyDateFormat or setLegacyTimeFormat.

Note: See documentation of #setLanguage for restrictions.

setLanguage

Sets a new language to be used from now on for language/region dependent functionality (e.g. formatting, data types, translated texts, ...).

When the language can't be interpreted as a BCP47 language (using the relaxed syntax described in #getLanguage, an error will be thrown.

When the language has changed, the Core will fire its localizationChanged event.

Restrictions

The framework does not guarantee that already created, language dependent objects will be updated by this call. It therefore remains best practice for applications to switch the language early, e.g. before any language dependent objects are created. Applications that need to support more dynamic changes of the language should listen to the localizationChanged event and adapt all language dependent objects that they use (e.g. by rebuilding their UI).

Currently, the framework notifies the following objects about a change of the localization settings before it fires the localizationChanged event:

  • date and number data types that are used in property bindings or composite bindings in existing Elements, Controls, UIAreas or Components
  • ResourceModels currently assigned to the Core, a UIArea, Component, Element or Control
  • Elements or Controls that implement the onlocalizationChanged hook (note the lowercase 'l' in onlocalizationChanged)

It furthermore derives the RTL mode from the new language, if no explicit RTL mode has been set. If the RTL mode changes, the following additional actions will be taken:

  • the URLs of already loaded library theme files will be changed
  • the dir attribute of the page will be changed to reflect the new mode.
  • all UIAreas will be invalidated (which results in a rendering of the whole UI5 UI)

This method does not accept SAP language codes for sLanguage. Instead, a second parameter sSAPLogonLanguage can be provided with an SAP language code corresponding to the given language. A given value will be returned by the #getSAPLogonLanguage method. It is up to the caller to provide a consistent pair of BCP47 language and SAP language code. The SAP language code is only checked to be of length 2 and must consist of letters or digits only.

Note: When using this method please take note of and respect the above mentioned restrictions.

References:

  • http://scn.sap.com/docs/DOC-14377

setRTL

Sets the character orientation mode to be used from now on.

Can either be set to a concrete value (true meaning right-to-left, false meaning left-to-right) or to null which means that the character orientation mode should be derived from the current language (incl. region) setting.

After changing the character orientation mode, the framework tries to update localization specific parts of the UI. See the documentation of #setLanguage for details and restrictions.

Note: See documentation of #setLanguage for restrictions.

setSecurityTokenHandlers

Sets the security token handlers for an OData V4 model. See chapter "Security Token Handling" in Model Instantiation and Data Access.

References:

  • #getSecurityTokenHandlers

applySettings

Applies multiple changes to the configuration at once.

If the changed settings contain localization related settings like language or calendarType, then only a single localizationChanged event will be fired. As the framework has to inform all existing components, elements, models etc. about localization changes, using applySettings can significantly reduce the overhead for multiple changes, esp. when they occur after the UI has been created already.

The mSettings can contain any property xyz for which a setter method setXYZ exists in the API of this class. Similarly, values for the format settings API can be provided in a nested object with name formatSettings.

Param Type DefaultValue Description
mSettings object

Configuration options to apply

sap.ui.core.Configuration.extend

Creates a new subclass of class sap.ui.core.Configuration 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.base.Object.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

getAccessibility

Returns whether the accessibility mode is used or not.

getActiveTerminologies

Returns the list of active terminologies defined via the Configuration.

getAllowlistService

URL of the allowlist service.

getAnimation

Returns whether the animations are globally used.

Since 1.50.0 replaced by {@link sap.ui.core.Configuration#getAnimationMode}

getAnimationMode

Returns the current animation mode.

getAppCacheBuster

Base URLs to AppCacheBuster ETag-Index files.

getAppCacheBusterHooks

Object defining the callback hooks for the AppCacheBuster like e.g. handleURL, onIndexLoad or onIndexLoaded.

getAppCacheBusterMode

The loading mode (sync|async|batch) of the AppCacheBuster (sync is default)

getApplication

The name of the application to start or empty.

Since 1.15.1 Please use {@link module:sap/ui/core/ComponentSupport} instead. See also {@link topic:82a0fcecc3cb427c91469bc537ebdddf Declarative API for Initial Components}.

getAutoAriaBodyRole

Returns whether the framework automatically adds automatically the ARIA role 'application' to the HTML body or not.

getCompatibilityVersion

Returns the used compatibility version for the given feature.

Param Type DefaultValue Description
sFeature string

the key of desired feature

getControllerCodeDeactivated

Return whether the controller code is deactivated. During design mode the.

getDebug

Returns whether the page runs in debug mode.

getDesignMode

Return whether the design mode is active or not.

getDisableCustomizing

Flag, whether the customizing is disabled or not.

getFiori2Adaptation

Returns whether the Fiori2Adaptation is on.

getFlexibilityServices

Returns the URL from where the UI5 flexibility services are called; if empty, the flexibility services are not called.

getFormatLocale

Returns the format locale string with language and region code. Falls back to language configuration, in case it has not been explicitly defined.

getFormatSettings

Returns a configuration object that bundles the format settings of UI5.

getFrameOptions

frameOptions mode (allow/deny/trusted).

getInspect

Returns whether the UI5 control inspector is displayed. Has only an effect when the sap-ui-debug module has been loaded

getLanguage

Returns a string that identifies the current language.

The value returned by this methods in most cases corresponds to the exact value that has been configured by the user or application or that has been determined from the user agent settings. It has not been normalized, but has been validated against a relaxed version of BCP47 , allowing underscores ('_') instead of the suggested dashes ('-') and not taking the case of letters into account.

The exceptions mentioned above affect languages that have been specified via the URL parameter sap-language. That parameter by definition represents an SAP logon language code ('ABAP language'). Most but not all of these language codes are valid ISO639 two-letter languages and as such are valid BCP47 language tags. For better BCP47 compliance, the framework maps the following non-BCP47 SAP logon codes to a BCP47 substitute:

   "ZH"  -->  "zh-Hans"         // script 'Hans' added to distinguish it from zh-Hant
   "ZF"  -->  "zh-Hant"         // ZF is not a valid ISO639 code, use the compliant language + script 'Hant'
   "1Q"  -->  "en-US-x-saptrc"  // special language code for supportability (tracing),
                                   represented as en-US with a private extension
   "2Q"  -->  "en-US-x-sappsd"  // special language code for supportability (pseudo translation),
                                   represented as en-US with a private extension
   "3Q"  -->  "en-US-x-saprigi" // special language code for the Rigi pseudo language,
                                   represented as en-US with a private extension

For a normalized BCP47 tag, call #getLanguageTag or call #getLocale to get a Locale object matching the language.

getLanguageTag

Returns a BCP47-compliant language tag for the current language.

The return value of this method is especially useful for an HTTP Accept-Language header.

Retrieves the modern locale, e.g. sr-Latn (Serbian (Cyrillic)), he (Hebrew), yi (Yiddish)

getLocale

Returns a Locale object for the current language.

The Locale is derived from the language property.

getManifestFirst

Flag whether a Component should load the manifest first.

sap.ui.core.Configuration.getMetadata

Returns a metadata object for class sap.ui.core.Configuration.

getNoDuplicateIds

Returns whether there should be an exception on any duplicate element IDs.

getOriginInfo

Returns whether the text origin information is collected.

getRootComponent

The name of the root component to start or empty.

Since 1.95 Please use {@link module:sap/ui/core/ComponentSupport} instead. See also {@link topic:82a0fcecc3cb427c91469bc537ebdddf Declarative API for Initial Components}.

getRTL

Returns whether the page uses the RTL text direction.

If no mode has been explicitly set (neither true nor false), the mode is derived from the current language setting.

getSAPLogonLanguage

Returns an SAP logon language for the current language.

It will be returned in uppercase. e.g. "EN", "DE"

getSecurityTokenHandlers

Returns the security token handlers of an OData V4 model.

References:

getSuppressDeactivationOfControllerCode

Return whether the activation of the controller code is suppressed.

getTheme

Returns the theme name

getUIDPrefix

Prefix to be used for automatically generated control IDs. Default is a double underscore "__".

getVersion

Returns the version of the framework.

Similar to sap.ui.version.

getWhitelistService

URL of the whitelist service.

Since 1.85.0 Use {@link sap.ui.core.Configuration#getAllowlistService} instead. SAP strives to replace insensitive terms with inclusive language. Since APIs cannot be renamed or immediately removed for compatibility reasons, this API has been deprecated.

setAnimationMode

Sets the current animation mode.

Expects an animation mode as string and validates it. If a wrong animation mode was set, an error is thrown. If the mode is valid it is set, then the attributes data-sap-ui-animation and data-sap-ui-animation-mode of the HTML document root element are also updated. If the animationMode is Configuration.AnimationMode.none the old animation property is set to false, otherwise it is set to true.

Param Type DefaultValue Description
sAnimationMode sap.ui.core.Configuration.AnimationMode

A valid animation mode

setCalendarType

Sets the new calendar type to be used from now on in locale dependent functionality (for example, formatting, translation texts, etc.).

Param Type DefaultValue Description
sCalendarType sap.ui.core.CalendarType null

the new calendar type. Set it with null to clear the calendar type and the calendar type is calculated based on the format settings and current locale.

setFlexibilityServices

Sets the UI5 flexibility services configuration.

Param Type DefaultValue Description
aFlexibilityServices object[]

Connector configuration

connector string

Name of the connector

applyConnector string

Name of the full module name of the custom apply connector

writeConnector string

Name of the full module name of the custom write connector

custom boolean false

Flag to identify the connector as custom or fl owned

url string

Url for requests sent by the connector

path string

Path for loading data in the ObjectPath connector

layers sap.ui.fl.Layer[]

List of layers in which the connector is allowed to write

setFormatLocale

Sets a new format locale to be used from now on for retrieving locale specific formatters. Modifying this setting does not have an impact on the retrieval of translated texts!

Can either be set to a concrete value (a BCP47 or Java locale compliant language tag) or to null. When set to null (default value) then locale specific formatters are retrieved for the current language.

After changing the format locale, the framework tries to update localization specific parts of the UI. See the documentation of #setLanguage for details and restrictions.

Note: When a format locale is set, it has higher priority than a number, date or time format defined with a call to setLegacyNumberFormat, setLegacyDateFormat or setLegacyTimeFormat.

Note: See documentation of #setLanguage for restrictions.

Param Type DefaultValue Description
sFormatLocale string null

the new format locale as a BCP47 compliant language tag; case doesn't matter and underscores can be used instead of dashes to separate components (compatibility with Java Locale IDs)

setLanguage

Sets a new language to be used from now on for language/region dependent functionality (e.g. formatting, data types, translated texts, ...).

When the language can't be interpreted as a BCP47 language (using the relaxed syntax described in #getLanguage, an error will be thrown.

When the language has changed, the Core will fire its localizationChanged event.

Restrictions

The framework does not guarantee that already created, language dependent objects will be updated by this call. It therefore remains best practice for applications to switch the language early, e.g. before any language dependent objects are created. Applications that need to support more dynamic changes of the language should listen to the localizationChanged event and adapt all language dependent objects that they use (e.g. by rebuilding their UI).

Currently, the framework notifies the following objects about a change of the localization settings before it fires the localizationChanged event:

It furthermore derives the RTL mode from the new language, if no explicit RTL mode has been set. If the RTL mode changes, the following additional actions will be taken:

This method does not accept SAP language codes for sLanguage. Instead, a second parameter sSAPLogonLanguage can be provided with an SAP language code corresponding to the given language. A given value will be returned by the #getSAPLogonLanguage method. It is up to the caller to provide a consistent pair of BCP47 language and SAP language code. The SAP language code is only checked to be of length 2 and must consist of letters or digits only.

Note: When using this method please take note of and respect the above mentioned restrictions.

References:

Param Type DefaultValue Description
sLanguage string

the new language as a BCP47 compliant language tag; case doesn't matter and underscores can be used instead of dashes to separate components (compatibility with Java Locale IDs)

sSAPLogonLanguage string

SAP language code that corresponds to the sLanguage; if a value is specified, future calls to getSAPLogonLanguage will return that value; if no value is specified, the framework will use the ISO639 language part of sLanguage as SAP Logon language.

setRTL

Sets the character orientation mode to be used from now on.

Can either be set to a concrete value (true meaning right-to-left, false meaning left-to-right) or to null which means that the character orientation mode should be derived from the current language (incl. region) setting.

After changing the character orientation mode, the framework tries to update localization specific parts of the UI. See the documentation of #setLanguage for details and restrictions.

Note: See documentation of #setLanguage for restrictions.

Param Type DefaultValue Description
bRTL boolean null

new character orientation mode or null

setSecurityTokenHandlers

Sets the security token handlers for an OData V4 model. See chapter "Security Token Handling" in Model Instantiation and Data Access.

References:

Param Type DefaultValue Description
aSecurityTokenHandlers function[]

The security token handlers