Awesome fields is a plugin that adds an extension to the built-in Rails FormBuilder in the form of a new method, FormBuilder#field. 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).

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
end

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 :long 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.

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 form_line with_errors. 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>
   <div class="form_line">
       <label for="model_number">Number:</label>
       <input type="text" name="model[number]" id="model_number" />
   </div>
   <div class="form_line">
       <label for="model_date">Date:</label>
       <!-- A date selector. -->
   </div>
</form>

See the section on LinedBuilder below for more details.

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.

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

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 :long 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 @object.send(method).class.underscore) followed by _field. So Strings go to string_field, Dates to date_field, and DateTimes to date_time_field.

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. Awesome 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 to_param. 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 find(:all) on it. If there are no available objects, then we attempt to reflect on the association for the given method to determine the right class. For example, with this call:

f.field :collection_method

If collection_method returned a list of Post objects (or a single Post object), then we issue a Post::find(:all) to determine the full collection (of selected and unselected values). If an empty list is returned, or nil, then we look up the association for the object on collection_method and try to invoke a find(:all) on that class. This guessing can be overridden by passing the :collection option with the desired collection.

Note also that the set of selected items (or the single selected item) can be overridden by providing a collection or object to use instead through the :selected option. If :collection is not provided, the class of this object or of the first item in the list will be used to run the find metnioned above.

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.

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.

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 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 FormBuilder#field 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.

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 AwesomeFields::LinedBuilder documentation. Go get it!

awesome_fields is Copyright © 2008 Antonio Salazar Cardozo, released under the MIT license.