Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 360 lines (254 sloc) 10.078 kb
fe6ae00 Andreas Loupasakis Add coderwall endorse button
alup authored
1 # RubyMoney - Money-Rails [![endorse](http://api.coderwall.com/alup/endorsecount.png)](http://coderwall.com/alup)
cac643a Andreas Loupasakis First commit
alup authored
2
32c1305 Andreas Loupasakis Update README with travis build status image
alup authored
3 [![Build Status](https://secure.travis-ci.org/RubyMoney/money-rails.png?branch=master)](http://travis-ci.org/RubyMoney/money-rails)
29f1607 Andreas Loupasakis Add dependency status image
alup authored
4 [![Dependency Status](https://gemnasium.com/RubyMoney/money-rails.png)](https://gemnasium.com/RubyMoney/money-rails)
90ef789 Andreas Loupasakis Stupid typo for codeclimate URL
alup authored
5 [![Code Climate](https://codeclimate.com/badge.png)](https://codeclimate.com/github/RubyMoney/money-rails)
cac643a Andreas Loupasakis First commit
alup authored
6
7 ## Introduction
8
9 This library provides integration of [money](http://github.com/Rubymoney/money) gem with Rails.
4060df8 Andreas Loupasakis First iteration - Bootstrapping
alup authored
10
2f37711 Andreas Loupasakis Update README
alup authored
11 Use 'monetize' to specify which fields you want to be backed by
12 Money objects and helpers provided by the [money](http://github.com/Rubymoney/money)
13 gem.
4060df8 Andreas Loupasakis First iteration - Bootstrapping
alup authored
14
e4c631d Andreas Loupasakis Update README
alup authored
15 Currently, this library is in active development mode, so if you would
16 like to have a new feature feel free to open a new issue
17 [here](https://github.com/RubyMoney/money-rails/issues). You are also
18 welcome to contribute to the project.
19
4060df8 Andreas Loupasakis First iteration - Bootstrapping
alup authored
20 ## Installation
21
22 Add this line to your application's Gemfile:
23
24 gem 'money-rails'
25
26 And then execute:
27
28 $ bundle
29
30 Or install it yourself as:
31
32 $ gem install money-rails
2f37711 Andreas Loupasakis Update README
alup authored
33
b0e6eb7 Andreas Loupasakis Update README
alup authored
34 You may also install money configuration initializer:
35
36 ```
37 $ rails g money_rails:initializer
38 ```
39
a863b18 Andreas Loupasakis Update README
alup authored
40 There, you can define the default currency value and set other
41 configuration parameters for the rails app.
2f37711 Andreas Loupasakis Update README
alup authored
42
43 ## Usage
44
f519832 Kevin Sołtysiak Updated README regarding mongoid 2.X support
ksol authored
45 ### ActiveRecord
46
2f37711 Andreas Loupasakis Update README
alup authored
47 For example, we create a Product model which has an integer price_cents column
48 and we want to handle it by using a Money object instead:
49
50 ```ruby
51 class Product < ActiveRecord::Base
f519832 Kevin Sołtysiak Updated README regarding mongoid 2.X support
ksol authored
52
2f37711 Andreas Loupasakis Update README
alup authored
53 monetize :price_cents
f519832 Kevin Sołtysiak Updated README regarding mongoid 2.X support
ksol authored
54
2f37711 Andreas Loupasakis Update README
alup authored
55 end
56 ```
57
58 Now each Product object will also have an attribute called ```price``` which
59 is a Money object and can be used for money comparisons, conversions etc.
60
61 In this case the name of the money attribute is created automagically by removing the
f519832 Kevin Sołtysiak Updated README regarding mongoid 2.X support
ksol authored
62 ```_cents``` suffix of the column name.
ff38332 Andreas Loupasakis Update README
alup authored
63
64 If you are using another db column name or you prefer another name for the
65 money attribute, then you can provide ```as``` argument with a string
2f37711 Andreas Loupasakis Update README
alup authored
66 value to the ```monetize``` macro:
67
68 ```ruby
a863b18 Andreas Loupasakis Update README
alup authored
69 monetize :discount_subunit, :as => "discount"
2f37711 Andreas Loupasakis Update README
alup authored
70 ```
71
a863b18 Andreas Loupasakis Update README
alup authored
72 Now the model objects will have a ```discount``` attribute which
73 is a Money object, wrapping the value of ```discount_subunit``` column to a
2f37711 Andreas Loupasakis Update README
alup authored
74 Money instance.
75
f519832 Kevin Sołtysiak Updated README regarding mongoid 2.X support
ksol authored
76 #### Allow nil values
18bdd59 Andreas Loupasakis Update documentation for 0.4.0 version
alup authored
77
78 If you want to allow the assignment of nil and/or blank values to a specific
79 monetized field, you can use the `:allow_nil` parameter like this:
80
81 ```
82 # in Product model
83 monetize :optional_price_cents, :allow_nil => true
84
85 # then blank assignments are permitted
86 product.optional_price = nil
87 product.save # returns without errors
88 product.optional_price # => nil
89 product.optional_price_cents # => nil
90 ```
91
dd734a9 Andreas Loupasakis Update README
alup authored
92 ### Mongoid 2.x and 3.x
f519832 Kevin Sołtysiak Updated README regarding mongoid 2.X support
ksol authored
93
94 `Money` is available as a field type to supply during a field definition:
95
96 ```ruby
97 class Product
98 include Mongoid::Document
99
100 field :price, type: Money
101 end
102
103 obj = Product.new
104 # => #<Product _id: 4fe865699671383656000001, _type: nil, price: nil>
105
106 obj.price
107 # => nil
108
109 obj.price = Money.new(100, 'EUR')
110 # => #<Money cents:100 currency:EUR>
111
112 obj.price
113 #=> #<Money cents:100 currency:EUR>
114
115 obj.save
116 # => true
117
118 obj
119 # => #<Product _id: 4fe865699671383656000001, _type: nil, price: {:cents=>100, :currency_iso=>"EUR"}>
120
121 obj.price
122 #=> #<Money cents:100 currency:EUR>
123
124 ## You can access the money hash too :
125 obj[:price]
126 # => {:cents=>100, :currency_iso=>"EUR"}
127 ```
128
129 The usual options on `field` as `index`, `default`, ..., are available.
130
80b4570 Joe Frambach docs and tests for method monetization
joeframbach authored
131 ### Method conversion
132
133 Method return values can be converted in the same way attributes are converted. For example:
134
135 ```ruby
136 class Transaction < ActiveRecord::Base
137
494e7cd Joe Frambach fixed readme for method conversion
joeframbach authored
138 monetize :price_cents
139 monetize :tax_cents
140 monetize :total_cents
80b4570 Joe Frambach docs and tests for method monetization
joeframbach authored
141 def total_cents
142 return price_cents + tax_cents
143 end
144
145 end
146 ```
147
148 Now each Transaction object has a method called `total` which returns a Money object.
149
a0f81ba Andreas Loupasakis Add documentation for currencies in README
alup authored
150 ### Currencies
ff38332 Andreas Loupasakis Update README
alup authored
151
a0f81ba Andreas Loupasakis Add documentation for currencies in README
alup authored
152 Money-rails supports a set of options to handle currencies for your
153 monetized fields. The default option for every conversion is to use
154 the global default currency of Money library, as given in the configuration
155 initializer of money-rails:
ff38332 Andreas Loupasakis Update README
alup authored
156
157 ```ruby
a0f81ba Andreas Loupasakis Add documentation for currencies in README
alup authored
158 # config/initializers/money.rb
159 MoneyRails.configure do |config|
160
161 # set the default currency
162 config.default_currency = :usd
163
164 end
165 ```
166
167 In many cases this is not enough, so there are some other options to
168 satisfy your needs.
169
170 #### Model Currency
171
f519832 Kevin Sołtysiak Updated README regarding mongoid 2.X support
ksol authored
172 You can define a specific currency for an activerecord model (not for mongoid).
173 This currency is used for the creation and conversions of the Money objects
174 referring to every monetized attributes of the specific model.
175 This means it overrides the global default currency of Money library.
176 To attach a currency to a model use the ```register_currency``` macro:
a0f81ba Andreas Loupasakis Add documentation for currencies in README
alup authored
177
178 ```ruby
179 # app/models/product.rb
180 class Product < ActiveRecord::Base
181
182 # Use EUR as model level currency
183 register_currency :eur
184
185 monetize :discount_subunit, :as => "discount"
186 monetize :bonus_cents
187
188 end
189 ```
190
191 Now ```product.discount``` and ```product.bonus``` will return a Money
192 object using EUR as currency, instead of the default USD.
193
194 #### Attribute Currency (:with_currency)
195
196 By using the key ```:with_currency``` with a currency symbol value in
197 the ```monetize``` macro call, you can define a currency in a more
198 granular way. This way you attach a currency only to the specific monetized
199 model attribute. It also allows to override both the model level
200 and the global default currency:
201
202 ```ruby
203 # app/models/product.rb
204 class Product < ActiveRecord::Base
205
206 # Use EUR as model level currency
207 register_currency :eur
208
209 monetize :discount_subunit, :as => "discount"
210 monetize :bonus_cents, :with_currency => :gbp
211
212 end
213 ```
214
215 In this case the ```product.bonus``` will return a Money object of GBP
216 currency, whereas ```product.discount.currency_as_string # => EUR ```
217
218 #### Instance Currencies
219
220 All the previous options do not require any extra model field to hold
221 currency values. If you need to provide differrent currency per model
222 instance, then you need to add a column with the name ```currency```
223 in your db table. Money-rails will discover this automatically,
224 and will use this knowledge to override the model level and global
ece582b Andreas Loupasakis Update README
alup authored
225 default values. Non-nil instance currency values also override attribute
226 currency values, so they have the highest precedence.
a0f81ba Andreas Loupasakis Add documentation for currencies in README
alup authored
227
228 ```ruby
229 class Transaction < ActiveRecord::Base
230
231 # This model has a separate currency column
232 attr_accessible :amount_cents, :currency, :tax_cents
233
234 # Use model level currency
235 register_currency :gbp
236
237 monetize :amount_cents
238 monetize :tax_cents
239
240 end
241
ece582b Andreas Loupasakis Update README
alup authored
242 # Now instantiating with a specific currency overrides
a0f81ba Andreas Loupasakis Add documentation for currencies in README
alup authored
243 # the model and global currencies
244 t = Transaction.new(:amount_cents => 2500, :currency => "CAD")
245 t.amount == Money.new(2500, "CAD") # true
ff38332 Andreas Loupasakis Update README
alup authored
246 ```
247
a863b18 Andreas Loupasakis Update README
alup authored
248 ### Configuration parameters
249
250 You can handle a bunch of configuration params through ```money.rb``` initializer:
251
252 ```
253 MoneyRails.configure do |config|
254
255 # To set the default currency
256 #
257 config.default_currency = :usd
258
560cfbd Andreas Loupasakis Add notes about exchange rates configuration params
alup authored
259 # Add custom exchange rates
260 config.add_rate "USD", "CAD", 1.24515
261 config.add_rate "CAD", "USD", 0.803115
262
a863b18 Andreas Loupasakis Update README
alup authored
263 # To handle the inclusion of validations for monetized fields
264 # The default value is true
265 #
266 config.include_validations = true
267
268 # Register a custom currency
269 #
270 # config.register_currency = {
271 # :priority => 1,
272 # :iso_code => "EU4",
273 # :name => "Euro with subunit of 4 digits",
274 # :symbol => "€",
275 # :symbol_first => true,
276 # :subunit => "Subcent",
277 # :subunit_to_unit => 10000,
278 # :thousands_separator => ".",
279 # :decimal_mark => ","
280 # }
281 end
282 ```
283
6601607 Andreas Loupasakis Minor update on README
alup authored
284 * ```default_currecy```: Set the default (application wide) currency (USD is the default)
285 * ```include_validations```: Permit the inclusion of a ```validates_numericality_of```
a863b18 Andreas Loupasakis Update README
alup authored
286 validation for each monetized field (the default is true)
6601607 Andreas Loupasakis Minor update on README
alup authored
287 * ```register_currency```: Register one custom currency. This option can be
a863b18 Andreas Loupasakis Update README
alup authored
288 used more than once to set more custom currencies. The value should be
6601607 Andreas Loupasakis Minor update on README
alup authored
289 a hash of all the necessary key/value pairs (important keys: ```:priority```, ```:iso_code```,
290 ```:name```, ```:symbol```, ```:symbol_first```, ```:subunit```, ```:subunit_to_unit```,
291 ```:thousands_separator```, ```:decimal_mark```).
292 * ```add_rate```: Provide custom exchange rate for currencies in one direction
560cfbd Andreas Loupasakis Add notes about exchange rates configuration params
alup authored
293 only! This rate is added to the attached bank object.
6601607 Andreas Loupasakis Minor update on README
alup authored
294 * ```default_bank```: The default bank object holding exchange rates etc.
560cfbd Andreas Loupasakis Add notes about exchange rates configuration params
alup authored
295 (https://github.com/RubyMoney/money#currency-exchange)
a863b18 Andreas Loupasakis Update README
alup authored
296
18bdd59 Andreas Loupasakis Update documentation for 0.4.0 version
alup authored
297 ### Helpers
298
299 * the `currency_symbol` helper method
300
301 ```
302 <%= currency_symbol %>
303 ```
304 This will render a `span` dom element with the default currency symbol.
305
306 * the `humanized_money` helper method
307
308 ```
309 <%= humanized_money @money_object %>
310 ```
311 This will render a formatted money value without the currency symbol and
312 without the cents part if it contains only zeros (uses
313 `:no_cents_fi_whole flag`).
314
315 * humanize with symbol helper
316
317 ```
318 <%= humanized_money_with_symbol @money_object %>
319 ```
320 This will render a formatted money value including the currency symbol and
321 without the cents part if it contains only zeros.
322
323 * get the money value without the cents part
324
325 ```
326 <%= money_without_cents @money_object %>
327 ```
328 This will render a formatted money value without the currency symbol and
329 without the cents part.
330
331 * get the money value without the cents part and including the currency
332 symbol
333
334 ```
335 <%= money_without_cents_and_with_symbol @money_object %>
336 ```
337 This will render a formatted money value including the currency symbol and
338 without the cents part.
339
dd734a9 Andreas Loupasakis Update README
alup authored
340 ## Supported ORMs/ODMs
341
342 * ActiveRecord (>= 3.x)
343 * Mongoid (2.x, 3.x)
344
60207aa Andreas Loupasakis Update readme file
alup authored
345 ## Supported Ruby interpreters
346
347 * MRI Ruby >= 1.8.7
348
349 You can see a full list of the currently supported interpreters in [travis.yml](http://github.com/RubyMoney/money-rails/blob/master/.travis.yml)
350
a863b18 Andreas Loupasakis Update README
alup authored
351 ## Maintainers
352
353 * Andreas Loupasakis (https://github.com/alup)
354 * Shane Emmons (https://github.com/semmons99)
355 * Simone Carletti (https://github.com/weppos)
356
2f37711 Andreas Loupasakis Update README
alup authored
357 ## License
358
359 MIT License. Copyright 2012 RubyMoney.
Something went wrong with that request. Please try again.