setCurrencyFormat

Creates a format that can be used with Currency values.

The currency symbol, often present in these format patterns, can appear in the formatted result in various forms depending on the attributes of this command. The attribute currencyIsoCode defines the currency to be displayed, but the symbol representing that currency is defined by locale. Depending on the locale, the symbol for the US dollar could be either "$" or "USD", for example. If the symbol defined this way is not satisfactory, the currencySymbol attribute may be used to directly set the symbol to a String of any kind.

Attributes

name

Required

Value type

EL-evaluated

No

String

Yes

Defines a name for the created format. If defined, other commands can choose to use this format by referring to it by this name.

Leaving the created format nameless declares it as the default format for Currency values. Any command that prints out a Currency value will then use this format, unless the command specifies a named format for itself. If a default format for Currency values has already been set, this new format will take its place as the default.

locale

Required

Value type

EL-evaluated

No

String

Yes

Specifies a locale for this format, affecting the formatting rules. The resolved String should be an ISO-639 language code and an ISO-3166 country code, joined by a hyphen or an underscore (eg. "en-US" or "en_US"). Alternatively the value may only specify the language code, but this may lead to unpredictable results if this format requires the country information.

If not defined, the format will follow the user's default locale.

currencyIsoCode

Required

Value type

EL-evaluated

No

String

Yes

Defines the currency of this format. The resolved String should be an ISO 4217 currency code.

If not defined, the currency of this format will be the same as that of the active user's Salesforce organization. If the organization uses multiple currencies, then the currency will be the default currency set for the user.

pattern

Required

Value type

EL-evaluated

No

String

Yes

The value of this attribute is used as the pattern defining what kind of Strings this format will produce.

If not defined, a locale-dependent standard pattern will be used.

currencySymbol

Required

Value type

EL-evaluated

No

String

Yes

Defines the currency symbol appearing in the formatted Currency value. Whatever String this attribute resolves into will be used as the symbol.

If not defined, a locale-dependent default value will be used.

decimalSeparator

Required

Value type

EL-evaluated

No

String

Yes

Defines the decimal separator for this format.

If not defined, a locale-dependent decimal separator is used.

groupingSeparator

Required

Value type

EL-evaluated

No

String

Yes

Defines the grouping separator for the format.

If not defined, a locale-dependent default grouping separator is used.

roundingMode

Required

Value type

EL-evaluated

No

String

Yes

Defines the rounding mode for the format. The possible values are the following:

HALF_UP
Rounding mode to round towards "nearest neighbor" unless both neighbors are equidistant, in which case round up. Behaves as for UP if the discarded fraction is >= 0.5; otherwise, behaves as for DOWN. Note that this is the rounding mode commonly taught at school.
HALF_DOWN
Rounding mode to round towards "nearest neighbor" unless both neighbors are equidistant, in which case round down. Behaves as for UP if the discarded fraction is > 0.5; otherwise, behaves as for DOWN.
HALF_EVEN
Rounding mode to round towards the "nearest neighbor" unless both neighbors are equidistant, in which case, round towards the even neighbor. Behaves as for HALF_UP if the digit to the left of the discarded fraction is odd; behaves as for HALF_DOWN if it's even. Note that this is the rounding mode that statistically minimizes cumulative error when applied repeatedly over a sequence of calculations. It is sometimes known as "Banker's rounding," and is chiefly used in the USA.
UP
Rounding mode to round away from zero. Always increments the digit prior to a non-zero discarded fraction. Note that this rounding mode never decreases the magnitude of the calculated value.
DOWN
Rounding mode to round towards zero. Never increments the digit prior to a discarded fraction (i.e., truncates). Note that this rounding mode never increases the magnitude of the calculated value.
CEILING
Rounding mode to round towards positive infinity. If the result is positive, behaves as for UP; if negative, behaves as for DOWN. Note that this rounding mode never decreases the calculated value.
FLOOR
Rounding mode to round towards negative infinity. If the result is positive, behave as for DOWN; if negative, behave as for RoundingMode.UP. Note that this rounding mode never increases the calculated value.

If not defined, the HALF_EVEN mode is used.

Examples

A common detail in displaying currencies is where the currency symbols should be, or how many of the decimal digits are displayed. Here are a few sample formats for the currency displays:

CODE

<setCurrencyFormat name="noDecimals" pattern="¤ #######"><setCurrencyFormat name="noSymbol" pattern="#######.##"><setCurrencyFormat name="twoDecimals" pattern="#######.00 ¤">