Skip to Main Content

Namespace: locale

QuickNav

Functions

apex.locale

The apex.locale namespace contains Oracle Application Express functions related to formatting numbers and dates according to a specific locale. For localizing text messages see apex.lang.

Since:
  • 20.1

Functions

(static) formatCompactNumber(pValue, pOptionsopt) → {string}

Formats the given number in a compact, locale specific way. For example in the US English locale the number 123400 would be formatted as "123.4K" and 1234000 as "1.23M".

This function relies on additional resources that are loaded when the page first loads. Calling this function before the resources are loaded returns the number as an unformatted string. See apex.locale.resourcesLoaded.

Parameters:
Name Type Attributes Description
pValue number The number value to be formatted.
pOptions object <optional>
 An options object that affect the way the number is formatted. All properties optional.
Properties
Name Type Description
maximumFractionDigits number The maximum number of digits to display after the decimal point. Default 2.
minimumFractionDigits number The minimum number of digits to display after the decimal point. Default 0.
minimumIntegerDigits number The minimum number of integer digits to display before the decimal point. Default 1.
roundingMode string One of 'DEFAULT', 'HALF_UP', 'HALF_DOWN', 'HALF_EVEN', 'UP', 'DOWN', 'CEILING', 'FLOOR'. The default is "DEFAULT".
separators string The characters to use for the decimal and group separator. The default is to use the appropriate locale specific characters.
Properties
Name Type Description
decimal string The decimal separator character.
group string The group separator character.
useGrouping boolean If true use locale specific rules to separate digits into groups. The default is true.
Returns:
The compact formatted number.
Type
string
Examples

Format the large number 123456789.12 in a compact format and display it in an alert message.

var largeNumber = 123456789.12;
var formattedNumber = apex.locale.formatCompactNumber( largeNumber );
// In the US English locale this will display: "The number is: 123.46M"
apex.message.alert( "The number is: " + formattedNumber, function() {
     // do something after message is shown if needed
} );

Format the same large number 123456789.12 in a compact format using an option to not include any fraction digits.

var largeNumber = 123456789.12;
var formattedNumber = apex.locale.formatCompactNumber( largeNumber, { maximumFractionDigits: 0 } );
// In the US English locale the formattedNumber is equal to 123M"

(static) formatNumber(pValue, pFormatopt, pOptionsopt) → {string}

Formats a number using a database format model similar to the SQL TO_CHAR(number) function.

See the Oracle SQL Language reference section on Format Models for more information on the pFormat parameter. The format elements RN, TM, and EEEE are not supported.

Parameters:
Name Type Attributes Description
pValue number The number to format.
pFormat string <optional>
 The database format model. The format elements RN, TM, and EEEE are not supported. If the format is not given the number is returned as a string with no additional formatting.
pOptions object <optional>
 Options to override default locale settings. All properties optional.
Properties
Name Type Description
NLS_NUMERIC_CHARACTERS string A string where the first letter is the decimal separator and the second letter is the group separator
NLS_CURRENCY string The local currency string.
NLS_DUAL_CURRENCY string The dual currency string.
NLS_ISO_CURRENCY string The ISO currency string. Note: This option differs from the corresponding database parameter. It is the ISO currency string such as "CAD" rather than the territory name such as "CANADA".
Returns:
The formatted number.
Type
string
Example

Format the number 1234.569 with locale specific currency symbol and 2 decimal places.

var formattedNumber = apex.locale.formatNumber( 1234.569, "FML999G999G999G999G990D00" );
// In the US English locale this will display: "The cost is: $1,234.57"
apex.message.alert( "The cost is: " + formattedNumber, function() {
     // do something after message is shown if needed
} );

(static) getAbbrevDayNames() → {array}

Return the database abbreviated day names as an array. First element of the array is the first day of the week in the current locale.
Returns:
Array of abbreviated day names. For example ["Sun","Mon","Tue","Wed",...,"Sat"]
Type
array

(static) getAbbrevMonthNames() → {array}

Return the database abbreviated month names as an array. First element of the array is the first month of the year in the current locale.
Returns:
Array of abbreviated month names. For example ["Jan","Feb","Mar", ..., "Dec"]
Type
array

(static) getCurrency() → {string}

Return the database locale specific currency symbol.
Returns:
Type
string

(static) getDecimalSeparator() → {string}

Return the database locale specific decimal separator for numeric values.
Returns:
The decimal separator. For example "." (US) or "," (Germany).
Type
string

(static) getDualCurrency() → {string}

Return the database locale specific dual currency symbol.
Returns:
Type
string

(static) getGroupSeparator() → {string}

Return the database locale specific group separator for numeric values.
Returns:
The group separator. For example "," (US) or "." (Germany).
Type
string

(static) getISOCurrency() → {string}

Return the database locale specific ISO currency string.
Returns:
Type
string

(static) getLanguage() → {string}

Return the current language locale.
Returns:
current language. For example "en", "de", "en-US", ...
Type
string

(static) resourcesLoaded(pCallbackopt) → {Promise}

Used to determine if the resources needed by some of the apex.locale functions have been loaded.

Parameters:
Name Type Attributes Description
pCallback function <optional>
 A Function to call when the resources have been loaded. If the resources are already loaded the function is called right away.
Returns:
A promise object. The promise is resolved when the resources have been loaded.
Type
Promise
Examples

Wait until the resources are loaded before formatting a number.

apex.locale.resourcesLoaded( function() {
    var formattedNumber = apex.locale.formatCompactNumber( 123456789.12 );
    // In the US English locale this will log: "The number is: 123.46M"
    console.log( "The number is: " + formattedNumber );
} );

This is the same as the previous example except it uses the returned promise.

var p = apex.locale.resourcesLoaded();
p.done( function() {
    var formattedNumber = apex.locale.formatCompactNumber( 123456789.12 );
    // In the US English locale this will log: "The number is: 123.46M"
    console.log( "The number is: " + formattedNumber );
} );

This checks to see if the resources are loaded.

if ( apex.locale.resourcesLoaded().state() === "resolved" ) {
    // resources are loaded
} else {
    // resources are not yet loaded
}