Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Rails plugin: a custom, template-based form builder that attempts to make your forms friendly (and maybe even fun!).
branch: master

This branch is 11 commits behind rpheath:master

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
forms
lib
tasks
test
.gitignore
MIT-LICENSE
README.textile
Rakefile
init.rb
install.rb
uninstall.rb

README.textile

FormAssistant

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

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

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’.

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 %>

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’).

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.

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.

Custom Helpers

The form assistant 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', :path => 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' } %>

There’s also a #partial() helper:

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

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

Bonus Features

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.

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).

Licensing

© 2008 Ryan Heath, released under the MIT license

Something went wrong with that request. Please try again.