ruby script/plugin install svn://rubyforge.org/var/svn/tpl-formbuilder

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" />

Customizing Your Form Templates
==============================

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

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: If only one error occured, this will be a string, otherwise an array of strings)

There is currently no advanced documentation for this plugin.