0
@@ -1,6 +1,81 @@
0
 module AwesomeFields
0
-  # This class builds form fields wrapped in divs with CSS class form_line and
0
-  # appropriate labels.
0
+  # This class presents a builder that provides a per-field block-level element.
0
+  # The class also takes care of labeling fields, as well as adding errors to
0
+  # the fields when needed.
0
+  #
0
+  # == Label
0
+  #
0
+  # Each field method that has been redefined in this builder uses the field
0
+  # name as a label by default (converted to the label text by #humanize-ing it.
0
+  # It also takes an optional <tt>:label</tt> parameter that specifies label
0
+  # text other than the humanized field name. Whatever the field, it is placed
0
+  # in label tag that is linked to the generated field when possible.
0
+  #
0
+  # In addition, the <tt>:no_label</tt> option may be passed to omit the label
0
+  # when generating the field.
0
+  #
0
+  # == Wrapping div
0
+  #
0
+  # When producing a field, the field is wrapped with a div whose CSS class is
0
+  # +form_line+. If the field has errors, that class is instead
0
+  # +form_line_with_errors+. This div is, obviously, a block-level element by
0
+  # default, but can be floated or what have you if needed.
0
+  #
0
+  # == Errors
0
+  #
0
+  # As mentioned above, if the field has an error, the wrapping div is given the
0
+  # +form_line_with_errors+ CSS class instead of the regular +form_line+ class.
0
+  # Additionally, the error text is placed within the containing +form_line+ div
0
+  # within its own div, whose class is +field_error+.
0
+  #
0
+  # The error message is assembled in parts: first, the field is checked for
0
+  # errors. If it has more than one error, these are turned into a sentence via
0
+  # a call to +to_sentence+. Then, the error text has the label prepended to it.
0
+  # By default, the label is the field name, so the error text will have the
0
+  # field name, humanized, prepended to it. Finally, a period (.) is appended to
0
+  # the end. This is the error message that is displayed.
0
+  #
0
+  # == Results
0
+  #
0
+  # The resulting structure of a field with errors is:
0
+  #
0
+  #  <div class="form_line_with_errors">
0
+  #    <div class="field_error">Field should not be blank.</div>
0
+  #
0
+  #    <label for="model_field">Field:</label>
0
+  #    <input type="text" id="model_field" name="model[field]" value="" />
0
+  #  </div>
0
+  #
0
+  # While one without errors has structure:
0
+  #
0
+  #  <div class="form_line">
0
+  #    <label for="model_field">Field:</label>
0
+  #    <input type="text" id="model_field" name="model[field]" value="" />
0
+  #  </div>
0
+  #
0
+  #  And one with no errors and no label has structure:
0
+  #
0
+  #  <div class="form_line">
0
+  #    <input type="text" id="model_field" name="model[field]" value="" />
0
+  #  </div>
0
+  #
0
+  # == <tt>:long</tt> option
0
+  #
0
+  # All helpers support a <tt>:long</tt> option in case the field is meant to
0
+  # contain `long' content. For most fields, all this means is that the label
0
+  # for the field will receive the CSS class +long+ if that option is set to
0
+  # true.
0
+  #
0
+  # Currently the only exception to this is +text_area+, which makes use of the
0
+  # <tt>:long</tt> option to modify the default rows and columns of the text
0
+  # area. If the text area is not `long', then it has 10 rows and 30 columns. If
0
+  # it is `long', then it has 20 rows and 70 columns.
0
+  #
0
+  # == Submit button
0
+  #
0
+  # This builder also adds a method +submit_button+ (which is aliased to the
0
+  # default +submit+) that wraps the submit button in a div of class
0
+  # +form_buttons+.
0
   class LinedBuilder < ActionView::Helpers::FormBuilder
0
     def text_field(label, options = {})
0
       labeled_field(label, options) { super label, options }
0
@@ -18,6 +93,10 @@ module AwesomeFields
0
       labeled_field(label, options) { super label, options }
0
     end
0
 
0
+    # Takes the additional option <tt>:long</tt> which, if set to true, will, in
0
+    # addition to setting the label's CSS class to +long+ (which happens for all
0
+    # other fields to), change the default rows and columns to 20x70 (instead of
0
+    # the non-long 10x30 defaults).
0
     def text_area(label, options = {})
0
       if options[:long]
0
         options.reverse_merge!({ :rows => 20, :cols => 70 })
0
@@ -28,13 +107,18 @@ module AwesomeFields
0
       labeled_field(label, options) { super label, options }
0
     end
0
 
0
+    # Produces a date select. The date select has a default order of month, day,
0
+    # year. Aliased as +date_field+ for uniformity with other field invocations
0
+    # and for good interoperability with the +AwesomeFields+ field helpers.
0
     def date_select(label, options = {})
0
-      options.merge!({ :order => [ :month, :day, :year ] })
0
+      options.reverse_merge!({ :order => [ :month, :day, :year ] })
0
 
0
       labeled_field(label, options) { super label, options }
0
     end
0
     alias_method :date_field, :date_select
0
 
0
+    # Produces a select box. If the html_options contains the <tt>:multiple</tt>
0
+    # option and it is set to true, then the default size is set to 5.
0
     def select(label, choices, options = {}, html_options = {})
0
       err = error_on label, options
0
 
0
@@ -46,11 +130,17 @@ module AwesomeFields
0
         :class => err ? 'form_line_with_errors' : 'form_line' )
0
     end
0
 
0
+    # Produces a submit button wrapped in a div of class +form_buttons+. The
0
+    # label is turned into a string and humanized, so it can be a string,
0
+    # potentially underscored.
0
+    #
0
+    # Aliased to +submit+, which is the default Rails name for this method.
0
     def submit_button(label = 'submit', options = {})
0
       @template.content_tag 'div',
0
         @template.submit_tag(label.to_s.humanize),
0
         :class => 'form_buttons'
0
     end
0
+    alias_method :submit, :submit_button
0
 
0
    protected
0
     # Produces a labeled field given the label, the options, and a block that
0
@@ -91,5 +181,3 @@ module AwesomeFields
0
         :class => 'field_error'
0
     end
0
   end
0
-end
0
-