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