FormAssistant

This is a Rails plugin that essentially provides two form builder’s:

1. RPH::FormAssistant::FormBuilder
   • Provides a method_missing hook that allows content to be wrapped in HTML elements “on the fly”, in addition to some helpful things like automatic “cancel” links and so on. Also, all of the traditional form helpers have labels attached to them automatically.
2. RPH::FormAssistant::InlineErrorFormBuilder
   • Extends RPH::FormAssistant::FormBuilder to attach field errors to the field itself, avoiding the need for error_messages_for.

Once installed, it’s easy to use either form builder via the following methods:

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

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

That’s all you have to do. If you don’t think you’ll be using the regular form assistant on one form, and the inline error form assistant on another, you can set which default builder to use across your entire application like so:

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

Then all of your form_for calls will automatically use the specified builder.

The InlineErrorFormBuilder uses partials to style the fields with and without errors, which is an extremely flexible way to keep your forms DRY. The form partials are kept in app/views/forms. To get started, run the following rake task from your project root:

$> rake form_assistant:install

That will put some example form partials in app/views/forms/*.

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:

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

Now, the examples:

# doing this
<%= form.text_field :title %>

# would render
<label for="project_title">Title</label>
<input type="text" id="project_title" name="project[title]" />

# other options:
<%= form.text_field :title, :label_text => 'Project Title' %>
<%= form.text_field :title, :label_class => 'required' %>
<%= form.text_field :title, :label => { :text => 'Project Title', :class => 'required' } %>

That works for all form helpers (text_area, checkbox, etc).

# a field that happens to have an error
<%= form.text_field :title, :label => { :text => 'Name', :class => 'required' } %>

# would render
<label class="required" for="project_title">Name</label>
<input type="text" id="project_title" name="project[title]" value="" />
<span class="errors">cannot be blank</span>

The form assistant also provides a cancel() helper that will allow the user to go back to the previous screen, automatically.

<%= form.cancel %>

<span class="cancel">
  <a href="/wherever/the/user/came/from">Cancel</a>
</span>

# other options:
<%= form.cancel 'Go Back' %>
<%= form.cancel 'Nevermind', :url => some_path %>
<%= form.cancel 'Go Back', :attrs => { :class => 'go-back' } %>

I usually like to give my submit buttons special attention, and so does form assistant:

<%= form.submission %>

<p class="submission">
  <input type="submit" value="Save Changes" ... />
</p>

# other options:
<%= form.submission 'Save Project' %>
<%= form.submission 'Save', :class => 'button' %>
<%= form.submission 'Save', :attrs => { :class => 'submit-wrapper' } %>

Here are a few bonus features:

<% form.div :class => 'admin' do %>
  // admin fields
<% end %>

<div class="admin">
  // admin fields
</div>

# other options:
<% form.p :id => 'notice' do %>
<% form.span :class => 'highlight' do %>

Now, an easier way to wrap a div around content:

<% form.admin_operations do %>
  // admin-operations
<% end %>

<div class="admin-operations">
  // admin-operations
</div>

<% form.admin_operations :glue => ' ' do %>
  // admin operations
<% end %>

<div class="admin operations">
  // admin operations
</div>

These helpers can be found in lib/form_assistant/helpers.rb. It was designed for extensibility, so please go crazy adding your own helpers! (see how easy it is by the existing implementations)

Enjoy keeping your forms DRY.

Licensing

© 2008 Ryan Heath, released under the MIT license