Currency and number formatting
The display of monetary amounts varies from one country to another. Monetary values are usually accompanied by a currency symbol, which can exist in either the local currency symbols (for example,. $, , R$), or ISO 4217 international currency codes (for example, USD, EUR, BRL). Currency symbols may be placed before, within, or after the radix character of the monetary amount, and there may or may not be a space between the symbol and the amount. Although, most countries use the comma or period as the decimal separator in currency, some countries, such as Japan, do not have a currency decimal separator.
About this task
The rules for formatting numeric fields are not necessarily the same as the rules for formatting monetary amounts. Cultural formatting of numeric fields differs by country, since different countries use different positive and negative numeric representations for the same amount.
The following list shows several ways to display the same numeric values:
- 1,234.56 .123
- 1,234,560,123
- 1.234,56
Negative number representation does not have a universal form. Some countries use a leading hyphen to denote negative non-monetary numbers. Some place the hyphen after the number, and some use another symbol altogether. The following list shows several ways to display the number negative fifteen:
- -15
- 15-
- (15)
- {15}
- <15>
Some countries may have more that one official language but only one currency. Canada is a prime example where there is a single currency, Canadian dollar, but two official languages, English and French. It is complex for businesses to operate in multiple currencies. Adding a language element increases this complexity and makes pricing and other currency-related tasks almost unmanageable in the WebSphere Commerce administration tools such as the WebSphere Commerce Accelerator.
A single default currency, which may be used as the basis for conversions or explicit pricing in other currencies, makes these operational tasks clearer and better matches business practices.
Linking a store's default currency to its default language has no valid business relationship and is not a valid currency defaulting method. For example, if you change the language it should not have to mean that we want the currency changed. For this reason, the selection of language and currency are two separate tasks in WebSphere Commerce as shown in the following figure:
There is no way to define a one-to-one or one-to-many relationship between language and currency. Any given currency may be related to many languages, for example, Canadian dollar is related to both French and English. Any given language can be related to many currencies, for example, English is related to the US dollar, Canadian dollar, British Pound, and others.
WebSphere Commerce Currency Manager
In WebSphere Commerce, the shopping currency is the currency in which the customer sees all prices. To determine the shopping currency of a customer, the currency engine called the Currency Manager performs the following algorithm:
- If the store specifies and supports the customer's preferred_currency, then shopping_currency = preferred_currency.
- If the customer's preferred_currency is specified (and not supported) and it is the counter value for another_supported_currency, then shopping_currency=another_supported_currency.
- If (shopping_currency = null) then shopping_currency = store's default currency (from STOREENT table - column SETCCURR which is nullable) is not language dependent.
- If (shopping_currency = null) then shopping_currency = default currency for the language (The SETCURR column of the STORELANG table) is language dependent.
Note the following when the Currency Manager performs the preceding algorithm:
- The use of the SETCCURR column of the STORELANG table is strongly discouraged, since it may be deprecated in a future release; the column is therefore backwardly compatibility only. Your store models should not set the SETCCURR column of the STORELANG table (set it to null).
- Migrated stores can easily achieve the new behavior by setting the store default using the STOREENT table. The STORELANG table does not have to be changed. This allows some migrated stores to get the new behavior and some other migrated stores to keep the old behavior.
- Either the SETCCURR column of the store object or the storeGroup object should be set via the STOREENT table. For migrated stores, this will not be the case initially. Any new stores should set the store or storeGroup default currency. Setting the store default currency will ensure that the last step of the algorithm above will not be executed.
Currency formatting in WebSphere Commerce is dependent on the following:
- The currency (ISO three-letter code)
- The language ID
This information is required to validate or format a currency. Number formatting is dependent only on the language ID.
The Currency Manager makes all of the formatting information for numbers and currency values available in the WebSphere Commerce instance database. When the WebSphere Commerce instance application server is started, this information is turned into JavaScript and becomes available for use as part of the WebSphere Commerce Tools Framework. Import the web/tools/common/NumberFormat.jsp into your JSP for these JavaScript functions. The functions perform the following tasks:
- Validate a currency value
- Convert from currency value to numeric
- Convert from numeric to currency value
- Validate a number value
- Convert from number value to a numeric value
- Convert from a numeric value to a number value
Note: We need to include the Util.js file in your JSP when you include NumberFormat.jsp.
The following table lists some of the key JavaScript currency and formatting functions:
| Task | Integer | Number | Currency |
|---|---|---|---|
| Validate User Input (anything) | isValidInteger() | isValidNumber() | isValidCurrency() |
| Save (convert to JavaScript number) | strToNumber() | strToNumber() | currencyToNumber() |
| Display (format a JavaScript number for a given language) | numberToStr() | numberToStr() | numberToCurrency() |
Note: If we are using the notebook, wizard, or dialog UI elements, the NumberFormat is already included in the parent frame.
The following example shows a typical JavaScript currency entry form in a tools JSP:
//requirement ::provide a user input currency entry ...
//prefilling it with the previous value ...
function initializeState(){
document.myForm.myInput.value =
parent.numberToCurrency(currAmount,fCurr,"<%=fLanguageId%>");
}
function validatePanelData(){
if (!parent.isValidCurrency(document.myForm.myInput.value),fCurr,
"<%=fLanguageId%>")){
alert("not valid");
return false;
}
return true;
}
function savePanelData(){
MyCurr=parent.currencyToNumber(document.myForm.myInput.Value,fCurr,
"<%=fLanguageId%>");
parent.put("myCurrLbl",myCurr);
}
A sample validation and format page is available in \commerce\web\tools\sample\. To execute this page launch http://hostname/commerce/tools/sample/validationTest.jsp.
Important: It is highly recommend that you avoid using FormatNumber, FormatCurrency, and FormatInteger. These functions are included in the WebSphere Commerce Tools Framework only for backward compatibility.
FormatNumber and FormatCurrency do the validation first based on the language ID. If we get a primitive numeric format (1000.23) from the WebSphere Commerce Server, the functions return a Not a Number (NaN) value. Furthermore, FormatInteger only accepts primitive numeric integers. As a result, if you have an integer such as 1,000 in the US English language ID, it returns a NaN.
Related concepts
WebSphere Commerce configuration file (wc-server.xml)
Outbound messaging system
Globalized catalog content
Cultural considerations
Localized store assets
Globalization in the messaging system
Programming models for globalized stores
Globalized store design
Supporting globalization
Globalized tools framework
Related tasks
Adding a currency to WebSphere Commerce
Creating a globalized store
Date and time formatting
Name and address formatting
Related reference
Globalization tips