Easily create and style forms in Rails applications
Ruby
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
lib
test
.gitignore
README
Rakefile
init.rb

README

= Labelled Form

== Purpose

This plugin was designed to increase productivity and reduce repetition
when creating forms. It should also aid in creating forms that are easy
to style with CSS, without adding a lot of meaningless markup to your
views.

== Example

A typical Rails form might look like this:

  <% form_for :person, @person do |f| %>
    <h1>My Information</h1>
    <div class="section">
      <div class="section_info">
        <p>Please enter your personal details.</p>
      </div>
      <div class="section_body">
	    <div class="field"><label for="person_name">Name:</label>
        <%= f.text_field :name, :class => :text %></div>
      </div>
    </div>
    <div class="section">
      <div class="section_info">
        <p>Please describe your preferences.</p>
      </div>
      <div class="section_body">
        <div class="boolean_field"><%= f.check_box :is_subscribed %>
        <label for="person_is_subscribed">Subscribe to newsletter</label></div>
      </div>
    </div>
  <% end %>
  
...only longer. The same form using labelled_form would look like this:

  <% labelled_form_for :person, @person, :title => 'My Information' do |f| %>
    <% f.section |s| %>
      <% s.info do %>
        <p>Please enter your personal details.</p>
      <% end>
      <% s.body do %>
        <%= s.text_field :name %>
      <% end %>
    <% end %>
    <% f.section |s| %>
      <% s.info do %>
        <p>Please describe your preferences.</p>
      <% end %>
      <% s.body do %>
        <%= s.check_box :is_subscribed, :label => 'Subscribe to newsletter' %>
      <% end %>
    <% end %>
  <% end %>
  
Much cleaner.

== Usage

In order to turn an undecorated form built with the standard <tt>FormBuilder</tt>
into a form with labels and wrapped in div tags, all you need to do is
replace your call to <tt>form_for<tt> with a call to <tt>labelled_form_for</tt>.
The builder object passed to your block will wrap all the standard Rails
helper methods, adding a div tag and a label:

  <% labelled_form_for :recipe, @recipe do |f| %>
    <%= f.text_field :title %>
  <% end %>

Most methods also understand one extra option: <tt>:label</tt>, which sets the label for
that field:

  <%= f.text_field :address, :label => 'Mailing Address:' %>

However, labels can often be guessed by the field name, so specifying a
label may not be necessary.

labelled_form also helps you split your forms into sections:

  <% f.section do |s| %>
    <% s.info do %>
    	<p>General Information</p>
    <% end %>
    <% s.body do %>
    	<%= s.text_field :title %>
    	<%= s.text_area_field :ingredients %>
    <% end %>
  <% end %>
  
The object passed to a section's block is a <tt>FormBuilder</tt> object, so
you can use builder methods on it. In fact, if a particular section of your
form uses a different object, you can use <tt>section_for</tt>:

  <% f.section_for :permissions, @person.permissions do |s| %>
    <% s.info do %>
    	<p>Permissions</p>
    <% end %>
    <% s.body do %>
      <%= s.check_box :is_admin, :label => 'This user is an administrator %>
    <% end %>
  <% end %>

The builder passed to section_for uses the specified object as the target.

== Error handling

If a field has error messages, the "field_with_errors" CSS class is added to
the div tag for that field. Each field is checked for errors when using
LabelledFormBuilder#field.

== Required fields

If a model requires an attribute using validates_presence_of, a field that
edits that attribute will have the "required_field" CSS class on its div tag.