TemplatedFormBuilder for Rails

This plugin provides a FormBuilder for Rails which allows you to specify the appearance of form helpers through partials. Also, it creates instant label tags just for you!

Installation

At the moment, the TemplatedFormBuilder plugin can only be obtained from SVN. From your application root:

`Rails Edge`:	script/plugin install svn://rubyforge.org/var/svn/tpl-formbuilder/trunk
`Rails 1.2`:	script/plugin install svn://rubyforge.org/var/svn/tpl-formbuilder/tags/rails-1.2

However, you might consider using Piston to manage your plugins:

  piston import svn://rubyforge.org/var/svn/tpl-formbuilder/trunk vendor/plugins/templated_form_builder

Usage

Getting Started

Some Rails form helpers (those yielding a block, e.g. form_for) accept a :builder option to supply a custom FormBuilder which is used to render the form elements. For a basic example of how this works, read the documentation on form_for: api.rubyonrails.org/classes/ActionView/Helpers/FormHelper.html#M000494

TemplatedFormBuilder renders form elements based on regular partial templates residing in app/views/forms. To install some sane defaults, you may want to execute:

  rake tfb:install

In order to use TemplatedFormBuilder in your views, you‘d do this:

  form_for :post, :builder => TemplatedFormBuilder do |form|

This plugin, however, comes with a handy shortcut (which will eventually be refactored into a separate plugin so you can define your own), allowing you to use:

  <% tpl_form_for :post do |form| %>

Within the block, you can go ahead and throw together your form as usual:

  <%= form.text_field :title %>

TemplatedFormBuilder will now look for views/forms/_text_field.rhtml (or whatever other template handlers you happen to have registered) and fall back to views/forms/_element.rhtml if it couldn‘t be found. This simple mechanism allows you to create specialized templates for the different form elements based on their types.

As a bonus, form element helpers accept an additional :label option. TemplatedFormBuilder wraps this into a ready to use label element. With the default templates shipping with the plugin, calling this:

  <%= form.text_field :title, :label => 'Title' %>

Would output:

  <label for="post_title"><br />
  <input type="text" name="post[title]" id="post_title" />

Additionally you can wrap any form elements with the section method. TemplatedFormBuilder would defer the render of the section to the template you declare via :partial option, fallbacking to views/forms/_section.rhtml.

  <% form.section do %>
     <%= form.text_field :title %>
     <%= form.text_field :address %>
     <%= form.text_field :phone %>
     ...
  <% end %>

or…

  <% form.section "Contact Info" do %>

or even …

  <% form.section "Contact Info", :partial => "contact" do %>

Customizing Your Form Templates

As mentioned above, form templates reside in app/views/forms. TemplatedFormBuilder passes three local variables to the element templates:

`element`:	the form element in question as it is rendered by Rails’ default form helpers
`label`:	a ready to use label element (i.e. the `for` attribute is correctly set)
`errors`:	validation errors for this element, if any (note: This local will be always an Array, even if there is only one error or no error at all.)

In the case of section templates you‘ll gain access to two locals:

`section_label`:	the string you used to name the section (defaults to "Section").
`section_contents`:	the rendered elements inside the section.

To Do

incorporate more form helpers
write tests

Bugs

If you find any bugs, please report them on RubyForge: rubyforge.org/tracker/?group_id=2889

README