major revision of form_for documentation

1 files changed, 54 insertions, 35 deletions

diff --git a/actionpack/lib/action_view/helpers/form_helper.rb b/actionpack/lib/action_view/helpers/form_helper.rb
index 6d97038da9..88c2d7ba9d 100644
--- a/actionpack/lib/action_view/helpers/form_helper.rb
+++ b/actionpack/lib/action_view/helpers/form_helper.rb
@@ -86,15 +86,15 @@ module ActionView
       #     <%= f.text_field :author %><br />
       #   <% end %>
       #
-      # There, +form_for+ is able to generate the rest of RESTful parameters
+      # There, +form_for+ is able to generate the rest of RESTful form parameters
       # based on introspection on the record, but to understand what it does we
       # need to dig first into the alternative generic usage it is based upon.
       #
       # === Generic form_for
       #
-      # The generic way to call +form_for+ requires a few arguments:
+      # The generic way to call +form_for+ yields a form builder around a model:
       #
-      #   <% form_for :person, @person, :url => { :action => "update" } do |f| %>
+      #   <% form_for :person, :url => { :action => "update" } do |f| %>
       #     <%= f.error_messages %>
       #     First name: <%= f.text_field :first_name %><br />
       #     Last name : <%= f.text_field :last_name %><br />
@@ -102,21 +102,48 @@ module ActionView
       #     Admin?    : <%= f.check_box :admin %><br />
       #   <% end %>
       #
+      # There, the first argument is a symbol or string with the name of the
+      # object the form is about, and also the name of the instance variable the
+      # object is stored in.
+      #
+      # The form builder acts as a regular form helper that somehow carries the
+      # model. Thus, the idea is that
+      #
+      #   <%= f.text_field :first_name %>
+      #
+      # gets expanded to
+      #
+      #   <%= text_field :person, :first_name %>
+      #
+      # If the instance variable is not <tt>@person</tt> you can pass the actual
+      # record as the second argument:
+      #
+      #   <% form_for :person, person, :url => { :action => "update" } do |f| %>
+      #     ...
+      #   <% end %>
+      #
+      # In that case you can think
+      #
+      #   <%= f.text_field :first_name %>
+      #
+      # gets expanded to
+      #
+      #   <%= text_field :person, :first_name, :object => person %>
+      #
+      # You can even display error messages of the wrapped model this way:
+      #
+      #   <%= f.error_messages %>
+      #
+      # In any of its variants, the rightmost argument to +form_for+ is an
+      # optional hash of options:
+      #
+      # * <tt>:url</tt> - The URL the form is submit to. It takes the same fields
+      #   you pass to`+url_for+ or +link_to+. In particular you may pass here a
+      #   named route directly as well. Defaults to the current action.
+      # * <tt>:html</tt> - Optional HTML attributes for the form tag.
+      #
       # Worth noting is that the +form_for+ tag is called in a ERb evaluation block,
-      # not an ERb output block. So that's <tt><% %></tt>, not <tt><%= %></tt>. Also
-      # worth noting is that +form_for+ yields a form builder object, in this
-      # example as +f+, which emulates the API for the stand-alone FormHelper
-      # methods, but without the object name. So instead of <tt>text_field :person, :name</tt>,
-      # you get away with <tt>f.text_field :name</tt>. Notice that you can even do
-      # <tt><%= f.error_messages %></tt> to display the error messsages of the model
-      # object in question.
-      #
-      # Even further, the +form_for+ method allows you to more easily escape the
-      # instance variable convention. So while the stand-alone approach would require
-      # <tt>text_field :person, :name, :object => person</tt> to work with local
-      # variables instead of instance ones, the +form_for+ calls remain the same.
-      # You simply declare once with <tt>:person, person</tt> and all subsequent
-      # field calls save <tt>:person</tt> and <tt>:object => person</tt>.
+      # not an ERb output block. So that's <tt><% %></tt>, not <tt><%= %></tt>.
       #
       # Also note that +form_for+ doesn't create an exclusive scope. It's still
       # possible to use both the stand-alone FormHelper methods and methods from
@@ -133,40 +160,32 @@ module ActionView
       # designed to work with an object as base, like FormOptionHelper#collection_select
       # and DateHelper#datetime_select.
       #
-      # HTML attributes for the form tag can be given as <tt>:html => {...}</tt>.
-      # For example:
-      #
-      #   <% form_for :person, @person, :html => {:id => 'person_form'} do |f| %>
-      #     ...
-      #   <% end %>
-      #
-      # The above form will then have the +id+ attribute with the value "person_form",
-      # which you can then style with CSS or manipulate with JavaScript.
-      #
-      # === Relying on record identification
+      # === Resource-oriented style
       #
       # As we said above, in addition to manually configuring the +form_for+ call,
-      # you can rely on record identification, which will use the conventions and
-      # named routes of that approach. This is the preferred way to use +form_for+
-      # nowadays:
+      # you can rely on automated resource identification, which will use the conventions
+      # and named routes of that approach. This is the preferred way to use +form_for+
+      # nowadays.
+      #
+      # For example, if <tt>@post</tt> is an existing record you want to edit
       #
-      #   <% form_for(@post) do |f| %>
+      #   <% form_for @post do |f| %>
       #     ...
       #   <% end %>
       #
-      # This will expand to be the same as:
+      # is equivalent to something like:
       #
       #   <% form_for :post, @post, :url => post_path(@post), :html => { :method => :put, :class => "edit_post", :id => "edit_post_45" } do |f| %>
       #     ...
       #   <% end %>
       #
-      # And for new records:
+      # And for new records
       #
       #   <% form_for(Post.new) do |f| %>
       #     ...
       #   <% end %>
       #
-      # This will expand to be the same as:
+      # expands to be the same as
       #
       #   <% form_for :post, Post.new, :url => posts_path, :html => { :class => "new_post", :id => "new_post" } do |f| %>
       #     ...