class sap.ui.core.Configuration.FormatSettings

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

Encapsulates configuration settings that are related to data formatting/parsing.

Note: When format configuration settings are modified through this class, UI5 only ensures that formatter objects created after that point in time will honor the modifications. To be on the safe side, applications should do any modifications early in their lifecycle or recreate any model/UI that is locale dependent.


Constructor

new sap.ui.core.Configuration.FormatSettings()

Methods Overview

Method Description
addCustomCurrencies

Adds custom currencies to the existing entries. E.g. { "KWD": {"digits": 3}, "TND" : {"digits": 3} }

References:

  • sap.ui.core.Configuration.FormatSettings#setCustomCurrencies

sap.ui.core.Configuration.FormatSettings.extend

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

getCustomCurrencies

Retrieves the custom currencies. E.g. { "KWD": {"digits": 3}, "TND" : {"digits": 3} }

getDatePattern

Returns the currently set date pattern or undefined if no pattern has been defined.

getFormatLocale

Returns the locale to be used for formatting.

If no such locale has been defined, this method falls back to the language, see Configuration.getLanguage().

If any user preferences for date, time or number formatting have been set, and if no format locale has been specified, then a special private use subtag is added to the locale, indicating to the framework that these user preferences should be applied.

getLegacyDateCalendarCustomizing

Returns the currently set customizing data for Islamic calendar support

getLegacyDateFormat

Returns the currently set legacy ABAP date format (its id) or undefined if none has been set.

getLegacyNumberFormat

Returns the currently set legacy ABAP number format (its id) or undefined if none has been set.

getLegacyTimeFormat

Returns the currently set legacy ABAP time format (its id) or undefined if none has been set.

sap.ui.core.Configuration.FormatSettings.getMetadata

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

getNumberSymbol

Returns the currently set number symbol of the given type or undefined if no symbol has been defined.

getTimePattern

Returns the currently set time pattern or undefined if no pattern has been defined.

getTrailingCurrencyCode

Returns current trailingCurrencyCode configuration for new NumberFormatter instances

setCustomCurrencies

Sets custom currencies and replaces existing entries.

There is a special currency code named "DEFAULT" that is optional. In case it is set it will be used for all currencies not contained in the list, otherwise currency digits as defined by the CLDR will be used as a fallback.

Example: To use CLDR, but override single currencies { "KWD": {"digits": 3}, "TND" : {"digits": 3} }

To replace the CLDR currency digits completely { "DEFAULT": {"digits": 2}, "ADP": {"digits": 0}, ... "XPF": {"digits": 0} }

Note: To unset the custom currencies: call with undefined

setDatePattern

Defines the preferred format pattern for the given date format style.

Calling this method with a null or undefined pattern removes a previously set pattern.

If a pattern is defined, it will be preferred over patterns derived from the current locale.

See class sap.ui.core.format.DateFormat for details about the pattern syntax.

After changing the date pattern, the framework tries to update localization specific parts of the UI. See the documentation of sap.ui.core.Configuration#setLanguage for details and restrictions.

setFirstDayOfWeek

Defines the day used as the first day of the week.

The day is set as an integer value between 0 (Sunday) and 6 (Saturday). Calling this method with a null or undefined symbol removes a previously set value.

If a value is defined, it will be preferred over values derived from the current locale.

Usually in the US the week starts on Sunday while in most European countries on Monday. There are special cases where you want to have the first day of week set independent of the user locale.

After changing the first day of week, the framework tries to update localization specific parts of the UI. See the documentation of sap.ui.core.Configuration#setLanguage for details and restrictions.

setLegacyDateCalendarCustomizing

Allows to specify the customizing data for Islamic calendar support

setLegacyDateFormat

Allows to specify one of the legacy ABAP date formats.

This method modifies the date patterns for 'short' and 'medium' style with the corresponding ABAP format. When called with a null or undefined format id, any previously applied format will be removed.

After changing the legacy date format, the framework tries to update localization specific parts of the UI. See the documentation of sap.ui.core.Configuration#setLanguage for details and restrictions.

setLegacyNumberFormat

Allows to specify one of the legacy ABAP number format.

This method will modify the 'group' and 'decimal' symbols. When called with a null or undefined format id, any previously applied format will be removed.

After changing the legacy number format, the framework tries to update localization specific parts of the UI. See the documentation of sap.ui.core.Configuration#setLanguage for details and restrictions.

setLegacyTimeFormat

Allows to specify one of the legacy ABAP time formats.

This method sets the time patterns for 'short' and 'medium' style to the corresponding ABAP formats and sets the day period texts to "AM"/"PM" or "am"/"pm" respectively. When called with a null or undefined format id, any previously applied format will be removed.

After changing the legacy time format, the framework tries to update localization specific parts of the UI. See the documentation of sap.ui.core.Configuration#setLanguage for details and restrictions.

setNumberSymbol

Defines the string to be used for the given number symbol.

Calling this method with a null or undefined symbol removes a previously set symbol string. Note that an empty string is explicitly allowed.

If a symbol is defined, it will be preferred over symbols derived from the current locale.

See class sap.ui.core.format.NumberFormat for details about the symbols.

After changing the number symbol, the framework tries to update localization specific parts of the UI. See the documentation of sap.ui.core.Configuration#setLanguage for details and restrictions.

setTimePattern

Defines the preferred format pattern for the given time format style.

Calling this method with a null or undefined pattern removes a previously set pattern.

If a pattern is defined, it will be preferred over patterns derived from the current locale.

See class sap.ui.core.format.DateFormat for details about the pattern syntax.

After changing the time pattern, the framework tries to update localization specific parts of the UI. See the documentation of sap.ui.core.Configuration#setLanguage for details and restrictions.

setTrailingCurrencyCode

Define whether the NumberFormatter shall always place the currency code after the numeric value, with the only exception of right-to-left locales, where the currency code shall be placed before the numeric value. Default configuration setting is true.

When set to false the placement of the currency code is done dynamically, depending on the configured locale using data provided by the Unicode Common Locale Data Repository (CLDR).

Each currency instance (sap.ui.core.format.NumberFormat.getCurrencyInstance) will be created with this setting unless overwritten on instance level.

addCustomCurrencies

Adds custom currencies to the existing entries. E.g. { "KWD": {"digits": 3}, "TND" : {"digits": 3} }

References:

Param Type DefaultValue Description
mCurrencies object

adds to the currency map

sap.ui.core.Configuration.FormatSettings.extend

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

getCustomCurrencies

Retrieves the custom currencies. E.g. { "KWD": {"digits": 3}, "TND" : {"digits": 3} }

getDatePattern

Returns the currently set date pattern or undefined if no pattern has been defined.

getFormatLocale

Returns the locale to be used for formatting.

If no such locale has been defined, this method falls back to the language, see Configuration.getLanguage().

If any user preferences for date, time or number formatting have been set, and if no format locale has been specified, then a special private use subtag is added to the locale, indicating to the framework that these user preferences should be applied.

getLegacyDateCalendarCustomizing

Returns the currently set customizing data for Islamic calendar support

getLegacyDateFormat

Returns the currently set legacy ABAP date format (its id) or undefined if none has been set.

getLegacyNumberFormat

Returns the currently set legacy ABAP number format (its id) or undefined if none has been set.

getLegacyTimeFormat

Returns the currently set legacy ABAP time format (its id) or undefined if none has been set.

sap.ui.core.Configuration.FormatSettings.getMetadata

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

getNumberSymbol

Returns the currently set number symbol of the given type or undefined if no symbol has been defined.

getTimePattern

Returns the currently set time pattern or undefined if no pattern has been defined.

getTrailingCurrencyCode

Returns current trailingCurrencyCode configuration for new NumberFormatter instances

setCustomCurrencies

Sets custom currencies and replaces existing entries.

There is a special currency code named "DEFAULT" that is optional. In case it is set it will be used for all currencies not contained in the list, otherwise currency digits as defined by the CLDR will be used as a fallback.

Example: To use CLDR, but override single currencies { "KWD": {"digits": 3}, "TND" : {"digits": 3} }

To replace the CLDR currency digits completely { "DEFAULT": {"digits": 2}, "ADP": {"digits": 0}, ... "XPF": {"digits": 0} }

Note: To unset the custom currencies: call with undefined

Param Type DefaultValue Description
mCurrencies object

currency map which is set

setDatePattern

Defines the preferred format pattern for the given date format style.

Calling this method with a null or undefined pattern removes a previously set pattern.

If a pattern is defined, it will be preferred over patterns derived from the current locale.

See class sap.ui.core.format.DateFormat for details about the pattern syntax.

After changing the date pattern, the framework tries to update localization specific parts of the UI. See the documentation of sap.ui.core.Configuration#setLanguage for details and restrictions.

Param Type DefaultValue Description
sStyle string

must be one of short, medium, long or full.

sPattern string

the format pattern to be used in LDML syntax.

setFirstDayOfWeek

Defines the day used as the first day of the week.

The day is set as an integer value between 0 (Sunday) and 6 (Saturday). Calling this method with a null or undefined symbol removes a previously set value.

If a value is defined, it will be preferred over values derived from the current locale.

Usually in the US the week starts on Sunday while in most European countries on Monday. There are special cases where you want to have the first day of week set independent of the user locale.

After changing the first day of week, the framework tries to update localization specific parts of the UI. See the documentation of sap.ui.core.Configuration#setLanguage for details and restrictions.

Param Type DefaultValue Description
iValue int

must be an integer value between 0 and 6

setLegacyDateCalendarCustomizing

Allows to specify the customizing data for Islamic calendar support

Param Type DefaultValue Description
aMappings object[]

contains the customizing data for the support of Islamic calendar.

dateFormat string

The date format

islamicMonthStart string

The Islamic date

gregDate string

The corresponding Gregorian date

setLegacyDateFormat

Allows to specify one of the legacy ABAP date formats.

This method modifies the date patterns for 'short' and 'medium' style with the corresponding ABAP format. When called with a null or undefined format id, any previously applied format will be removed.

After changing the legacy date format, the framework tries to update localization specific parts of the UI. See the documentation of sap.ui.core.Configuration#setLanguage for details and restrictions.

Param Type DefaultValue Description
sFormatId string

id of the ABAP data format (one of '1','2','3','4','5','6','7','8','9','A','B','C')

setLegacyNumberFormat

Allows to specify one of the legacy ABAP number format.

This method will modify the 'group' and 'decimal' symbols. When called with a null or undefined format id, any previously applied format will be removed.

After changing the legacy number format, the framework tries to update localization specific parts of the UI. See the documentation of sap.ui.core.Configuration#setLanguage for details and restrictions.

Param Type DefaultValue Description
sFormatId string

id of the ABAP number format set (one of ' ','X','Y')

setLegacyTimeFormat

Allows to specify one of the legacy ABAP time formats.

This method sets the time patterns for 'short' and 'medium' style to the corresponding ABAP formats and sets the day period texts to "AM"/"PM" or "am"/"pm" respectively. When called with a null or undefined format id, any previously applied format will be removed.

After changing the legacy time format, the framework tries to update localization specific parts of the UI. See the documentation of sap.ui.core.Configuration#setLanguage for details and restrictions.

Param Type DefaultValue Description
sFormatId string

id of the ABAP time format (one of '0','1','2','3','4')

setNumberSymbol

Defines the string to be used for the given number symbol.

Calling this method with a null or undefined symbol removes a previously set symbol string. Note that an empty string is explicitly allowed.

If a symbol is defined, it will be preferred over symbols derived from the current locale.

See class sap.ui.core.format.NumberFormat for details about the symbols.

After changing the number symbol, the framework tries to update localization specific parts of the UI. See the documentation of sap.ui.core.Configuration#setLanguage for details and restrictions.

Param Type DefaultValue Description
sStyle string

must be one of decimal, group, plusSign, minusSign.

sSymbol string

will be used to represent the given symbol type

setTimePattern

Defines the preferred format pattern for the given time format style.

Calling this method with a null or undefined pattern removes a previously set pattern.

If a pattern is defined, it will be preferred over patterns derived from the current locale.

See class sap.ui.core.format.DateFormat for details about the pattern syntax.

After changing the time pattern, the framework tries to update localization specific parts of the UI. See the documentation of sap.ui.core.Configuration#setLanguage for details and restrictions.

Param Type DefaultValue Description
sStyle string

must be one of short, medium, long or full.

sPattern string

the format pattern to be used in LDML syntax.

setTrailingCurrencyCode

Define whether the NumberFormatter shall always place the currency code after the numeric value, with the only exception of right-to-left locales, where the currency code shall be placed before the numeric value. Default configuration setting is true.

When set to false the placement of the currency code is done dynamically, depending on the configured locale using data provided by the Unicode Common Locale Data Repository (CLDR).

Each currency instance (sap.ui.core.format.NumberFormat.getCurrencyInstance) will be created with this setting unless overwritten on instance level.

Param Type DefaultValue Description
bTrailingCurrencyCode boolean

Whether currency codes shall always be placed after the numeric value