Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP

This branch is 1 commit behind merb:master

Fetching latest commit…

Cannot retrieve the latest commit at this time

..
Failed to load latest commit information.
docs
lib
spec
.gitignore
.rspec
LICENSE
README.mkd
Rakefile
TODO
merb-helpers.gemspec

README.mkd

merb-helpers

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

To use this plugin in merb in your app, add the gem merb-helpers to your application's Gemfile, and run gem bundle.

TODO: describe date_time_helpers, form_helpers, tag_helpers

Form helpers

delete_button

If you want to delete an object, you should call the delete method on the object's controller. You should not use a simple link to your action, instead you should make a DELETE request. To help you doing that, you can use the delete_button method as follows:

<%= delete_button(@comment) %>

The delete_button helper has many options, first thing, you can pass an object or an URL:

<%= delete_button(url(:comment, @comment)) %>

This helper creates a form with a submit button.

You can pass many arguments to the delete_button helper. The first thing you might want to do is to change the default button text:

<%= delete_button(@comment), "Remove this comment by #{@comment.author.name}" %>

You can also pass the usual helper params to specify a class to use for instance:

<%= delete_button(@comment, nil, :class => 'custom-class') %>

See usage in specs: spec/fixture/app/views/delete_button_specs

Numeric helpers

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

  • minutes_to_hours converts a numeric value representing minutes into a string representing an hour value:

    315.minutes_to_hours # => "05:15"

  • two_digits formats a number into a two digit string. Basically it prepends an integer to a 2 digits string:

    3.two_digits # => "03"

  • with_delimiter formats a number with grouped thousands:

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

  • with_precison formats a number with a level of precision:

    111.2345.with_precision # => "111.235"

  • to_currency 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) # => "&pound;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.