ConvertibleCurrencies ===================== 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] yield MultiCurrency.output_currency = nil end Usage ===== ## 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> >> 1000.to_currency.in("GBP") => #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
pehlert/multi_currency
This plugin is supposed to make handling of multiple currencies in a Rails application as easy as possible.
RubyMIT