move the fields_for/form builder section higher up

1 files changed, 55 insertions, 53 deletions

diff --git a/railties/doc/guides/source/form_helpers.txt b/railties/doc/guides/source/form_helpers.txt
index 2f8cb68b38..44a06f2ffb 100644
--- a/railties/doc/guides/source/form_helpers.txt
+++ b/railties/doc/guides/source/form_helpers.txt
@@ -512,6 +512,61 @@ As a rule of thumb you should be using `date_select` when working with model obj
 
 NOTE:In many cases the built in date pickers are clumsy as they do not aid the user in working out the relationship between the date and the day of the week
 
+Scoping out form controls with `fields_for`
+-------------------------------------------
+
+`fields_for` creates a form builder in exactly the same way as `form_for` but doesn't create the actual `<form>` tags. It creates a scope around a specific model object like `form_for`, which is useful for specifying additional model objects in the same form. For example if you had a Person model with an associated ContactDetail model you could create a form for editing both like so:
+-------------
+<% form_for @person do |person_form| %>
+  <%= person_form.text_field :name %>
+  <% fields_for @person.contact_detail do |contact_details_form| %>
+    <%= contact_details_form.text_field :phone_number %>
+  <% end %>
+<% end %>
+-------------
+
+which produces the following output:
+
+-------------
+<form action="/people/1" class="edit_person" id="edit_person_1" method="post">
+  <input id="person_name" name="person[name]" size="30" type="text" />  
+  <input id="contact_detail_phone_number" name="contact_detail[phone_number]" size="30" type="text" />
+</form>
+-------------
+
+Form builders
+-------------
+
+As mentioned previously the object yielded by `form_for` and `fields_for` is an instance of FormBuilder (or a subclass thereof). Form builders encapsulate the notion of displaying a form elements for a single object. While you can of course write helpers for your forms in the usual way you can also subclass FormBuilder and add the helpers there. For example 
+
+----------
+<% form_for @person  do |f| %>
+  <%= text_field_with_label f, :first_name %>
+<% end %>
+----------
+can be replaced with 
+----------
+<% form_for @person, :builder => LabellingFormBuilder do |f| %>
+  <%= f.text_field :first_name %>
+<% end %>
+----------
+by defining a LabellingFormBuilder class similar to the following:
+-------
+class LabellingFormBuilder < FormBuilder
+  def text_field attribute, options={}
+    label(attribute) + text_field(attribute, options)
+  end
+end
+-------
+If you reuse this frequently you could define a `labeled_form_for` helper that automatically applies the `:builder => LabellingFormBuilder` option.
+
+The form builder used also determines what happens when you do
+------
+<%= render :partial => f %>
+------
+If `f` is an instance of FormBuilder then this will render the 'form' partial, setting the partial's object to the form builder. If the form builder is of class LabellingFormBuilder then the 'labelling_form' partial would be rendered instead.
+
+
 Parameter Names
 ---------------
 [[parameter_names]]
@@ -581,59 +636,6 @@ File upload form
 
 :multipart - If set to true, the enctype is set to "multipart/form-data".
 
-Scoping out form controls with `fields_for`
--------------------------------------------
-
-`fields_for` creates a form builder in exactly the same way as `form_for` but doesn't create the actual `<form>` tags. It creates a scope around a specific model object like `form_for`, which is useful for specifying additional model objects in the same form. For example if you had a Person model with an associated ContactDetail model you could create a form for editing both like so:
--------------
-<% form_for @person do |person_form| %>
-  <%= person_form.text_field :name %>
-  <% fields_for @person.contact_detail do |contact_details_form| %>
-    <%= contact_details_form.text_field :phone_number %>
-  <% end %>
-<% end %>
--------------
-
-which produces the following output:
-
--------------
-<form action="/people/1" class="edit_person" id="edit_person_1" method="post">
-  <input id="person_name" name="person[name]" size="30" type="text" />  
-  <input id="contact_detail_phone_number" name="contact_detail[phone_number]" size="30" type="text" />
-</form>
--------------
-
-Form builders
--------------
-
-As mentioned previously the object yielded by `form_for` and `fields_for` is an instance of FormBuilder (or a subclass thereof). Form builders encapsulate the notion of displaying a form elements for a single object. While you can of course write helpers for your forms in the usual way you can also subclass FormBuilder and add the helpers there. For example 
-
-----------
-<% form_for @person  do |f| %>
-  <%= text_field_with_label f, :first_name %>
-<% end %>
-----------
-can be replaced with 
-----------
-<% form_for @person, :builder => LabellingFormBuilder do |f| %>
-  <%= f.text_field :first_name %>
-<% end %>
-----------
-by defining a LabellingFormBuilder class similar to the following:
--------
-class LabellingFormBuilder < FormBuilder
-  def text_field attribute, options={}
-    label(attribute) + text_field(attribute, options)
-  end
-end
--------
-If you reuse this frequently you could define a `labeled_form_for` helper that automatically applies the `:builder => LabellingFormBuilder` option.
-
-The form builder used also determines what happens when you do
-------
-<%= render :partial => f %>
-------
-If `f` is an instance of FormBuilder then this will render the 'form' partial, setting the partial's object to the form builder. If the form builder is of class LabellingFormBuilder then the 'labelling_form' partial would be rendered instead.
 
 
 * `form_for` within a namespace