Skip to content
Pull request Compare This branch is 116 commits behind wycats:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
..
Failed to load latest commit information.
lib
spec
LICENSE
README
Rakefile
TODO

README

merb_helpers
=================

A plugin for the Merb Web framework that provides different view helpers.

To use this plugin in merb in your app

config/dependencies.rb

#...

dependency "merb_helpers"

#...

# TODO: describe date_time_helpers, form_helpers, tag_helpers

numeric helpers
---------------

Numeric helpers extend numeric instances, in lay terms: numbers.

* +with_delimiter+, this method formats a number with grouped thousands 

    12345678.with_delimiter # => "12,345,678"
  

* +with_precison+, this method formats a number with a level of precision

    111.2345.with_precision # => "111.235"
    
* +to_currency, this method formats a number into a currency value using a delimited and a set precision

    1234567890.506.to_currency # => "$1,234,567,890.51"
    
(For usage example look at spec/numeric_exlib.rb)


Overwriting the default formating options:

One can overwrite the default settings by passing the name or of the format used and a hash representing the settings to overwrite.

Each method mentioned above has some format settings you can overwrite:

* +with_delimiter+ 
  * :delimiter - Overwrites the thousands delimiter.
  * :separator - Overwrites the separator between the units.
  
* +with_precision+
  * :precision - Overwrites the level of precision
  * :separator - Overwrites the separator between the units
  * :delimiter - Overwrites the thousands delimiter
  
* +with_currency+
  * :precision - Sets the level of precision 
  * :unit - Sets the denomination of the currency 
  * :format - Sets the format of the output string (defaults to "%u%n"). The field types are: 
    * %u The currency unit
    * %n The number
    
Usage example:

    1234567890.506.to_currency(:default, :unit => '£') # => "£1,234,567,890.51"
    
merb_helpers comes with a very limited set of formats you can use, here is an example:

    1234567890.50.to_currency(:uk) # => "£1,234,567,890.50"
    
Formats are just a hash of settings used by the plugin, here is the default format:

    :us => {
      :number => {      
        :precision => 3, 
        :delimiter => ',', 
        :separator => '.'
      },
      :currency => { 
        :unit => '$',
        :format => '%u%n',
        :precision => 2 
      }
    }
    
If you wish to add a new format you can easily do that as follows:
    
    custom_format_to_add = {  :custom_name => {
                                :number => {      
                                  :precision => 3, 
                                  :delimiter => ',', 
                                  :separator => '.'
                                },
                                :currency => { 
                                  :unit => 'Merbollars',
                                  :format => '%n %u',
                                  :precision => 2 
                                }
                              }
                          }
    
    Numeric::Transformer.add_format(custom_format_to_add)
    
You can then call the format like that:

    1234567890.to_currency(:custom_name) # => "1,234,567,890.00 Merbollars"
    
After adding a custom format, you can set it as the default format:

    Numeric::Transformer.change_default_format(:custom_name)
    
You can set this things up in your before/after app load block in the config/init.rb file.


Formating a Date or Time instance
---------------

Usage examples: spec/merb_helpers_date_time_spec.rb

    Time.now.formatted(:db)   # => "2008-09-21 02:07:31"
    Time.now.formatted(:long) # => "September 21, 2008 02:08"
    
You can also add your own format:

    Date.add_format(:matt, "%H:%M:%S %Y-%m-%d")

And use is as a default format:

  Time.now.formatted(:matt)    # => "02:09:18 2008-09-21"



Representation of time difference
-------------------

Usage examples: spec/merb_helpers_date_time_spec.rb

* Relative time:

Let's imagine that we are the June 1st 2007 at 11am UTC


    relative_date(Time.now.utc)       # => "today"
    relative_date(1.day.ago.utc)      # => 'yesterday'
    relative_date(1.day.from_now.utc) # => 'tomorrow'
    relative_date(Time.utc(2005, 11, 15)) # => 'Nov 15th, 2005' (date with the year since it's not this year)
    relative_date(Time.utc(2007, 11, 15)) # => 'Nov 15th' (date without the year this the passed date is this year)
    
Something went wrong with that request. Please try again.