From e4c5ddd83954a04be72f738f2f1c60739aacdd76 Mon Sep 17 00:00:00 2001 From: Marcel Molina Date: Sun, 6 May 2007 05:23:03 +0000 Subject: [PATCH] Modernize documentation for form helpers. Closes #8035. [jeremymcanally] git-svn-id: http://svn-commit.rubyonrails.org/rails/trunk@6689 5ecf4fe2-1ee6-0310-87b1-e25e094e27de --- actionpack/CHANGELOG | 2 + .../lib/action_view/helpers/form_helper.rb | 228 +++++++++++------- 2 files changed, 149 insertions(+), 81 deletions(-) diff --git a/actionpack/CHANGELOG b/actionpack/CHANGELOG index 0e4bfad3f3..039ed8aa52 100644 --- a/actionpack/CHANGELOG +++ b/actionpack/CHANGELOG @@ -1,5 +1,7 @@ *SVN* +* Modernize documentation for form helpers. [jeremymcanally] + * Add brief introduction to REST to the resources documentation. [fearoffish] * Fix various documentation typos throughout ActionPack. [Henrik N] diff --git a/actionpack/lib/action_view/helpers/form_helper.rb b/actionpack/lib/action_view/helpers/form_helper.rb index 543f451a7f..3af7236b30 100644 --- a/actionpack/lib/action_view/helpers/form_helper.rb +++ b/actionpack/lib/action_view/helpers/form_helper.rb @@ -4,85 +4,65 @@ module ActionView module Helpers - # 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. + # Form helpers are designed to make working with models much easier than 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. # - # 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: + # 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. # - # <% 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: - # - #
- # - # - # - # - #
- # - # The params object created for this would look like: - # - # {"commit"=>"Log in", "action"=>"create", "controller"=>"sessions", "login"=>"some_user", "password"=>"some_pass"} + # 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: # - # Note how the params are not nested when creating a form this way. - # - # An example that specifically deals with a person object: - # - # # 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| %> + # # Note: a @person variable will have been created in the controller. + # # For example: @person = Person.new + # <% form_for :person, @person, :url => { :action => "create" } do |f| %> # <%= f.text_field :first_name %> # <%= f.text_field :last_name %> - # <%= submit_tag 'Update' %> + # <%= submit_tag 'Create' %> # <% end %> # - # The html generated for this would be: + # The HTML generated for this would be: # - #
+ # # # - # + # #
# - # The params object created when this form is submitted would look like: + # The params object created when this form is submitted would look like: # - # {"action"=>"create", "controller"=>"sessions", "person"=>{"first_name"=>"William", "last_name"=>"Smith"}} + # {"action"=>"create", "controller"=>"persons", "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. + # 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. Example: + # If the object name contains square brackets the id for the object will be inserted. For example: # # <%= text_field "person[]", "name" %> # - # ...becomes: + # ...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: + # used by render_collection_of_partials, the index option may come in handy. Example: # # <%= text_field "person", "name", "index" => 1 %> # - # becomes + # ...becomes... # # # # 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 - # values for the fields. Examples: + # Creates a form and a scope around a specific model object that is used as a base for questioning about + # values for the fields. # # <% form_for :person, @person, :url => { :action => "update" } do |f| %> # First name: <%= f.text_field :first_name %> @@ -92,17 +72,17 @@ module FormHelper # <% end %> # # 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 + # 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. # - # That in itself is a modest increase in comfort. The big news is that form_for allows us to more easily escape the instance - # variable convention, so while the stand-alone approach would require text_field :person, :name, :object => person + # Even further, the form_for method allows you to more easily escape the instance variable convention. So while the stand-alone + # approach would require text_field :person, :name, :object => person # to work with local variables instead of instance ones, the form_for calls remain the same. You simply declare once with # :person, person and all subsequent field calls save :person and :object => person. # # 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 FormTagHelper. Example: + # and methods from FormTagHelper. For example: # # <% form_for :person, @person, :url => { :action => "update" } do |f| %> # First name: <%= f.text_field :first_name %> @@ -112,16 +92,19 @@ module FormHelper # <% end %> # # Note: This also works for the methods in FormOptionHelper and DateHelper that are designed to work with an object as base. - # Like collection_select and datetime_select. + # Like FormOptionHelper#collection_select and DateHelper#datetime_select. # - # Html attributes for the form tag can be given as :html => {...}. Example: + # HTML attributes for the form tag can be given as :html => {...}. 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. + # # You can also build forms using a customized FormBuilder class. Subclass FormBuilder and override or define some more helpers, - # then use your custom builder like so: + # then use your custom builder. For example, let's say you made a helper to automatically add labels to form inputs. # # <% form_for :person, @person, :url => { :action => "update" }, :builder => LabellingFormBuilder do |f| %> # <%= f.text_field :first_name %> @@ -130,12 +113,13 @@ module FormHelper # <%= check_box_tag "person[admin]", @person.company.admin? %> # <% end %> # - # In many cases you will want to wrap the above in another helper, such as: + # In many cases you will want to wrap the above in another helper, so you could do something like the following: # # def labelled_form_for(name, object, options, &proc) # form_for(name, object, options.merge(:builder => LabellingFormBuiler), &proc) # end # + # If you don't need to attach a form to a model instance, then check out FormTagHelper#form_tag. def form_for(object_name, *args, &proc) raise ArgumentError, "Missing block" unless block_given? options = args.last.is_a?(Hash) ? args.pop : {} @@ -145,8 +129,9 @@ def form_for(object_name, *args, &proc) end # Creates a scope around a specific model object like form_for, but doesn't create the form tags themselves. This makes - # fields_for suitable for specifying additional model objects in the same form. Example: + # fields_for suitable for specifying additional model objects in the same form: # + # ==== Examples # <% form_for :person, @person, :url => { :action => "update" } do |person_form| %> # First name: <%= person_form.text_field :first_name %> # Last name : <%= person_form.text_field :last_name %> @@ -156,8 +141,8 @@ def form_for(object_name, *args, &proc) # <% end %> # <% end %> # - # Note: This also works for the methods in FormOptionHelper and DateHelper that are designed to work with an object as base. - # Like collection_select and datetime_select. + # Note: This also works for the methods in FormOptionHelper and DateHelper that are designed to work with an object as base, + # like FormOptionHelper#collection_select and DateHelper#datetime_select. def fields_for(object_name, *args, &block) raise ArgumentError, "Missing block" unless block_given? options = args.last.is_a?(Hash) ? args.pop : {} @@ -169,27 +154,81 @@ def fields_for(object_name, *args, &block) # 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+. These options will be tagged onto the html as an html element attribute as in the example + # hash with +options+. These options will be tagged onto the html as an HTML element attribute as in the example # shown. # - # Examples (call, result): + # ==== Examples # text_field(:post, :title, :size => 20) - # + # # => + # + # text_field(:post, :title, :class => "create_input") + # # => + # + # text_field(:session, :user, :onchange => "if $('session[user]').value == 'admin' { alert('Your login can not be admin!'); }") + # # => + # + # text_field(:snippet, :code, :size => 20, :class => 'code_input') + # # => + # def text_field(object_name, method, options = {}) InstanceTag.new(object_name, method, self, nil, options.delete(:object)).to_input_field_tag("text", options) end - # Works just like text_field, but returns an input tag of the "password" type instead. + # Returns an input tag of the "password" 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+. These options will be tagged onto the html as an HTML element attribute as in the example + # shown. + # + # ==== Examples + # password_field(:login, :pass, :size => 20) + # # => + # + # password_field(:account, :secret, :class => "form_input") + # # => + # + # password_field(:user, :password, :onchange => "if $('user[password]').length > 30 { alert('Your password needs to be shorter!'); }") + # # => + # + # password_field(:account, :pin, :size => 20, :class => 'form_input') + # # => + # def password_field(object_name, method, options = {}) InstanceTag.new(object_name, method, self, nil, options.delete(:object)).to_input_field_tag("password", options) end - # Works just like text_field, but returns an input tag of the "hidden" type instead. + # Returns a hidden input tag 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+. These options will be tagged onto the html as an html element attribute as in the example + # shown. + # + # ==== Examples + # hidden_field(:signup, :pass_confirm) + # # => + # + # hidden_field(:post, :tag_list) + # # => + # + # hidden_field(:user, :token) + # # => def hidden_field(object_name, method, options = {}) InstanceTag.new(object_name, method, self, nil, options.delete(:object)).to_input_field_tag("hidden", options) end - # Works just like text_field, but returns an input tag of the "file" type instead, which won't have a default value. + # Returns an file upload input tag 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+. These options will be tagged onto the html as an html element attribute as in the example + # shown. + # + # ==== Examples + # file_field(:user, :avatar) + # # => + # + # file_field(:post, :attached, :accept => 'text/html') + # # => + # + # file_field(:attachment, :file, :class => 'file_input') + # # => + # def file_field(object_name, method, options = {}) InstanceTag.new(object_name, method, self, nil, options.delete(:object)).to_input_field_tag("file", options) end @@ -198,11 +237,26 @@ def file_field(object_name, method, options = {}) # on an object assigned to the template (identified by +object+). Additional options on the input tag can be passed as a # hash with +options+. # - # Example (call, result): - # text_area("post", "body", "cols" => 20, "rows" => 40) - # + # ==== Examples + # text_area(:post, :body, :cols => 20, :rows => 40) + # # => + # + # text_area(:comment, :text, :size => "20x30") + # # => + # + # text_area(:application, :notes, :cols => 40, :rows => 15, :class => 'app_input') + # # => + # + # text_area(:entry, :body, :size => "20x20", :disabled => 'disabled') + # # => def text_area(object_name, method, options = {}) InstanceTag.new(object_name, method, self, nil, options.delete(:object)).to_text_area_tag(options) end @@ -211,18 +265,24 @@ def text_area(object_name, method, options = {}) # assigned to the template (identified by +object+). It's intended that +method+ returns an integer and if that # integer is above zero, then the checkbox is checked. Additional options on the input tag can be passed as a # hash with +options+. The +checked_value+ defaults to 1 while the default +unchecked_value+ - # is set to 0 which is convenient for boolean values. Usually unchecked checkboxes don't post anything. - # We work around this problem by adding a hidden value with the same name as the checkbox. + # is set to 0 which is convenient for boolean values. Since HTTP standards say that unchecked checkboxes don't post anything, + # we add a hidden value with the same name as the checkbox as a work around. # - # Example (call, result). Imagine that @post.validated? returns 1: + # ==== Examples + # # Let's say that @post.validated? is 1: # check_box("post", "validated") - # - # + # # => + # # # - # Example (call, result). Imagine that @puppy.gooddog returns "no": + # # Let's say that @puppy.gooddog is "no": # check_box("puppy", "gooddog", {}, "yes", "no") - # - # + # # => + # # + # + # check_box("eula", "accepted", {}, "yes", "no", :class => 'eula_check') + # # => + # # + # def check_box(object_name, method, options = {}, checked_value = "1", unchecked_value = "0") InstanceTag.new(object_name, method, self, nil, options.delete(:object)).to_check_box_tag(options, checked_value, unchecked_value) end @@ -231,12 +291,18 @@ def check_box(object_name, method, options = {}, checked_value = "1", unchecked_ # assigned to the template (identified by +object+). If the current value of +method+ is +tag_value+ the # radio button will be checked. Additional options on the input tag can be passed as a # hash with +options+. - # Example (call, result). Imagine that @post.category returns "rails": + # + # ==== Examples + # # Let's say that @post.category returns "rails": # radio_button("post", "category", "rails") # radio_button("post", "category", "java") - # - # + # # => + # # # + # radio_button("user", "receive_newsletter", "yes") + # radio_button("user", "receive_newsletter", "no") + # # => + # # def radio_button(object_name, method, tag_value, options = {}) InstanceTag.new(object_name, method, self, nil, options.delete(:object)).to_radio_button_tag(tag_value, options) end -- GitLab