This plugin is supposed to make handling of multiple currencies in a Rails application as easy as possible.
Switch branches/tags
Nothing to show
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.



This plugin allows easy conversion between currencies.

Automatic output conversion of currencies

The ConvertibleCurrency#to_s method when called without parameters, checks the class attribute
output_currency for the currency to use. If the output_currency should not match it's own, it will
convert it before returning the string.

This can be exceptionally useful when used in an around_filter of your application.
The following example allows you to simply add ?currency=EUR to your query parameters and have
all currencies on the page in EUR, no matter what their original currency was:

def output_currency
	MultiCurrency.output_currency = params[:currency]
	MultiCurrency.output_currency = nil


## Currency fields that come back from the database
# In most models you will find an expression like this:
currency_columns :payments_q1, :payments_q2, :payments_q3, :payments_q4,
    :payments_forecast, :commitments, :commitments_forecast, 
    :payments_up_to_end_of, :commitments_up_to_end_of,
	:year => lambda { |m| m.year }, :currency => lambda { |m| m.donor.currency }

# That line makes all listed columns of the model automatically return objects of the class ConvertibleCurrency, 
# so that you don't have to worry about about conversions later.
# The attributes +year+ and +currency+ take Proc objects that are used to determine the base year and 
# currency that is used in e.g. conversions.

## Converting other objects to currencies
# You can easily convert strings and numbers to currencies by using the .to_currency method.
# to_currency takes two arguments, the first is the actual currency second is the year which 
# defaults to the current year and on whose exchange rates further conversions will be based.

# Examples:
>> 1000.to_currency
=> #<Currency:0x112a8a8 @year=2008, @currency=nil, @base_value=1000.0>

>> "100,323,21".to_currency("EUR", 2007)
=> #<Currency:0x1129278 @year=2007, @currency="EUR", @base_value=100323.21>

## Working with currencies
# The ConvertibleCurrency class supports many powerful methods which are best explained by examples:

# The in method allows you to convert an object from one currency to another, based on the exchange rates
# from our database. Please note that you can't use it on "anonymous currencies" with no unit given, 
# as demonstrated below:

# Examples:
>> 1000.to_currency("EUR").in("GBP")
=> #<MultiCurrency::ConvertibleCurrency:0x297fd68 @year=2008, @currency="GBP", @base_value=670.0>

=> #MultiCurrency::ConversionOfAnonymousCurrency: Can't convert anonymous currency to GBP

# The most powerful method of the Currency class is definitely to_s which is called by Rails automatically whenever you
# try to output a Currency object in a template file. It will automatically add separators and a unit indicator to
# the amount.

# Examples:
>> 100.to_currency("SEK").to_s
=> "100 SEK"
>> 100000000.to_currency("SEK").in("EUR").to_s
=> "10,845,987 EUR"

# Usually .to_s will output the amount in the currency specified before.
# However, you can set MultiCurrency.output_currency to make it always return a certain currency, regardless of the 
# object's actual unit.
# This method is used in the output filter that allows you to add ?currency= to the URL
>> MultiCurrency.output_currency = "SEK"
=> "SEK"

>> 100.to_currency("GBP").to_s
=> "1,376 SEK"

>> 1000.to_currency("EUR").to_s
=> "9,220 SEK"

## Performing calculations on currencies
# The most important thing of course is to use currencies for calculations.
# The Currency class is smart enough to convert its objects to a common currency before it adds or subtracts them.
# It will always convert them to the currency of the element on the left side of the operator (e.g. + or -)

# Examples:
>> f = 1000.to_currency("EUR") + 200.to_currency("SEK")
=> #<Currency:0x295c264 @year=2008, @currency="EUR", @base_value=1021.69197396963>
>> f.to_s
=> "1,022 EUR"

>> f = 1000.to_currency("GBP") + 2000.to_currency("SEK")
=> #<Currency:0x2950720 @year=2008, @currency="GBP", @base_value=1145.33622559653>
>> f.to_s
=> "1,145 GBP"

## Don't try to add currency objects to ordinary numbers!
# The above examples make clear how calculations are handled internally.
# That's also the reason why you experienced errors like "Currency can't be coerced into Fixnum".
# If you would do e.g. 

>> 10 + 20.to_currency("EUR")

# Ruby can't be sure about the currency of the object on the left side, so that a calculation doesn't make sense.
# This can be circumvented in two ways. Either you convert the left side argument to a Currency object first,
# (e.g. 10.to_currency("EUR")) or you just exchange the operands to that the above examples becomes:

>> 20.to_currency("EUR") + 10

# In that case Ruby assumes that the currency of the right side operand equals the left side operand's unit and automatically
# converts it for you:
>> f = 20.to_currency("EUR") + 10
=> #<Currency:0x294d188 @year=2008, @currency="EUR", @base_value=30.0>
>> f.to_s
=> "30 EUR"

Copyright (c) 2008 Pascal Ehlert, ODAdata, released under the MIT license