Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

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 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.