form_assistant

Rails plugin: a custom, template-based form builder.

Ruby

h1. FormAssistant

This is a Rails plugin that provides a custom form builder that attempts to make forms somewhat friendly.

h2. Usage

Once installed, use the form assistant just like #form_for():

<% form_assistant_for @project do |form| %>
  // typical form_for stuff
<% end %>

Or if you’d rather use #form_for() everywhere, you can set the form assistant’s builder to be your default across the entire application like so:

ActionView::Base.default_form_builder = RPH::FormAssistant::FormBuilder

h2. Defaults and Configuration

Things you can customize…

# config/initializers/form_assistant.rb
  
RPH::FormAssistant::FormBuilder.ignore_templates = true         # defaults to false
RPH::FormAssistant::FormBuilder.ignore_labels = true            # defaults to false
RPH::FormAssistant::FormBuilder.ignore_errors = true            # defaults to false
RPH::FormAssistant::FormBuilder.template_root = '...'           # defaults to app/views/forms

The only thing worth mentioning deals with ignoring templates. If you ignore the templates, you will still get access to all of the custom helpers and your form helpers (@text_field@, @text_area@, etc) will automatically have labels attached to them. The form assistant considers trailing labels, too, meaning if you have a @check_box@ the label will be after the check box instead of before it. It will also be given a CSS class of ‘inline’.

h2. Examples

Here are a few reasons why it’s worth using the form assistant.

I’m going to refer to a @form@ object in the examples. Assume this object is yielded back to the block of a form assistant call, like so:

<% form_assistant_for @project do |form| %>
  // the 'form' object would be used in here
<% end %>

And just to be clear, the regular @fields_for()@ doesn’t inherit the builder from the builder object, but as long as you’re using the form assistant, this problem has been taken care of automatically. Just call the @fields_for()@ helper on the builder object, like so:

<% form_assistant_for @project do |form| %>
  <% form.fields_for :tasks do |task_fields| %>
    <%= task_fields.text_field :name %>
  <% end %>
<% end %>

h3. Form Templates

The new and improved form assistant uses partials to format your fields, labels, errors (if any), and tips. To get started, run…

$> rake form_assistant:install

…from your project root. That will put some example form partials in app/views/forms/*.

By default, the form assistant will try to render a template based on the name of the helper. For instance, calling

<%= form.text_field :title %>

will look for a template called _text_field.html.erb located in app/views/forms. However, you can specify a different template easily:

<%= form.text_field :title, :template => 'custom_template' %>

If a specified template doesn’t exist, a fallback template will be used (called ‘_field.html.erb’).

There’s also a @#fieldset()@ helper available to you, although it doesn’t belong to the form object (it’s mixed into action view itself).

<% fieldset 'User Registration' do %>
  <%= form.text_field :name %>
  <%= form.text_field :username %>
  <%= form.text_field :password %>
<% end %>

The nice thing about that is it’s also controlled by a template (cleverly called ‘_fieldset.html.erb’).

h3. Required Fields

You can now pass a @:required@ flag to the field helpers, and it will be available within the templates.

<%= form.text_field :title, :required => true %>

Then you can check the ‘required’ local variable and handle it accordingly. Naturally, this defaults to false.

h3. Form Labels

Another convenient thing about the form assistant is the ability to control labels from their respective helper. For example…

<%= form.text_field :title, :label => 'Project Title' %>
<%= form.text_field :title, :label_text => 'Project Title' %>
<%= form.text_field :title, :label_class => 'required' %>
<%= form.text_field :title, :label_id => 'dom_id' %>
<%= form.text_field :title, :label => { :text => 'Project Title', :id => 'dom_id', :class => 'required' } %>
<%= form.text_field :title, :label => false %>

That works for all form helpers (text_area, check_box, etc). And by default, the label will be the humanized version of the field name, so that’s what you’ll get if you ignore the label options altogether.

h3. Form Widgets

Sometimes, a single form field isn’t enough. Form assistant provides a construct to help you
with this, called widget:

<% form.widget :expiration_date, :label => 'Card expiration date' do %>
  <%= form.select :expiration_month, (1..12) %>
  <%= form.select :expiration_month, (1..12) %>
<% end %>

There are a few things to note about this new feature:

error messages will come from the errors on the field name (‘expiration_date’ in the above example)
templates and labels are disabled for the duration of the block
the default template for widgets is the fallback template (=_field.html.erb= unless configured otherwise)

h3. Custom Helpers

@#partial()@ helper:

<%= form.partial 'shared/new', :locals => { ... } %>

The builder variable will be automatically passed as a local called ‘form’.

h2. Requirements

The form assistant requires at least Rails version 2.1.0. This is mainly due to the usage of the convenience methods now included in the Rails module (for things like @Rails.version@ and @Rails.root@).

h2. Licensing