From ef2ec071deba316d2f1f756f9591a153eb951219 Mon Sep 17 00:00:00 2001 From: Xavier Noria Date: Sat, 10 Apr 2010 16:49:39 -0700 Subject: makes a pass to the intro rdoc of form_helper.rb, will revise form_for tomorrow --- actionpack/lib/action_view/helpers/form_helper.rb | 112 ++++++++-------------- 1 file changed, 38 insertions(+), 74 deletions(-) (limited to 'actionpack/lib/action_view/helpers/form_helper.rb') diff --git a/actionpack/lib/action_view/helpers/form_helper.rb b/actionpack/lib/action_view/helpers/form_helper.rb index d2b3e2b214..92ec6ee632 100644 --- a/actionpack/lib/action_view/helpers/form_helper.rb +++ b/actionpack/lib/action_view/helpers/form_helper.rb @@ -8,90 +8,54 @@ require 'active_support/core_ext/object/blank' module ActionView module Helpers - # Form helpers are designed to make working with models much easier - # compared to using just standard HTML elements by providing a set of - # methods for creating forms based on your models. This helper generates - # the HTML for forms, providing a method for each sort of input - # (e.g., text, password, select, and so on). When the form is submitted - # (i.e., when the user hits the submit button or form.submit is - # called via JavaScript), the form inputs will be bundled into the - # params object and passed back to the controller. + # Form helpers are designed to make working with resources much easier + # compared to using vanilla HTML. # - # There are two types of form helpers: those that specifically work with - # model attributes and those that don't. This helper deals with those that - # work with model attributes; to see an example of form helpers that don't - # work with model attributes, check the ActionView::Helpers::FormTagHelper - # documentation. + # There are methods to generate all kinds of input fields and the form + # element itself. They get convenient names, IDs, endpoints, etc. so that + # you can work at the model level. Thanks to conventions in the HTML they + # generate controllers receive form data nicely structured in +params+. # - # The core method of this helper, form_for, gives you the ability to create - # a form for a model instance; for example, let's say that you have a model - # Person and want to create a new instance of it: + # Model-based forms are created with +form_for+. That method yields a form + # builder that knows the model the form is about. The form builder is thus + # able to generate default values for input fields that correspond to model + # attributes, and also convenient element names, IDs, endpoints, etc. # - # # Note: a @person variable will have been created in the controller. - # # For example: @person = Person.new - # <%= form_for @person do |f| %> - # <%= f.text_field :first_name %> - # <%= f.text_field :last_name %> - # <%= submit_tag 'Create' %> - # <% end %> + # Conventions in the generated field names allow controllers to receive form + # data nicely structured in +params+ with no effort on your side. # - # The HTML generated for this would be: + # For example, to create a new +Person+ resource you typically set up a new + # instance in PeopleController#new action, @person, and + # write the form in new.html.erb this way: # - #
- # - # - # - #
+ # <%= form_for @person do |f| %> + # <%= f.text_field :first_name %> + # <%= f.text_field :last_name %> + # <%= f.submit %> + # <% end %> # - # If you are using a partial for your form fields, you can use this shortcut: + # The HTML generated for this would be (modulus formatting): # - # <%= form_for @person do |form| %> - # <%= render form %> - # <%= submit_tag 'Create' %> - # <% end %> + #
+ #
+ # + #
+ # + # + # + #
# - # This example will render the people/_form partial, setting a - # local variable called form which references the yielded - # FormBuilder. The params object created when this form is - # submitted would look like: + # Because of the names of the input fields, the controller gets a :person + # nested hash in +params+ with the corresponding first and last names. That hash + # is ready to be passed to Person.create like this: # - # {"action"=>"create", "controller"=>"persons", "person"=>{"first_name"=>"William", "last_name"=>"Smith"}} + # if person = Person.create(params[:person]) + # # success + # else + # # error handling + # end # - # The params hash has a nested person value, which can therefore - # be accessed with params[:person] in the controller. If were - # editing/updating an instance (e.g., Person.find(1) rather than - # Person.new in the controller), the objects attribute values are - # filled into the form (e.g., the person_first_name field would - # have that person's first name in it). - # - # If the object name contains square brackets the id for the object will be - # inserted. For example: - # - # <%= text_field "person[]", "name" %> - # - # ...will generate the following ERb. - # - # - # - # If the helper is being used to generate a repetitive sequence of similar - # form elements, for example in a partial used by - # render_collection_of_partials, the index option may - # come in handy. Example: - # - # <%= text_field "person", "name", "index" => 1 %> - # - # ...becomes... - # - # - # - # An index option may also be passed to form_for and - # fields_for. This automatically applies the index to - # all the nested fields. - # - # 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 + # That's how you tipically work with resources. module FormHelper extend ActiveSupport::Concern -- cgit v1.2.3