Skip to content

Latest commit

 

History

History
88 lines (70 loc) · 5.37 KB

README.md

File metadata and controls

88 lines (70 loc) · 5.37 KB
Raw

Build Status Code Climate Test Coverage

FoundationFormBuilder

What is this gem for?

Foundation is an excellent CSS framework, and provides some lovely components for working with forms. Unfortunately, using them with Rails can be a bit of a hassle, as Foundation wants each form input to be wrapped in a <div>, with another <div> for errors.

In addition, I wanted to use something like Formtastic to DRY up my form field markup, but writing new renderers for Formtastic is non-trivial, and I wanted something a bit simpler anyway, so I rolled my own. If you want to build pretty forms with a simple FormBuilder interface and all the Foundation goodness, this gem is for you!

FoundationFormBuilder is a work in progress. I welcome bug reports and pull requests! It's only tested on Rails 4.2 and Ruby 2.2 so far, but I'd love to support older versions of both Rails and Ruby if it's not too difficult to do so.

Sounds great! How do I use it?

Install the gem in the usual way:

gem 'foundation_form_builder'

Then put the following in your application.rb file:

config.action_view.default_form_builder = FoundationFormBuilder::Rails

This tells Rails to use FoundationFormBuilder::Rails for all forms. If you don't want to do that, then specify it for the particular form you'd like to use it on.

Simple usage

form_for @user do |f|
  f.input_div :email
end

will create something like

<form action='users/1' and='all the other standard Rails attributes :)'>
  <div class='email'> <!-- adds class 'error' too if there are validation errors -->
    <label for='user_email'>Email</label>
    <input type='email' id='user_email' name='user[email]' />
    <!-- if there are validation errors, also the following: -->
    <span class='error'>can't be blank</div>
  </div>
</form>

Note that FoundationFormBuilder::Rails uses the Rails form helper functions to render the fields, and that it tries to infer the most appropriate form helper type, as follows.

Condition Default form helper
Field name is email email_field
Field name is time_zone time_zone_select
Field name contains the word password password_field
Field maps to numeric column in DB number_field
Field maps to date column in DB date_field
Field maps to text column in DB text_area
Otherwise text_field

Since FoundationFormBuilder::Rails is a subclass of the standard Rails ActionView::Helpers::FormBuilder, all the usual Rails FormBuilder helpers are also available. You'll probably need to use f.submit at least; we're not doing anything special with submit buttons at the moment.

Advanced usage

input_div takes several options if you want to override its defaults.

Option Value
:field Hash of options to pass through to the underlying Rails form helper
:label Text for label
:type Explicit form helper type; overrides inferred types (see above). Significant values are :date, :email, :numeric, :password, :select, :textarea, and :time_zone; :text or anything else will generate a text field.
:values Values for <option> elements; only meaningful with type: :select.

The following example shows all of these options in use.

f.input_div :size, label: 'My size is:', type: :select, values: [['Small', 1], ['Large', 2]], field: {prompt: 'Choose a size'}

It renders as:

<div class='size'> <!-- and class 'error' if necessary -->
  <label for='product_size'>My size is:</label>
  <select name='product[size]' id='product_size'>
    <option>Choose a size</option>
    <option value='1'>Small</option>
    <option value='2'>Large</option>
  </select>
  <!-- error span if necessary, as above -->
</div>