Creating a new currency

The administration interface allows you to add new currencies to the webshop system. Let's say that you already have three currencies (USD, UAH and NOK) and you wish to add another one (EUR). The following example demonstrates how to add EUR when you already have USD, UAH, NOK.

1.  Click the "Webshop" tab in the administration interface, select the "Currencies" link on the left and click the "New currency" button located under the list of existing currencies. (This interface can also be accessed by requesting "/shop/currencylist" in the URL.)
    

   

   Available Currencies

    The system will bring up the currency edit interface where you can specify the desired properties for a new currency (look at the next screenshot).

Creating New Currency

      2. Specify the currency attributes (these are described below) and click the "Create" button. The system will add a new currency to the list. 

Please note that after creating a new currency the system will automatically create zero auto prices in this currency for all your products. It is recommended to click the "Update autoprices" button when you have finished managing your currencies. This will instruct the system to update auto prices for all products.

Currency code

The three-character currency code which is generally used to represent this currency ("USD", "EUR" and so on). This parameter is required. This code can be thought of as an unique identifier of the currency. You can not use two currencies with the same codes. The currency code consists of three English capital letters and often (but not always) corresponds to the ISO 4217 standard.

Once the currency code is specified, the system will be able to display the currency name ("European euro", "U.S. dollar" and so on). These currency names can be changed by providing a custom version of the "currencynames.tpl" template which is located in the "templates/shop/" directory of the standard design. This template does not have any effect on the shop functionality available for site visitors. The currency names are displayed only in the administration interface. If you have created a new currency with unknown code for example "ABC" which is not listed in the "currencynames.tpl" template, the system will display the currency name as "Unknown currency name".

Currency symbol

A currency symbol is a string that will be displayed near the numerical price value ("$", "€" and so on). Currency symbols are used in everyday life to denote that a number is a monetary value. This parameter is not required. If the currency symbol is not defined, the visitors who prefer using this currency will see the numerical price values without any additional symbols. Please note that if you are not able to type in the desired symbol then you can copy and paste it from your browser or text editor.

Formatting locale

A formatting locale is a locale which is used for price formatting. This parameter is required. You can choose the desired locale from the drop-down list of available locales. By default, the current system locale is selected (this locale is determined by the "Locale" setting located in the "[RegionalSettings]" section of the "settings/site.ini" configuration file or its override). The available locales and their settings are defined by the locale INI files located in the "share/locale" directory of your eZ Publish installation.

Once the formatting locale is specified, the system will automatically format the prices using the "DecimalSymbol", "ThousandsSeparator", "FractDigits" and "PositiveFormat" settings specified in the "[Currency]" section of the locale's INI file. Please note that the "Symbol", "Name" and "ShortName" settings defined in the same section will not have any effect in this case.

Example

Let's create a new currency "ABC" and specify its properties as shown in the following screenshot.
 

Currency Properties

 Since the "ABC" code is not listed in the "currencynames.tpl" template, the system will display the currency name as "Unknown currency name" (look at the next screenshot).
 

Unknown Currency Name

 This problem can be solved by creating a custom version of the "currencynames.tpl" which is located in the "templates/shop/" directory of the standard design. To do this, copy the "currencynames.tpl" template into the "templates/shop/" directory of the admin design and edit it. Add a new key/value pair to the list of pairs that are passed to the "hash" template operator which creates the "set_currency_names" associative array as shown below:

{set currency_names = hash( 'ABC', 'AB-Currency',
'AUD', 'Australian dollar',
...
'USD', 'U.S.dollar' ) }

After clearing the eZ Publish caches, the system will display the currency name as "AB-Currency".

The "eng-US.ini" configuration file located in the "share/locale" directory contains the following section:

[Currency]
Symbol=$
Name=US Dollar
ShortName=USD
DecimalSymbol=.
ThousandsSeparator=,
FractDigits=2
PositiveSymbol=
NegativeSymbol=-
PositiveFormat=%c%p%q
NegativeFormat=%c%p%q

Since the "eng-US" locale is selected for the "ABC" currency, the system will use "." as a decimal symbol and "," as thousands separator, with 2 digits after decimal point and the currency symbol placed before the numeric value as specified in the "DecimalSymbol", "ThousandsSeparator", "FractDigits" and "PositiveFormat" settings. (The "Symbol", "Name" and "ShortName" settings will not be used.)

Let's say that some product costs for example 550 units in this currency. In this case, the visitors who prefer using this currency will see the price of this product like this:

abc550.00

Custom rate

This required parameter tells the system about which rate to use for calculating auto prices for/in this currency. By default, the custom rate is set to 0 so the system will use auto rate for this currency. However, it is possible to specify a non-zero fixed custom rate value that will be used for calculating auto prices in this currency.

Rate factor

This required parameter is intended for supporting a kind of virtual rate that can be used for calculating auto prices in this currency. If a non-zero custom rate is specified, the system will multiply it by rate factor in order to calculate the final rate, otherwise the system will multiply the auto rate by this factor. The default value of the rate factor is 1. The following table reveals how the final rate is calculated according to the auto rate, custom rate and rate factor values.

Status

The status of the currency can be either "active or "inactive". When you create a new currency, the status will be automatically set to "Active". Inactive currencies will be invisible for the site visitors. In other words, you can hide a currency from your customers if you don't wish them to use this currency.

Inactive currencies are displayed in red color in the list of currencies as shown in the following screenshot.
 

Currency Status