Ruby on Rails | Screencasts | Download | Documentation | Weblog | Community | Source

Ticket #7618: changed_form_helper_documentation.diff

File changed_form_helper_documentation.diff, 7.7 kB (added by fearoffish, 3 years ago)

  • lib/action_view/helpers/form_helper.rb

    old new  
    44 
    55module ActionView 
    66  module Helpers 
    7     # Provides a set of methods for working with forms and especially forms related to objects assigned to the template. 
    8     # The following is an example of a complete form for a person object that works for both creates and updates built 
    9     # with all the form helpers. The <tt>@person</tt> object was assigned by an action on the controller: 
    10     #   <form action="save_person" method="post"> 
    11     #     Name: 
    12     #     <%= text_field "person", "name", "size" => 20 %> 
     7    # Form helpers are designed to make working with models much easier than just standard html elements.  These helpers 
     8    # provide a set of methods for creating forms based on your models.  Each helper deals with a different type of data. 
     9    # Instead of creating the html elements manually, you ask the helpers to create the form element.  When the form is  
     10    # submitted i.e. when the user hits the submit button, the form elements will be bundled into the params object and 
     11    # passed back to the controller. 
    1312    # 
    14     #     Password: 
    15     #     <%= password_field "person", "password", "maxsize" => 20 %> 
     13    # There are two types of form helper, those that specifically work with the attributes on models, and those that don't.   
     14    # First, an example of a form generated for a login page that doesn't deal with model attributes: 
    1615    # 
    17     #     Single?: 
    18     #     <%= check_box "person", "single" %> 
     16    #     <% form_tag :controller => 'sessions', :action => 'new' do -%> 
     17    #       <%= text_field_tag 'login' %> 
     18    #       <%= password_field_tag 'password' %> 
     19    #  
     20    #       <%= submit_tag 'Log in' %> 
     21    #     <% end -%> 
    1922    # 
    20     #     Description: 
    21     #     <%= text_area "person", "description", "cols" => 20 %> 
     23    # This would generate the following html: 
    2224    # 
    23     #     <input type="submit" value="Save"> 
    24     #   </form> 
     25    #     <form action="/sessions/new" method="post"> 
     26    #       <input id="login" name="login" type="text" /> 
     27    #       <input id="password" name="password" type="password" /> 
     28    #      
     29    #       <input name="commit" type="submit" value="Log in" /> 
     30    #     </form> 
    2531    # 
    26     # ...is compiled to: 
     32    # The params object created for this would look like: 
    2733    # 
    28     #   <form action="save_person" method="post"> 
    29     #     Name: 
    30     #     <input type="text" id="person_name" name="person[name]" 
    31     #       size="20" value="<%= @person.name %>" /> 
     34    #     {"commit"=>"Log in", "action"=>"create", "controller"=>"sessions", "login"=>"some_user", "password"=>"some_pass"} 
    3235    # 
    33     #     Password: 
    34     #     <input type="password" id="person_password" name="person[password]" 
    35     #       size="20" maxsize="20" value="<%= @person.password %>" /> 
     36    # Note how the params are not nested when creating a form this way. 
    3637    # 
    37     #     Single?: 
    38     #     <input type="checkbox" id="person_single" name="person[single]" value="1" /> 
     38    # An example that specifically deals with a person object: 
    3939    # 
    40     #     Description: 
    41     #     <textarea cols="20" rows="40" id="person_description" name="person[description]"> 
    42     #       <%= @person.description %> 
    43     #     </textarea> 
     40    #     # Note: a @person variable will have been created in the controller and populated with data  
     41    #     # e.g. @person = Person.find(1) 
     42    #     <% form_for :person, @person, :url => { :action => "update" } do |f| %> 
     43    #       <%= f.text_field :first_name %> 
     44    #       <%= f.text_field :last_name %> 
     45    #       <%= submit_tag 'Update' %> 
     46    #     <% end %> 
    4447    # 
    45     #     <input type="submit" value="Save"> 
    46     #   </form> 
     48    # The html generated for this would be: 
    4749    # 
     50    #     <form action="/persons/update" method="post"> 
     51    #       <input id="person_first_name" name="person[first_name]" size="30" type="text" /> 
     52    #       <input id="person_last_name" name="person[last_name]" size="30" type="text" /> 
     53    #       <input name="commit" type="submit" value="Update" /> 
     54    #     </form> 
     55    # 
     56    # The params object created when this form is submitted would look like: 
     57    # 
     58    #     {"action"=>"create", "controller"=>"sessions", "person"=>{"first_name"=>"William", "last_name"=>"Smith"}} 
     59    #  
     60    # The form_for method generates a form based on a method, in our example if the @person object had contained any  
     61    # values they would have been set in the form (this is how edit forms are created).  Notice how the params hash  
     62    # has a nested 'person' value, which can therefore be accessed with params[:person] in the controller. 
     63    #     
    4864    # If the object name contains square brackets the id for the object will be inserted. Example: 
    4965    # 
    5066    #   <%= text_field "person[]", "name" %>  
    …… 
    6278    # 
    6379    #   <input type="text" id="person_1_name" name="person[1][name]" value="<%= @person.name %>" /> 
    6480    # 
    65     # There's also methods for helping to build form tags in link:classes/ActionView/Helpers/FormOptionsHelper.html, 
     81    # There are also methods for helping to build form tags in link:classes/ActionView/Helpers/FormOptionsHelper.html, 
    6682    # link:classes/ActionView/Helpers/DateHelper.html, and link:classes/ActionView/Helpers/ActiveRecordHelper.html 
    6783    module FormHelper 
    6884      # Creates a form and a scope around a specific model object, which is then used as a base for questioning about 
    …… 
    7591      #     Admin?    : <%= f.check_box :admin %> 
    7692      #   <% end %> 
    7793      # 
    78       # Worth noting is that the form_for tag is called in a ERb evaluation block, not a ERb output block. So that's <tt><% %></tt>,  
    79       # not <tt><%= %></tt>. Also worth noting is that the form_for yields a form_builder object, in this example as f, which emulates 
     94      # 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>,  
     95      # not <tt><%= %></tt>. Also worth noting is that form_for yields a form_builder object, in this example as f, which emulates 
    8096      # the API for the stand-alone FormHelper methods, but without the object name. So instead of <tt>text_field :person, :name</tt>, 
    8197      # you get away with <tt>f.text_field :name</tt>.  
    8298      # 
    …… 
    153169 
    154170      # Returns an input tag of the "text" type tailored for accessing a specified attribute (identified by +method+) on an object 
    155171      # assigned to the template (identified by +object+). Additional options on the input tag can be passed as a 
    156       # hash with +options+. 
     172      # hash with +options+.  These options will be tagged onto the html as an html element attribute as in the example 
     173      # shown. 
    157174      # 
    158175      # Examples (call, result): 
    159       #   text_field("post", "title", "size" => 20) 
     176      #   text_field(:post, :title, :size => 20) 
    160177      #     <input type="text" id="post_title" name="post[title]" size="20" value="#{@post.title}" /> 
    161178      def text_field(object_name, method, options = {}) 
    162179        InstanceTag.new(object_name, method, self, nil, options.delete(:object)).to_input_field_tag("text", options) 
    …… 
    202219      #     <input type="checkbox" id="post_validate" name="post[validated]" value="1" checked="checked" /> 
    203220      #     <input name="post[validated]" type="hidden" value="0" /> 
    204221      # 
    205       # Example (call, result). Imagine that @puppy.gooddog returns no: 
     222      # Example (call, result). Imagine that @puppy.gooddog returns "no": 
    206223      #   check_box("puppy", "gooddog", {}, "yes", "no") 
    207224      #     <input type="checkbox" id="puppy_gooddog" name="puppy[gooddog]" value="yes" /> 
    208225      #     <input name="puppy[gooddog]" type="hidden" value="no" />