CurrCon Currency Converter Manual

The CurrCon Java Applet displays prices on this
web page converted with today’s exchange rates into your local international currency,
e.g. Euros, US dollars, Canadian dollars, British Pounds, Indian Rupees…
CurrCon requires an up-to-date browser
and Java version 1.7 or later, preferably 1.8.0_31.
If you can’t see the prices in your local currency,
Troubleshoot. Use Chrome for best results.

Introduction

CurrCon stands for
Currency Converter.

The currency converter lets you display prices/amounts in the native currency of the
visitors to your website. The currency converter automatically selects the default
currency to display based on the locale country setting of the browser. It currently
supports 169 different
currencies.

The CurrCon Currency Converter is available with Java
source to download.

In other words, Americans automatically see American prices and Canadian see Canadian
prices and the Dutch see Euros. Viewers can optionally view the prices on the page in
another currency. Changing any currency selector on the page instantly
changes all the prices on the page to that currency.

Unlike most currency converters, with this one, the user does not enter amounts to be
converted. The values come from your web page. All prices on your web pages are instantly
displayed in the user’s favourite currency without him having to do anything.

Benefits

It lets you sell to an international market on the web. You quote prices in your
native currency and CurrCon deals with automatically
converting all the prices on a page to the user’s favoured currency.

If the user wants, he can flip all the prices on the page
instantaneously into any other currency. Unfortunately, that setting
is not remembered when the user flips to another page. It reverts back to his native
currency.

If you write essays that mention amounts of money, you can use CurrCon so that all these amounts are automatically converted to the
currency the reader is most familiar with. That ensures your readers fully understand
what you are saying.

I am working on a JSP-version of CurrCon that will not
require the clients to install Java. It will require you to serve the website from a
JSP (Java Server Pages) Servlet womb. and it will not allow the users to select
the currency instantly.

Disadvantages

The users must have the Java JRE (Java Runtime Environment)
installed
to view the international prices. Otherwise they will just see the original price.
See installing Java.

The user must have his country properly configured in the control panel. Otherwise
he will see the default US prices, rather than his local currency, until he selects the
currency for the page.

If you want to customise CurrCon, e.g. change the list
of currencies presented, change the colours, update your own exchange rates, you will
need to install the Java JDK,
ANT and genjar. This requires basic knowledge of Java
programming.

The <applet tags to invoke the CurrCon Applet are verbose. The alternative terser <!-- macro CurrCon tags require the use of the complex htmlmacros package. For a fee, I could prepare you a stripped down
simple macro processor.

If you have 12 or more instances of CurrCon on a single page, they will not be able to communicate with each
other. This means if you change the currency from USD to CSD (Control Structure Diagram)
the whole page will not
automatically update. You will have to update each price individually. This is caused
by a bug in Java’s AppletContext.getApplets. I have reported the bug. It existed long ago in
Java version 1.3, was fixed and seems to have come back from the dead. When
Oracle fixes it, CurrCon will automatically start working
again. This is the behaviour with Firefox, Oper and IE. It seems to work correctly in
Chrome.

Shopping Carts

If you have a shopping cart website, CurrCon is probably not what you want. Why?

The prices CurrCon displays are usually based on
today’s exchange rates. You have to explain to your customers that the prices
displayed are approximate. The prices the customer actually pays are based on the
credit card company, PayPal, your bank etc., perhaps using rates several days hence or
previous, or with hefty exchange rate commissions built-in. The price depends on the
form of payment! The discrepancies could enrage your customers.

To use CurrCon, your customers must
have a recent Java installed. This is not a problem for a technical audience, but will
frighten off computer novices.

What you want is shopping cart software than runs on you server that handles
multiple currencies that knows the exchange rates charged by your various credit card
companies and banks. It will not require your customers to have Java installed.
Unfortunately, I cannot at this point recommend any particular package. You might find
one by discovering a website what handles multiple currencies well and asking them what
software they use.

I am working on a server-side version of CurrCon that does
not need Java, however it still would not be suitable for use with shopping carts since
it would not be integrated into the shopping cart software. Perhaps some shopping cart
vendors will merge it into their products when I release it.

How It Works

Unlike most currency converters, this one requires no
server-side support. It does not require JavaScript. However, it does require Java in the
user’s browser. Each value displayed is a tiny Java Applet. All that is required is
you upload the currcon.jar file to your website. It contains
the latest exchange rates in compressed form and also the Java code to do the
conversions.

If you change the currency choice anywhere on a page, automatically all the other
displays on the page instantly follow suit. Try using the up down arrow to cycle through
the possible currencies. Try it below:

$0.00 USD

To get a display like this:

$30.00 USD

You need to code some HTML (Hypertext Markup Language) that looks like this:

<!-- macro CurrCon C$AcN USD 30.00 -->

which expands to:

Normally you might display something simpler such as this:

$30.00 USD

To get that you code some HTML like this:

<!-- macro CurrCon cA USD 30.00 -->

which expands to this:
or even simpler like this:

$30.00 USD

To get that you code some HTML like this:

<!-- macro CurrCon A USD 20.00 -->

which expands to this:

Details of the Applet Tags

Typically to produce a CurrCon display, you need something like this in your
HTML :
You may also hand code the <applet tags yourself, without
using the complexity of a macro preprocessor. What is all this gobbledgook? Happily most
of it is just boilerplate. You can copy/paste standard templates and just change the
amount.

<applet says this is a Java Applet.

archive=currcon.jar is the name
of the file where the exchange rates are kept.

code=com.mindprod.currcon.CurrCon.class is the name of the Java program
that does the conversions.

width=120 tells how much screen
width real estate in pixels to use. You must calculate the width based on how many
elements you choose to include is your show parameter: c=52 C=30 N=120 A=70 $=10. More
on that later.

height=20 The height of the
display in pixels.

alt=30.00 USD What to display if the user does not have
Java.

<param name=currency value=USD> the currency used to express the base amount, most
commonly USD for US Dollars, CAD for Canadian dollars, or EUR for Euros or GBP for British
pounds sterling. See this complete list. Every price on the page
can be expressed in a different base currency if you want.

<param name=amount value=30.00> specifies the amount in some base currency.

<param name=geom value=4>. This is used to ensure all the various CurrCon programs are using the same version of the geometry of how big
each field should be.

<param name=show value=cA> Which types of display you want to see: any combination or
order of the letters: c C N A P $. More on what they mean
later.

</applet> marks the end of information needed to
generate the display.

In HTML5 (Hypertext Markup Language version 5), you use the OBJECT tag that looks like this:

Examples Using Different Show Parameters

CurrCon Display Variations

How a $70USD
Price is displayed

Format Letter Combination

$30.00 USD

$AcN

$30.00 USD

$A

$30.00 USD

$Ac

$30.00 USD

c$A

$30.00 USD

C$A

$30.00 USD

$AC

$30.00 USD

A

$30.00 USD

N

$30.00 USD

C

$30.00 USD

c

$1,200,000.00 USD

cA

$1,200,000.00 USD

cP

Displaying Large Amounts

large amounts

CurrCon Display of Large Amounts

$1,000.00 USD

1000 USD

$1,000,000.00 USD

1,000,000 one million USD

$1,200,000.00 USD

1,200,000 1.2 million USD

$10,000,000.00 USD

10,000,000 10 million USD

$12,000,000.00 USD

12,000,000 12 million USD

$1,000,000,000.00 USD

1,000,000,000 one billion USD

$12,000,000,000.00 USD

12,000,000,000 12 billion USD

$12,300,000,000.00 USD

12,300,000,000 12.3 billion USD

$199,300,000.00 USD

19,930,000,000 19.93 billion USD, note rounding

$19,000,000,000.00 USD

19,000,000,000 19 billion USD

$19,000,000,000,000.00 USD

19,000,000,000,000 19 trillion USD

You can suppress the short forms by using code P
instead of code A.

Details of the show Parameter

show parameter

Letter

What it looks like

Changeable

Width in Pixels

Purpose

c

$0.00 USD

54

Allows user to change the currency for all displays
on the page. This was increased from 52 pixels on
2010-02-04 to handle wide abbreviations such as
KRW.

C

$0.00 USD

32

Compactly let’s user know what Currency is
being used with a three-letter abbreviation, as a display that cannot directly
changed.

N

$0.00 USD

130

Spells out the currency Name being used in
easy-to-understand words.

A

$30.00 USD

76

Show the Amount converted into the user’s
favoured currency. If there is no A in the show parameter, you need not bother
specifying the currency and amount parameters.

P

$1,900,030.00 USD

108

Show the Precise amount, converted into the
user’s favoured currency. Does not use any of the short forms for large
amounts.

$

$30.00 USD

30

Put a lead $/euro symbol etc. on the following amount.

You can use any combination of the letters c C N A P $, in any order, leaving any
out. You need to add up the widths of each piece and put that in as the width of the
entire Applet. Unfortunately CurrCon can’t add them up for you, since by the time
it starts the amount of screen real estate is already fixed. For example:

Yuch, that’s too Complicated! Macros to the Rescue

Don’t
give up yet. There are several possible alternatives to manually coding the <APPLET tags.

If you want, for no extra cost, I will write you an Java
Application to help with the show letter symbols. You fill in the blanks to
select which elements you want to display, the amount, the currency and the nesting
level and it both shows you what it will look like and pokes the equivalent
HTML<APPLET tags into clipboard where you can paste them into
your HTML document.
I have not written this HTML generator since no one has asked for it yet. It could
have it ready in a day or two.

You can just embed the short form static HTML
macros
in your HTML and have them expanded for you. It this how I handle
them on my own website. You can see the macros I use on the my own website by using
view source.

<!-- macro CurrCon cA USD 30.00 -->

expands to:
The tricky part in doing it manually is getting the right number of ../../ in the archive jar name and figuring out the exact width and
height.

I run the macro processor on all my files just prior to any upload. I expand the
macros, generate an index, compact the HTML,
and
provide a mirror website via the Replicator. The macro generator stripped
down to handle just CurrCon macros is optionally
included, but not the Compactor or the Replicator. I have not prepared the stripped
down version of the macro generator since no one has asked for it yet. It could have
it ready in a day or two at no extra cost.

You could also generate the <APPLET tags with
JSP, servlets or
ASP (Association of Shareware Professionals). I have not yet written code to do that, but I could
work with you on developing it. I have no ASP
experience at all, so all I could do in provide you
equivalent Java code. You might wonder why bother with CurrCon in that case. Why not just generate the page with the
conversions pre-expanded? The advantage of using CurrCon is
the user can switch every price on the page with a click of a mouse. He does not have
to wait for a whole new page to be generated and delivered. However, you could do it
that way, cannibalising some of CurrCon’s logic,
giving you the advantage of no reliance of a working Java in the client machine.

You could simplify the <APPLET tags by creating a
special version of CurrCon that used your usual Show tags
and base currency as the default. Further, you could leave out the material
for-non-Java users and put that somewhere on your page once.

Displaying Exchange Rates

You can also use CurrCon to display exchange rates like this:

exchange rates

1 Euro is

€1.00 EUR

$0.00 USD

1 British pound Sterling
is

1.00 GBP

1 US dollar is

$1.00 USD

1 Canadian dollar is

$1.00 CAD

1 New Zealand dollar is

1.00 NZD

Updating the Exchange Rates

Exchange rates change daily. I update
the exchange rate tables daily and post them on my website embedded at http://mindprod.com/applet/currcon.jar shortly aftter
1 PM Eastern time, when the bank of Canada posts them. You are
free to download the latest versions every day and upload them to your website.
Alternatively, you can use your own source and add the massaged serialized data to the
jar yourself. I have written code to do this the Bank of Canada, the source I use on my
own website. I could write you an automated extractor for other sources. Most likely I
would charge
$50.00 USD
, but it depends on the complexity. In any case,
I give you a fixed price ahead of time. It is not hard to do yourself using the two
sample extractors I have written as models.

Official Government source, comes out 1 PM EST (Eastern Standard Time)
each day. Has
last 7 days of rates. This is the source I use at
mindprod.com. Free. You can also pick them up indirectly already massaged into a
jar file from the http://mindprod.com/applet/currcon.jar
website each day.

Makers of the FxCommerce product that competes with CurrCon. It is illegal to use this site to feed data into CurrCon
by screenscaping or copying from the screen. Their lawyer explained this in
series of emails. Apparently, it would be legal if either you or I signed a
licence agreement with them and paid a fee to use a special feed they have.

Oddly they even carry obsolete currencies, e.g. that of countries that have
converted to the Euro.

You manually select which currencies you want, then it sends you a list of the
exchange rates in HTML or CSV
embedded
in an HTML page. It is free to use, so long as you
don’t actually make practical use of the information, so you can experiment
with it for free.

If you curious about the history of how the US dollar (code USD) has been
doing relative to the Canadian dollar (code USD), the Euro (code EUR) even the
Iraqi Dinar (code IQD) see Oanda’s fxhistory. The US
dollar is in deep trouble, but most Americans are unaware of what is happening.
Money is fleeing America causing the value of the dollar to drop relative to
other countries. The net effect is America has to pay more for imported goods
which puts her still deeper in debt in a vicious spiral of debt.

This is a lot of work. It is error prone. The main advantage is no issue of
paying royalties.

Comparison of CurrCon with Oanda
FxCommerce

Oanda made a similar
product to CurrCon called FXCommerce, but I cannot find any mention of it any longer on
their website. They seem to not only have discontinued it, but disavow it ever existing.

comparison of CurrCon and Oanda

Feature

CurrCon

FxCommerce

Requires special Code on the server?

Automatically selects user’s currency

Requires user to have JavaScript enabled

Requires user to have Java enabled

Requires user to reload page to see prices?

Lets you control font, color etc. of prices with style
sheets?

Includes daily feed of exchange rate changes?

Cost

free

$30.00 USD
per month.

exists and open source so it cannot ever be taken away from you.

Defunct

Configuring

You will likely need my help getting started. I am
opening to creating custom versions of the program.

CurrCon itself free but if you need help installing or configuring CurrCon, I am available on a consulting basis for a fee. I will help you
configure CurrCon for your needs. I need to know which
technique you will use to generate the Applet tags and what
source you plan to use for the exchange rates. I need to know what program you use to
upload to your website.

To help you get started quickly, I need to know which currency choices you want to
offer.

You can configure the files to restrict the currency choices and control the
default currency for each country.

The list of choices is limited by both what your exchange rate source offers and by
the list of currency descriptions. To deliberately leave out a country, remove its line
from countrytocur.csv. To deliberately leave out a currency,
remove its line from currencydetails.csv.

Country code to Currency code conversion lookup table. In other words, which
currency do people use in each country?

com\mindprod\currcon\CurrCon.java

CurrCon Java Applet source. Uses the exchs.ser file prepared each day to display prices as an Applet
embedded in HTML.

com\mindprod\currcon\currcon.jar

The jar containing the CurrCon java Applet and the
exchs.ser digested daily exchange rates. It is a compact
13K for fast loading. It is freshly prepared each day
with the new exchange rates and uploaded to the website. Alternatively, you can
just borrow mine from my website if you have no customisation.

com\mindprod\currcon\CurrConAux.java

CurrConAux main Java program source. Prepares the exchs.ser digest of exchange rates each day from the bank of Canada
file.

com\mindprod\currcon\currencydetails.csv

Details about each currency, its name, how many decimal places you use to
display it, what symbol to use for the dollar sign if any.

com\mindprod\currcon\daily.bat

Run daily to prepare jar for uploading to the website.

com\mindprod\currcon\dailym.bat

Run daily to prepare jar for uploading to the website, if you handle your
exchange rates manually..

com\mindprod\currcon\seven_day_exchange_en.csv

File downloaded each day to the J:\com\mindprod\currcon\
directory from the bank of Canada website http://www.bankofcanada.ca/en/markets/csv/exchange_eng.csv
containing the daily exchange rates for various countries with the currencies
labelled using ISO (International Standards Organisation) 4217 codes.

com\mindprod\currcon\exchs.ser

The massaged and predigested exchange rates in a compact form ready for the
CurrCon Applet. It is included in the currcon.jar prepared each day and uploaded to the website.

com\mindprod\currcon\manual.csv

Only used if you want to manually control the exchange rates. A list of
currencies and their current exchange rates.

Daily Procedure

Once only, get a computer-savvy person (possibly me) to adjust the file
daily.bat for you to customise it for your computer.

Any time after 1 PM Eastern time, when the Bank of Canada posts the new exchange
rates, run daily.bat. It will download http://www.bankofcanada.ca/en/markets/csv/exchange_eng.csv
to the J:\com\mindprod\currcon directory. Then it will merge
the various data files and produce a new currcon.jar file.

Upload com\mindprod\currcon\currcon.jar to your
website.

If you see errors, most commonly it is the Bank of Canada changing, adding or
deleting country codes. I will usually notice the problem within 24 hours and post a new
version to handle the change. Sometimes it is a temporary problem, e.g. An exchange rate
was not available for the Myanmar Kyat today.

Manual Procedure

If you want complete control of the exchange rates
(perhaps to pad them with a fee, or to hold them more stable than they really are), you
can run CurrCon in manual mode.

Once only, get a computer-savvy person to adjust the file dailym.bat for you to customise it for your computer, e.g, to use your
favourite text editor.

Each day, or as often as you want to change the exchange rates, edit the file
com\mindprod\currcon\manual.csv. It is a
CSV file with one
line per currency (and two fields per line) that you want to support. It would look
something like this:

CAD,0.98473EUR,1.57104GBP,1.98306USD,1.0

Use the upper case three letter codes for the currencies you want to support from the
list in currencydetails.csv. The numeric value is the value
of one unit of the currency in US dollars. The GBP (Great Britain Pound) and Euro
will be greater than 1. The MXP Mexican peso will be less than 1. USD US dollars will
be exactly 1. You need lines for the currencies you want to support, including USD.
You can get the exchange rates from a newspaper or from one of the online sources.

Once only, prune out currencies you don’t want to support. There is no need
to prune currencies you don’t want to support from the other files such as
currencydetails.csv and countrytocurr.csv.

Run dailym.bat.

Upload com\mindprod\currcon\currcon.jar to your
website.

Costs

CurrCon is free. It comes with source and your right to modify
it and use it throughout your company. I will help you get it going, but if you require
modifications or extensive help, I will help you for a negotiated fee. Even someone with
the most basic knowledge of Java should have no problem getting CurrCon working or doing minor customisations, like reducing the set of
currencies supported. Since customising means running the Javac compiler and and ant
script it is likely beyond the reach of a someone without Java experience, unless they
use it unmodified.

$1989.00 US donated so far. If the CMP utilities solved your problem, please donate a buck or two,
or donate to one of the charities featured in the footer public service ads
throughout the website and get a tax receipt.
CurrCon Currency Converter is free. Full source included.
You may even include the source code, modified or unmodified
in free/commercial open source/proprietary programs that you write and distribute. Non-military use only.