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.