Difference between revisions of "X-Cart:MultiCurrency"

From X-Cart 4 Classic
Jump to: navigation, search
(Overview)
m
 
(20 intermediate revisions by 3 users not shown)
Line 1: Line 1:
 
==Overview==
 
==Overview==
  
'''MultiCurrency''' is an add-on that allows using multiple currencies at customer's front end.
+
'''MultiCurrency''' is an add-on module that allows your store to display product prices in multiple currencies.
  
 
: [[Image:XC_MultiCurrency01.png]]
 
: [[Image:XC_MultiCurrency01.png]]
  
The module features:
+
Back-end features:
 +
* Ability to define any number of currencies in addition to the store's primary currency
 +
* Ability to set currency rates manually or automatically based on data from reputable online currency converters
  
* Changing your online store's  default currency.
+
Front-end features:
* Defining any number of additional currencies.
+
* Display of product prices in the customers' local currencies
* Automatically displaying prices in your customers' local currencies.
+
* Ability for customers to specify their country, as well as the language and currency they would like to use for store browsing
 +
* Automatic identification of the geographical location (country) of new visitors by their IP address and pre-selection of currency and language for them according to the detected country
  
and much more.
+
{{Note|All the actual charges occur in your store's primary currency. Prices displayed in any other currency are for informational purposes only. The accuracy of price calculations in other currencies depends on the exchange rate defined in the module settings, and the order total may differ from the actual amount to be charged, especially for large numbers of products.}}
  
{{Note|All the actual charges occur in your store's default currency. Prices displayed in any other currency are for informational purposes only. The accuracy of price calculations in other currencies depends on the exchange rate set forth in the module settings, and the order total may differ from the actual amount to be charged, especially for large numbers of products.}}
+
: [[Image:XC_MultiCurrency02.png]]
  
: [[Image:XC_MultiCurrency02.png]]
+
==System requirements and installation==
 +
 
 +
Starting from X-Cart version 4.5.3, '''MultiCurrency''' is available as a built-in module in X-Cart GOLD PLUS and PLATINUM editions. In the said editions the module does not require installation and can be enabled in the <u>Modules</u> section of X-Cart Admin area.
  
== System requirements ==
+
For X-Cart GOLD and PRO versions 4.4.x and 4.5.x, '''MultiCurrency''' is available as an add-on module which can be purchased and installed separately. The instructions below will guide you through the process of installing the '''MultiCurrency''' add-on module in your store.
  
To be able to successfully install and use the MultiCurrency module, you must have a working copy of X-Cart Gold or X-Cart Pro already installed on your server. Make sure that the version of the MultiCurrency module matches the version of your copy of X-Cart.
+
=== System requirements ===
  
{{Note|If you do not remember the version of your copy of X-Cart, you can find it in the <u>Summary/Environment info</u> section of the X-Cart Admin area (select<u>Administration</u> -> <u>Summary</u>) on the menu.}}
+
To be able to successfully install and use the MultiCurrency module, you need a working copy of X-Cart GOLD or PRO v4.4.x or later installed on your server. Make sure that the version of the MultiCurrency module matches the version of your copy of X-Cart.
  
==Installation and removal==
+
{{Note|If you do not remember the version of your copy of X-Cart, you can find it in the <u>Environment info</u> section of the [[X-Cart:Summary_Page |Summary]] page in X-Cart Admin area.}}
  
These instructions on both installing and removing the MultiCurrency module are the same for both X-Cart Gold and X-Cart Pro.
+
===Installation and removal===
  
 
'''To install the MultiCurrency module to your X-Cart based store:'''
 
'''To install the MultiCurrency module to your X-Cart based store:'''
Line 51: Line 56:
 
3. In a web browser, run the installation script at httр://www.example.com/install-xmulticurrency.php, replacing the variable www.example.com with the real domain name, where your X-Cart is installed.
 
3. In a web browser, run the installation script at httр://www.example.com/install-xmulticurrency.php, replacing the variable www.example.com with the real domain name, where your X-Cart is installed.
  
4. Enter the Auth code, accept the License Agreement and click the '''Next''' button.
+
4. Enter the [[X-Cart:FAQs#What_is_Auth_code_and_where_can_I_find_it.3F|Auth code]], accept the License Agreement and click the '''Next''' button.
 
 
{{Note|The Auth code is a random code that was generated after you installed your copy of X-Cart. If you do not remember the Auth code, find it in the Summary section of the X-Cart Admin area (select <u>Tools</u>-><u>Summary</u> on the administration menu), right over the License info subsection. Another way to find out the code is to retrieve the value of the $installation_auth_code variable from the file <u><xcart_dir>include/install.php</u> .}}
 
  
 
5. The installation script copies the files and activates the module. Click the '''Next '''button to continue.
 
5. The installation script copies the files and activates the module. Click the '''Next '''button to continue.
Line 66: Line 69:
 
1. In a web browser, run the installation script at http://www.example.com/install-xmulticurrency.php, replacing the "www.example.com" with the real domain name, where your X-Cart is installed.
 
1. In a web browser, run the installation script at http://www.example.com/install-xmulticurrency.php, replacing the "www.example.com" with the real domain name, where your X-Cart is installed.
  
2. Choose the <u>Uninstall the module</u> option, enter the Auth code, accept the License Agreement and click the '''Next''' button.
+
2. Choose the <u>Uninstall the module</u> option, enter the [[X-Cart:FAQs#What_is_Auth_code_and_where_can_I_find_it.3F|Auth code]], accept the License Agreement and click the '''Next''' button.
 
 
{{Note1|Note: The Auth code is a random code that was generated after you installed your copy of X-Cart. If you do not remember the Auth code, find it in the Summary section of the X-Cart Admin area (select <u>Tools</u>-><u>Summary</u> on the administration menu), right over the License info subsection. Another way to find out the code is to retrieve the value of the $installation_auth_code variable from the file <u><xcart_dir>include/install.php</u> .}}
 
  
 
3. Once the installation script has removed the MultiCurrency files and deactivated the module, click the '''Next''' button to complete the uninstallation.
 
3. Once the installation script has removed the MultiCurrency files and deactivated the module, click the '''Next''' button to complete the uninstallation.
Line 87: Line 88:
  
 
3. Scroll down to the bottom of the page and click the '''Apply changes''' button to save changes.
 
3. Scroll down to the bottom of the page and click the '''Apply changes''' button to save changes.
 +
 +
: [[Image:XC_MultiCurrency03.png]]
  
 
== Using MultiCurrency ==
 
== Using MultiCurrency ==
  
 
To get started with MultiCurrency, go to the <u>Currency management</u> page and set up the currencies to be used in your store.
 
To get started with MultiCurrency, go to the <u>Currency management</u> page and set up the currencies to be used in your store.
 +
 +
: [[Image:XC_MultiCurrency04.png]]
 +
  
 
'''To open the <u>Currency management</u> page:'''
 
'''To open the <u>Currency management</u> page:'''
Line 96: Line 102:
 
1. Log in to the X-Cart Admin area.
 
1. Log in to the X-Cart Admin area.
  
2. Select the <u>Currencies</u> item on the Settings menu.
+
2. Select the <u>Currencies</u> item on the <u>Settings</u> menu.
 +
 
  
 
'''To add new currency:'''
 
'''To add new currency:'''
Line 105: Line 112:
  
 
3. Click the '''Add currency''' button.
 
3. Click the '''Add currency''' button.
 +
 +
: [[Image:XC_MultiCurrency05.png]]
  
 
The new currency now appears on the Currencies list.
 
The new currency now appears on the Currencies list.
 +
  
 
'''To delete currency:'''
 
'''To delete currency:'''
Line 112: Line 122:
 
1. On the <u>Currency management</u> page, find the <u>Currencies list</u> section.
 
1. On the <u>Currency management</u> page, find the <u>Currencies list</u> section.
  
2. On the Currencies list, click the red X icon by the currency to be deleted.
+
2. On the Currencies list, click the red [[Image:XC_MultiCurrencyDel.png]] icon by the currency to be deleted.
  
 
The deleted currency no longer appears on the Currencies list.
 
The deleted currency no longer appears on the Currencies list.
Line 123: Line 133:
  
 
1. On the Currencies list, click on the '''Primary''' radio button by the currency to be set as primary.
 
1. On the Currencies list, click on the '''Primary''' radio button by the currency to be set as primary.
 +
 +
: [[Image:XC_MultiCurrency06.png]]
  
 
2. Click the '''Apply changes''' button to save the selection.
 
2. Click the '''Apply changes''' button to save the selection.
Line 133: Line 145:
  
 
Here are the fields you can edit:
 
Here are the fields you can edit:
 +
 +
: [[Image:XC_MultiCurrency07.png]]
  
 
* '''Symbol''' - a graphic symbol used as a shorthand for a currency's name. For more information, please refer to the [http://en.wikipedia.org/wiki/Currency_sign Currency sign] article in Wikipedia.
 
* '''Symbol''' - a graphic symbol used as a shorthand for a currency's name. For more information, please refer to the [http://en.wikipedia.org/wiki/Currency_sign Currency sign] article in Wikipedia.
Line 145: Line 159:
  
 
'''Exchange rate''' shows the rate at which the selected currency will be exchanged for one unit of the primary currency.
 
'''Exchange rate''' shows the rate at which the selected currency will be exchanged for one unit of the primary currency.
 +
 +
: [[Image:XC_MultiCurrency08.png]]
 +
  
 
'''To enter exchange rate manually:'''
 
'''To enter exchange rate manually:'''
Line 151: Line 168:
  
 
2. Click the '''Apply changes''' button to save changes.
 
2. Click the '''Apply changes''' button to save changes.
 +
  
 
'''To get current exchange rate from online service:'''
 
'''To get current exchange rate from online service:'''
Line 160: Line 178:
 
3. Click the '''Update rates right now button''' to get current exchange rate for currencies on your list.
 
3. Click the '''Update rates right now button''' to get current exchange rate for currencies on your list.
  
'''To get current exchange rate automatically:'''  
+
 
 +
'''To get current exchange rate automatically:'''
  
 
1. On the <u>Currency management</u> page, find the <u>Update rates</u> section.
 
1. On the <u>Currency management</u> page, find the <u>Update rates</u> section.
Line 166: Line 185:
 
2. On the '''Online service''' select box, select the online currency conversion service to retrieve data from.
 
2. On the '''Online service''' select box, select the online currency conversion service to retrieve data from.
  
3. Select the '''Automatically update currency exchange rates daily''' check box.  
+
3. Select the '''Automatically update currency exchange rates daily''' check box.
  
 
4. Click the '''Apply changes''' button to save changes.
 
4. Click the '''Apply changes''' button to save changes.
Line 173: Line 192:
  
 
The MultiCurrency module adds a popup selector, which allows customers to select language (when several languages defined), currency (when more than one currency specified) and country. First time visitors' country is detected automatically by their IP address. Language and currency are preselected according to the detected country and remembered in cookies. You can disable changing country on the popup selector.
 
The MultiCurrency module adds a popup selector, which allows customers to select language (when several languages defined), currency (when more than one currency specified) and country. First time visitors' country is detected automatically by their IP address. Language and currency are preselected according to the detected country and remembered in cookies. You can disable changing country on the popup selector.
 +
 +
: [[Image:XC_MultiCurrency09.png]]
 +
  
 
'''To allow/disallow customers to select country:'''
 
'''To allow/disallow customers to select country:'''
Line 183: Line 205:
  
 
You can also limit the list of available countries by those that use currencies defined on the Currencies list.
 
You can also limit the list of available countries by those that use currencies defined on the Currencies list.
 +
  
 
'''To limit the list of available countries:'''
 
'''To limit the list of available countries:'''
Line 191: Line 214:
  
 
3. Click the '''Apply changes''' button to save changes.
 
3. Click the '''Apply changes''' button to save changes.
 +
 +
[[Category:X-Cart modules]]

Latest revision as of 14:21, 21 August 2013

Overview

MultiCurrency is an add-on module that allows your store to display product prices in multiple currencies.

XC MultiCurrency01.png

Back-end features:

  • Ability to define any number of currencies in addition to the store's primary currency
  • Ability to set currency rates manually or automatically based on data from reputable online currency converters

Front-end features:

  • Display of product prices in the customers' local currencies
  • Ability for customers to specify their country, as well as the language and currency they would like to use for store browsing
  • Automatic identification of the geographical location (country) of new visitors by their IP address and pre-selection of currency and language for them according to the detected country
Note: All the actual charges occur in your store's primary currency. Prices displayed in any other currency are for informational purposes only. The accuracy of price calculations in other currencies depends on the exchange rate defined in the module settings, and the order total may differ from the actual amount to be charged, especially for large numbers of products.
XC MultiCurrency02.png

System requirements and installation

Starting from X-Cart version 4.5.3, MultiCurrency is available as a built-in module in X-Cart GOLD PLUS and PLATINUM editions. In the said editions the module does not require installation and can be enabled in the Modules section of X-Cart Admin area.

For X-Cart GOLD and PRO versions 4.4.x and 4.5.x, MultiCurrency is available as an add-on module which can be purchased and installed separately. The instructions below will guide you through the process of installing the MultiCurrency add-on module in your store.

System requirements

To be able to successfully install and use the MultiCurrency module, you need a working copy of X-Cart GOLD or PRO v4.4.x or later installed on your server. Make sure that the version of the MultiCurrency module matches the version of your copy of X-Cart.

Note: If you do not remember the version of your copy of X-Cart, you can find it in the Environment info section of the Summary page in X-Cart Admin area.

Installation and removal

To install the MultiCurrency module to your X-Cart based store:

1. Obtain a distribution package for the MultiCurrency module by downloading it from the File Area section of your X-Cart Account account. The distribution package is archived in the file x-multicurrency-x.y.z.tgz, where x, y and z indicate the version of the module. Make sure the version of the module matches the version of your copy of X-Cart.

2. Copy the distribution package to the X-Cart root directory on your server or hosting account.

  • If you use a Windows-based server or a UNIX-based server without terminal access:
a) Extract the contents of the archive with the MultiCurrency files to a directory on your system using your favorite compression program (WinZIP or any other archiver that supports TAR files).
b) Use an FTP client to upload all the files extracted from the archive (retaining the directory structure) to the X-Cart root directory on your server or hosting account.
  • If you use a UNIX-based server with terminal access:
a) Use an FTP client to upload the archive with the MultiCurrency distribution package to the X-Cart root directory on your server or hosting account.
b) Decompress the package by typing the following command:
tar -xzvf x-multicurrency-x.y.z.tgz
Important: Make sure that you maintain the directory structure while unpacking and uploading the distribution package; otherwise, some critical files can be overwritten!

3. In a web browser, run the installation script at httр://www.example.com/install-xmulticurrency.php, replacing the variable www.example.com with the real domain name, where your X-Cart is installed.

4. Enter the Auth code, accept the License Agreement and click the Next button.

5. The installation script copies the files and activates the module. Click the Next button to continue.

6. The installation script generates a new system fingerprint. Click the Next button to complete the installation.

7. Use the ADMINISTRATOR AREA link to log in to the Admin area.


To uninstall the MultiCurrency module:

1. In a web browser, run the installation script at http://www.example.com/install-xmulticurrency.php, replacing the "www.example.com" with the real domain name, where your X-Cart is installed.

2. Choose the Uninstall the module option, enter the Auth code, accept the License Agreement and click the Next button.

3. Once the installation script has removed the MultiCurrency files and deactivated the module, click the Next button to complete the uninstallation.

4. On the Uninstallation complete screen, click Next to leave the Wizard.

Important: After you have uninstalled the MultiCurrency module, make sure to remove the module's distribution package from your web directory as well.

Enabling MultiCurrency module in X-Cart

Once you have installed the MultiCurrency module, enable it in the X-Cart Admin area.

To enable the MultiCurrency module:

1. Log in to the X-Cart Admin area and go to the Modules section (select Settings -> Modules on the administration menu).

2. On the list of modules, find the "MultiCurrency" item and select the check box by the item's name.

3. Scroll down to the bottom of the page and click the Apply changes button to save changes.

XC MultiCurrency03.png

Using MultiCurrency

To get started with MultiCurrency, go to the Currency management page and set up the currencies to be used in your store.

XC MultiCurrency04.png


To open the Currency management page:

1. Log in to the X-Cart Admin area.

2. Select the Currencies item on the Settings menu.


To add new currency:

1. On the Currency management page, find the Add currency section.

2. Select the currency to be added on the Add currency select box.

3. Click the Add currency button.

XC MultiCurrency05.png

The new currency now appears on the Currencies list.


To delete currency:

1. On the Currency management page, find the Currencies list section.

2. On the Currencies list, click the red XC MultiCurrencyDel.png icon by the currency to be deleted.

The deleted currency no longer appears on the Currencies list.

Managing currencies

Defining primary currency

To define primary currency:

1. On the Currencies list, click on the Primary radio button by the currency to be set as primary.

XC MultiCurrency06.png

2. Click the Apply changes button to save the selection.

Editing currency

To edit currency:

On the Currencies list, simply modify the editable fields as necessary and click the Apply changes button to save changes.

Here are the fields you can edit:

XC MultiCurrency07.png
  • Symbol - a graphic symbol used as a shorthand for a currency's name. For more information, please refer to the Currency sign article in Wikipedia.
  • Format - order of character sequence in price expression: currency symbol followed by a numeric value or vice versa.
  • Number format - order of digits and signs (comma, period, space) in the numeric value.
  • Rate - currency exchange rate; can be entered manually or retrieved automatically from an online currency conversion service.

Currency exchange rate

Exchange rate shows the rate at which the selected currency will be exchanged for one unit of the primary currency.

XC MultiCurrency08.png


To enter exchange rate manually:

1. On the Currencies list, modify the Rate field as necessary for the selected currency.

2. Click the Apply changes button to save changes.


To get current exchange rate from online service:

1. On the Currency management page, find the Update rates section.

2. On the Online service select box, select the online currency conversion service to retrieve data from.

3. Click the Update rates right now button to get current exchange rate for currencies on your list.


To get current exchange rate automatically:

1. On the Currency management page, find the Update rates section.

2. On the Online service select box, select the online currency conversion service to retrieve data from.

3. Select the Automatically update currency exchange rates daily check box.

4. Click the Apply changes button to save changes.

Advanced options

The MultiCurrency module adds a popup selector, which allows customers to select language (when several languages defined), currency (when more than one currency specified) and country. First time visitors' country is detected automatically by their IP address. Language and currency are preselected according to the detected country and remembered in cookies. You can disable changing country on the popup selector.

XC MultiCurrency09.png


To allow/disallow customers to select country:

1. On the Currency management page, find the Update selector options section.

2. Select the Allow customers to select country check box.

3. Click the Apply changes button to save changes.

You can also limit the list of available countries by those that use currencies defined on the Currencies list.


To limit the list of available countries:

1. On the Currency management page, find the Update selector options section.

2. Select the List only countries with currencies set on the currency list check box.

3. Click the Apply changes button to save changes.