diff --git a/actionpack/lib/action_view/helpers/form_helper.rb b/actionpack/lib/action_view/helpers/form_helper.rb index 71838c9d0b..f583414622 100644 --- a/actionpack/lib/action_view/helpers/form_helper.rb +++ b/actionpack/lib/action_view/helpers/form_helper.rb @@ -4,47 +4,63 @@ require 'action_view/helpers/tag_helper' module ActionView module Helpers - # Provides a set of methods for working with forms and especially forms related to objects assigned to the template. - # The following is an example of a complete form for a person object that works for both creates and updates built - # with all the form helpers. The @person object was assigned by an action on the controller: - #
+ # # - # ...is compiled to: + # The params object created for this would look like: # - # + # The html generated for this would be: # + # + # + # The params object created when this form is submitted would look like: + # + # {"action"=>"create", "controller"=>"sessions", "person"=>{"first_name"=>"William", "last_name"=>"Smith"}} + # + # The form_for method generates a form based on a method, in our example if the @person object had contained any + # values they would have been set in the form (this is how edit forms are created). Notice how the params hash + # has a nested 'person' value, which can therefore be accessed with params[:person] in the controller. + # # If the object name contains square brackets the id for the object will be inserted. Example: # # <%= text_field "person[]", "name" %> @@ -62,7 +78,7 @@ module ActionView # # # - # There's also methods for helping to build form tags in link:classes/ActionView/Helpers/FormOptionsHelper.html, + # There are also methods for helping to build form tags in link:classes/ActionView/Helpers/FormOptionsHelper.html, # link:classes/ActionView/Helpers/DateHelper.html, and link:classes/ActionView/Helpers/ActiveRecordHelper.html module FormHelper # Creates a form and a scope around a specific model object, which is then used as a base for questioning about @@ -75,8 +91,8 @@ module ActionView # Admin? : <%= f.check_box :admin %> # <% end %> # - # Worth noting is that the form_for tag is called in a ERb evaluation block, not a ERb output block. So that's <% %>, - # not <%= %>. Also worth noting is that the form_for yields a form_builder object, in this example as f, which emulates + # Worth noting is that the form_for tag is called in a ERb evaluation block, not an ERb output block. So that's <% %>, + # not <%= %>. 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 text_field :person, :name, # you get away with f.text_field :name. # @@ -153,10 +169,11 @@ module ActionView # Returns an input tag of the "text" type tailored for accessing a specified attribute (identified by +method+) on an object # assigned to the template (identified by +object+). Additional options on the input tag can be passed as a - # hash with +options+. + # hash with +options+. These options will be tagged onto the html as an html element attribute as in the example + # shown. # # Examples (call, result): - # text_field("post", "title", "size" => 20) + # text_field(:post, :title, :size => 20) # def text_field(object_name, method, options = {}) InstanceTag.new(object_name, method, self, nil, options.delete(:object)).to_input_field_tag("text", options) @@ -202,7 +219,7 @@ module ActionView # # # - # Example (call, result). Imagine that @puppy.gooddog returns no: + # Example (call, result). Imagine that @puppy.gooddog returns "no": # check_box("puppy", "gooddog", {}, "yes", "no") # #