From cd4dbd8cd2fce4c0f0b7ad216003cd8da7732128 Mon Sep 17 00:00:00 2001 From: David Heinemeier Hansson Date: Sun, 25 Feb 2007 20:19:24 +0000 Subject: Doc fixes git-svn-id: http://svn-commit.rubyonrails.org/rails/trunk@6234 5ecf4fe2-1ee6-0310-87b1-e25e094e27de --- actionpack/lib/action_view/helpers/form_helper.rb | 89 ++++++++++++++--------- 1 file changed, 53 insertions(+), 36 deletions(-) (limited to 'actionpack/lib/action_view') 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: - #
- # Name: - # <%= text_field "person", "name", "size" => 20 %> + # Form helpers are designed to make working with models much easier than just standard html elements. These helpers + # provide a set of methods for creating forms based on your models. Each helper deals with a different type of data. + # Instead of creating the html elements manually, you ask the helpers to create the form element. When the form is + # submitted i.e. when the user hits the submit button, the form elements will be bundled into the params object and + # passed back to the controller. # - # Password: - # <%= password_field "person", "password", "maxsize" => 20 %> + # There are two types of form helper, those that specifically work with the attributes on models, and those that don't. + # First, an example of a form generated for a login page that doesn't deal with model attributes: # - # Single?: - # <%= check_box "person", "single" %> + # <% form_tag :controller => 'sessions', :action => 'new' do -%> + # <%= text_field_tag 'login' %> + # <%= password_field_tag 'password' %> + # + # <%= submit_tag 'Log in' %> + # <% end -%> + # + # This would generate the following html: + # + # + # + # + # + # + #
# - # Description: - # <%= text_area "person", "description", "cols" => 20 %> + # The params object created for this would look like: # - # - # + # {"commit"=>"Log in", "action"=>"create", "controller"=>"sessions", "login"=>"some_user", "password"=>"some_pass"} # - # ...is compiled to: + # Note how the params are not nested when creating a form this way. # - #
- # Name: - # + # An example that specifically deals with a person object: # - # Password: - # + # # Note: a @person variable will have been created in the controller and populated with data + # # e.g. @person = Person.find(1) + # <% form_for :person, @person, :url => { :action => "update" } do |f| %> + # <%= f.text_field :first_name %> + # <%= f.text_field :last_name %> + # <%= submit_tag 'Update' %> + # <% end %> # - # Single?: - # + # The html generated for this would be: # - # Description: - # + # + # + # + # + #
# - # - # + # 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") # # -- cgit v1.2.3