A Rails plugin to improve forms. Includes a better FormBuilder and DRYness for form fields.
Switch branches/tags
Nothing to show
Pull request Compare This branch is 8 commits behind Shadowfiend:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


= Awesome Fields
Awesome fields is a plugin that adds an extension to the built-in Rails
FormBuilder in the form of a new method, <tt>FormBuilder#field</tt>. This method
magically determines what type of field to display for the corresponding method.
It also adds a new form builder, +LinedBuilder+, and related methods, such as
lined_form_for and lined_fields_for. Note that JS-related methods are not
provided, since generally speaking I don't think Rails's JS helpers should be
used (look into a library like LowPro instead).

== Overview of the +field+ method

So let's say you had a model MyModel with a migration that looked oddly like:
 create_table(:my_model) do |t|
   t.column 'magic', :string
   t.column 'number', :integer
   t.column 'hyperdate', :date
   t.column 'supertime', :time
   t.column 'incredidatetime', :datetime

Then let's say we did this bit of magic:
 <% form_for :model, @model, :action => 'superplace' do |f| %>
   <%= f.field :magic %>
   <%= f.field :number %>
   <%= f.field :hyperdate %>
   <%= f.field :supertime %>
   <%= f.field :incredidatetime %>
 <% end %>
In this situation, you would get two plain text boxes, one date selector, one
time selector, and one datetime selector.

What if the `magic' field was really long (i.e., we generated a column with type
:text instead of :string)? Then we'd probably prefer a textarea. In this
situation, we pass the <tt>:long</tt> option to the +field+ method:
   <%= f.field :magic, :long => true %>
Different field types may deal with this option differently, and some may ignore
it entirely.

== Overview of the +LinedBuilder+

+LinedBuilder+ is a Rails form builder that adds support for labels and pretty
error handling to forms. +LinedBuilder+ wraps each input element created by a
call to a field helper in a div of CSS class +form_line+. It also gives it a
label (by default, this contains the humanized name of the field) and, if an
error exists, it provides a nested div within the +form_line+ of CSS class
+field_error+ and the div's class is changed to
<tt>form_line with_errors</tt>. More details are below.

A short example now. Assume there are three fields for a model -- `number',
`date', and `name'. `name' is blank but should not be, and so has an error on
it. The ERB code:

 <% lined_form_for @model do |f| %>
   <%= f.field :name %>
   <%= f.text_field :number %>
   <%= f.field :date %>
 <% end %>

Will yield the HTML output:

 <form ...>
    <div class="form_line with_errors">
        <div class="field_error">Name should not be blank.</div>
        <label for="model_name">Name:</label>
        <input type="text" name="model[name]" id="model_name" value="" />
    <div class="form_line">
        <label for="model_number">Number:</label>
        <input type="text" name="model[number]" id="model_number" />
    <div class="form_line">
        <label for="model_date">Date:</label>
        <!-- A date selector. -->

See the section on +LinedBuilder+ below for more details.

== The +field+ Method

The field method automatically takes care of generating a field of the
appropriate type for you in a form. It even takes care of a lot of the magic of
collection fields. Some details on the inner workings follow. See also the
documentation for the +AwesomeFieldHelpers+ for more information.

=== Field Generation
There are two steps to generating the field: first, we determine what type of
field to generate, then we generate the actual HTML for it.

There are two ways we use to find the type of field to generate. First, we run
the method itself and look for what the class of the object returned is. If we
get a nil result from the method, then we use the actual database type as our

To generate the actual HTML, we call a helper method. For example, if we had a
string field, then we would call +string_field+. Since there are already methods
for most fields, we simply alias the existing methods to the relevant ones.
Sometimes, the mapping isn't one-to-one. For example, in the case of strings,
sometimes we'll need to make the field a text area and other times just a simple
text field (see the situation where we're using the <tt>:long</tt> option
above). In these cases, we can implement the actual method and have it dispatch
to the relevant helper methods.

What if you want to specialize the behavior in one of your builders? Just
override the relevant methods! Then there's the other situation -- one where
maybe you've serialized an object to the database in YAML form, and you want to
display a field for it. Since the returned value from the method will be of your
class, we may be unable to resolve that class to an actual field type. In this
case, you can either alias in your own helper or implement the relevant method
in your own builder. The pattern of the methods called is simply the class name
underscored (literally, the result of
<tt>@object.send(method).class.underscore</tt>) followed by +_field+. So Strings
go to +string_field+, Dates to +date_field+, and DateTimes to +date_time_field+.

== Collection Fields
Basic fields are all well and good, but it'd be nice to be able to automatically
generate select boxes based on collection fields, too, and have them behave as
expected. Magic fields makes this easier to a certain extent, as well. First of
all, if a field returns a value that responds to the +collect+ method, then
the field is assumed to be a collection field (an exception is made for Strings,
which do respond to +collect+, but are handled as regular text fields).

Then, we use +collection_select+ to generate the appropriate field (actually, we
use +select+, because +collection_select+ doesn't allow us to easily indicate
the multiple objects that should be preselected). By default, the +value_method+
used to determine the value for the collection options is +id+. If a
+text_method+ is not specified, then the +name+ or +to_s+ methods are used (they
are attempted in that order).

For +select+, we also need an original collection -- basically, a list of all of
the possible values -- to use with the list of selected values.  If the objects
inside the collection are AR objects, then we take their class and issue a
<tt>find(:all)</tt> on it. For example, with this call:

 f.field :collection_method

If +collection_method+ returned a list of Post objects, then we issue a
<tt>Post::find(:all)</tt> to determine the full collection (of selected and
unselected values). This guessing can be overridden by providing a collection to
use instead by passing the <tt>:collection</tt> option with the relevant

You can override both the method used for display text and that used for the
option value by passing the +text_method+ and +value_method+ options to the
+field+ helper. Further options and HTML options are passed on to
+select+, as usual.

=== What About Collections of Non-ActiveRecord Objects?
Unfortunately, this convenience comes at a slight price when it comes to
collections of non-AR objects. If you want to use +field+ with its collection
field magic and you've got, say, integers in the collection, then you'll have to
do a bit of extra work and specify both the value and text methods, like so:

 f.field :numbers, :value_method => :to_int, :text_method => :to_int

In this case, since we're getting numbers out, we just use the +to_int+ method
for both the value and the text.

=== Notes
Since Rails will typecast date and datetime fields to the Ruby +Time+ class,
these typically won't be recognized appropriately. Currently, the +time_field+
method is implemented to double-check with the database the type that needs to
be used.  If you implement accessors for the relevant fields to return objects
of the appropriate type (see http://www.railsweenie.com/forums/1/topics/936 for
an example of how you could do this), then the appropriate methods will be
called without the extra level of indirection. Sadly, this specialization means
that any Time fields will always have their type checked twice.

Also, the presence of <tt>FormBuilder#field</tt> does NOT in any way mean the
other helpers are not available for use. If the decisions +field+ makes don't
float your boat, feel free to put in a direct call to the regular helpers. The
purpose of +field+ is to try and reduce the repetition (it's a already a string,
why say it again?), not to get in your way. If it's getting in your way, you
probably need a different solution.

== The +LinedBuilder+ Class

+LinedBuilder+ is meant to take the pain out of creating forms whose fields fit
on multiple lines and whose fields have labels and correlated errors. By
default, Rails's +FormBuilder+ doesn't do this. This builder provides those
capabilities transparently.

Because this builder is a self-contained class, the detailed documentation for
it is in the <tt>AwesomeFields::LinedBuilder</tt> documentation. Go get it!

== License and Such

+awesome_fields+ is Copyright (c) 2008 Antonio Salazar Cardozo, released under
the MIT license.