Massive documentation update for all helpers (closes #8223, #8177, #8175, #8108, #7977, #7972, #7971, #7969) [jeremymcanally]

git-svn-id: http://svn-commit.rubyonrails.org/rails/trunk@7106 5ecf4fe2-1ee6-0310-87b1-e25e094e27de

1 files changed, 251 insertions, 48 deletions

diff --git a/actionpack/lib/action_view/helpers/form_tag_helper.rb b/actionpack/lib/action_view/helpers/form_tag_helper.rb
index cf8fb74f59..bf82fa234a 100644
--- a/actionpack/lib/action_view/helpers/form_tag_helper.rb
+++ b/actionpack/lib/action_view/helpers/form_tag_helper.rb
@@ -3,33 +3,36 @@ require 'action_view/helpers/tag_helper'
 
 module ActionView
   module Helpers
-    # Provides a number of methods for creating form tags that doesn't rely on conventions with an object assigned to the template like
-    # FormHelper does. With the FormTagHelper, you provide the names and values yourself.
+    # Provides a number of methods for creating form tags that doesn't rely on an ActiveRecord object assigned to the template like
+    # FormHelper does. Instead, you provide the names and values manually.
     #
-    # NOTE: The html options disabled, readonly, and multiple can all be treated as booleans. So specifying <tt>:disabled => true</tt>
-    # will give <tt>disabled="disabled"</tt>.
+    # NOTE: The HTML options <tt>disabled</tt>, <tt>readonly</tt>, and <tt>multiple</tt> can all be treated as booleans. So specifying 
+    # <tt>:disabled => true</tt> will give <tt>disabled="disabled"</tt>.
     module FormTagHelper
       # Starts a form tag that points the action to an url configured with <tt>url_for_options</tt> just like
       # ActionController::Base#url_for. The method for the form defaults to POST.
       #
-      # Examples:
-      # * <tt>form_tag('/posts') => <form action="/posts" method="post"></tt>
-      # * <tt>form_tag('/posts/1', :method => :put) => <form action="/posts/1" method="put"></tt>
-      # * <tt>form_tag('/upload', :multipart => true) => <form action="/upload" method="post" enctype="multipart/form-data"></tt>
-      # 
-      # ERb example:
-      #   <% form_tag '/posts' do -%>
-      #     <div><%= submit_tag 'Save' %></div>
-      #   <% end -%>
-      #
-      # Will output:
-      #   <form action="/posts" method="post"><div><input type="submit" name="submit" value="Save" /></div></form>
-      #
-      # Options:
+      # ==== Options
       # * <tt>:multipart</tt> - If set to true, the enctype is set to "multipart/form-data".
       # * <tt>:method</tt>    - The method to use when submitting the form, usually either "get" or "post".
       #                         If "put", "delete", or another verb is used, a hidden input with name _method 
       #                         is added to simulate the verb over post.
+      # * A list of parameters to feed to the URL the form will be posted to.
+      #
+      # ==== Examples
+      #   form_tag('/posts')                      
+      #   # => <form action="/posts" method="post">
+      #
+      #   form_tag('/posts/1', :method => :put)   
+      #   # => <form action="/posts/1" method="put">
+      #
+      #   form_tag('/upload', :multipart => true) 
+      #   # => <form action="/upload" method="post" enctype="multipart/form-data">
+      # 
+      #   <% form_tag '/posts' do -%>
+      #     <div><%= submit_tag 'Save' %></div>
+      #   <% end -%>
+      #   # => <form action="/posts" method="post"><div><input type="submit" name="submit" value="Save" /></div></form>
       def form_tag(url_for_options = {}, options = {}, *parameters_for_url, &block)
         html_options = html_options_for_form(url_for_options, options, *parameters_for_url)
         if block_given?
@@ -39,45 +42,101 @@ module ActionView
         end
       end
 
-
       # Creates a dropdown selection box, or if the <tt>:multiple</tt> option is set to true, a multiple
       # choice selection box.
       #
       # Helpers::FormOptions can be used to create common select boxes such as countries, time zones, or
-      # associated records.
+      # associated records. <tt>option_tags</tt> is a string containing the option tags for the select box.
+      #
+      # ==== Options
+      # * <tt>:multiple</tt> - If set to true the selection will allow multiple choices.
+      # * <tt>:disabled</tt> - If set to true, the user will not be able to use this input.
+      # * Any other key creates standard HTML attributes for the tag.
       #
-      # <tt>option_tags</tt> is a string containing the option tags for the select box:
-      #   # Outputs <select id="people" name="people"><option>David</option></select>
+      # ==== Examples
       #   select_tag "people", "<option>David</option>"
+      #   # => <select id="people" name="people"><option>David</option></select>
       #
-      # Options:
-      # * <tt>:multiple</tt> - If set to true the selection will allow multiple choices.
+      #   select_tag "count", "<option>1</option><option>2</option><option>3</option><option>4</option>"
+      #   # => <select id="count" name="count"><option>1</option><option>2</option>
+      #   #    <option>3</option><option>4</option></select>
+      #
+      #   select_tag "colors", "<option>Red</option><option>Green</option><option>Blue</option>", :multiple => true
+      #   # => <select id="colors" multiple="multiple" name="colors"><option>Red</option>
+      #   #    <option>Green</option><option>Blue</option></select>
+      #
+      #   select_tag "locations", "<option>Home</option><option selected="selected">Work</option><option>Out</option>"
+      #   # => <select id="locations" name="locations"><option>Home</option><option selected='selected'>Work</option>
+      #   #    <option>Out</option></select>
+      #
+      #   select_tag "access", "<option>Read</option><option>Write</option>", :multiple => true, :class => 'form_input'
+      #   # => <select class="form_input" id="access" multiple="multiple" name="access"><option>Read</option>
+      #   #    <option>Write</option></select>
+      #
+      #   select_tag "destination", "<option>NYC</option><option>Paris</option><option>Rome</option>", :disabled => true
+      #   # => <select disabled="disabled" id="destination" name="destination"><option>NYC</option>
+      #   #    <option>Paris</option><option>Rome</option></select>
       def select_tag(name, option_tags = nil, options = {})
         content_tag :select, option_tags, { "name" => name, "id" => name }.update(options.stringify_keys)
       end
 
-      # Creates a standard text field.
+      # Creates a standard text field; use these text fields to input smaller chunks of text like a username
+      # or a search query.
       #
-      # Options:
+      # ==== Options
       # * <tt>:disabled</tt> - If set to true, the user will not be able to use this input.
       # * <tt>:size</tt> - The number of visible characters that will fit in the input.
       # * <tt>:maxlength</tt> - The maximum number of characters that the browser will allow the user to enter.
+      # * Any other key creates standard HTML attributes for the tag.
       # 
-      # A hash of standard HTML options for the tag.
+      # ==== Examples
+      #   text_field_tag 'name'
+      #   # => <input id="name" name="name" type="text" />
+      #
+      #   text_field_tag 'query', 'Enter your search query here'
+      #   # => <input id="query" name="query" type="text" value="Enter your search query here" />
+      #
+      #   text_field_tag 'request', nil, :class => 'special_input'
+      #   # => <input class="special_input" id="request" name="request" type="text" />
+      #
+      #   text_field_tag 'address', '', :size => 75
+      #   # => <input id="address" name="address" size="75" type="text" value="" />
+      #
+      #   text_field_tag 'zip', nil, :maxlength => 5
+      #   # => <input id="zip" maxlength="5" name="zip" type="text" />
+      #
+      #   text_field_tag 'payment_amount', '$0.00', :disabled => true
+      #   # => <input disabled="disabled" id="payment_amount" name="payment_amount" type="text" value="$0.00" />
+      #
+      #   text_field_tag 'ip', '0.0.0.0', :maxlength => 15, :size => 20, :class => "ip-input"
+      #   # => <input class="ip-input" id="ip" maxlength="15" name="ip" size="20" type="text" value="0.0.0.0" />
       def text_field_tag(name, value = nil, options = {})
         tag :input, { "type" => "text", "name" => name, "id" => name, "value" => value }.update(options.stringify_keys)
       end
 
-      # Creates a hidden field.
+      # Creates a hidden form input field used to transmit data that would be lost due to HTTP's statelessness or
+      # data that should be hidden from the user.
+      #
+      # ==== Options
+      # * Creates standard HTML attributes for the tag.
+      #
+      # ==== Examples
+      #   hidden_field_tag 'tags_list'
+      #   # => <input id="tags_list" name="tags_list" type="hidden" />
       #
-      # Takes the same options as text_field_tag
+      #   hidden_field_tag 'token', 'VUBJKB23UIVI1UU1VOBVI@'
+      #   # => <input id="token" name="token" type="hidden" value="VUBJKB23UIVI1UU1VOBVI@" />
+      #
+      #   hidden_field_tag 'collected_input', '', :onchange => "alert('Input collected!')"
+      #   # => <input id="collected_input" name="collected_input" onchange="alert('Input collected!')" 
+      #   #    type="hidden" value="" />
       def hidden_field_tag(name, value = nil, options = {})
         text_field_tag(name, value, options.stringify_keys.update("type" => "hidden"))
       end
 
-      # Creates a file upload field.
+      # Creates a file upload field.  If you are using file uploads then you will also need 
+      # to set the multipart option for the form tag:
       #
-      # If you are using file uploads then you will also need to set the multipart option for the form:
       #   <%= form_tag { :action => "post" }, { :multipart => true } %>
       #     <label for="file">File to Upload</label> <%= file_field_tag "file" %>
       #     <%= submit_tag %>
@@ -85,23 +144,93 @@ module ActionView
       #
       # The specified URL will then be passed a File object containing the selected file, or if the field 
       # was left blank, a StringIO object.
+      #
+      # ==== Options
+      # * Creates standard HTML attributes for the tag.
+      # * <tt>:disabled</tt> - If set to true, the user will not be able to use this input.
+      #
+      # ==== Examples
+      #   file_field_tag 'attachment'
+      #   # => <input id="attachment" name="attachment" type="file" />
+      #
+      #   file_field_tag 'avatar', :class => 'profile-input'
+      #   # => <input class="profile-input" id="avatar" name="avatar" type="file" />
+      #
+      #   file_field_tag 'picture', :disabled => true
+      #   # => <input disabled="disabled" id="picture" name="picture" type="file" />
+      #
+      #   file_field_tag 'resume', :value => '~/resume.doc'
+      #   # => <input id="resume" name="resume" type="file" value="~/resume.doc" />
+      #
+      #   file_field_tag 'user_pic', :accept => 'image/png,image/gif,image/jpeg'
+      #   # => <input accept="image/png,image/gif,image/jpeg" id="user_pic" name="user_pic" type="file" /> 
+      #
+      #   file_field_tag 'file', :accept => 'text/html', :class => 'upload', :value => 'index.html'
+      #   # => <input accept="text/html" class="upload" id="file" name="file" type="file" value="index.html" />
       def file_field_tag(name, options = {})
         text_field_tag(name, nil, options.update("type" => "file"))
       end
 
-      # Creates a password field.
+      # Creates a password field, a masked text field that will hide the users input behind a mask character.
       #
-      # Takes the same options as text_field_tag
+      # ==== Options
+      # * <tt>:disabled</tt> - If set to true, the user will not be able to use this input.
+      # * <tt>:size</tt> - The number of visible characters that will fit in the input.
+      # * <tt>:maxlength</tt> - The maximum number of characters that the browser will allow the user to enter.
+      # * Any other key creates standard HTML attributes for the tag.
+      #
+      # ==== Examples
+      #   password_field_tag 'pass'
+      #   # => <input id="pass" name="pass" type="password" />
+      #
+      #   password_field_tag 'secret', 'Your secret here'
+      #   # => <input id="secret" name="secret" type="password" value="Your secret here" />
+      #
+      #   password_field_tag 'masked', nil, :class => 'masked_input_field'
+      #   # => <input class="masked_input_field" id="masked" name="masked" type="password" />
+      #
+      #   password_field_tag 'token', '', :size => 15
+      #   # => <input id="token" name="token" size="15" type="password" value="" />
+      #
+      #   password_field_tag 'key', nil, :maxlength => 16
+      #   # => <input id="key" maxlength="16" name="key" type="password" />
+      #
+      #   password_field_tag 'confirm_pass', nil, :disabled => true
+      #   # => <input disabled="disabled" id="confirm_pass" name="confirm_pass" type="password" />
+      #
+      #   password_field_tag 'pin', '1234', :maxlength => 4, :size => 6, :class => "pin-input"
+      #   # => <input class="pin-input" id="pin" maxlength="4" name="pin" size="6" type="password" value="1234" />
       def password_field_tag(name = "password", value = nil, options = {})
         text_field_tag(name, value, options.update("type" => "password"))
       end
 
-      # Creates a text input area.
+      # Creates a text input area; use a textarea for longer text inputs such as blog posts or descriptions.
+      #
+      # ==== Options
+      # * <tt>:size</tt> - A string specifying the dimensions of the textarea using dimensions (e.g., "25x10").
+      # * <tt>:rows</tt> - Specify the number of rows in the textarea
+      # * <tt>:cols</tt> - Specify the number of columns in the textarea
+      # * <tt>:disabled</tt> - If set to true, the user will not be able to use this input.
+      # * Any other key creates standard HTML attributes for the tag.
+      #
+      # ==== Examples
+      #   text_area_tag 'post'
+      #   # => <textarea id="post" name="post"></textarea>
+      #
+      #   text_area_tag 'bio', @user.bio
+      #   # => <textarea id="bio" name="bio">This is my biography.</textarea>
       #
-      # Options:
-      # * <tt>:size</tt> - A string specifying the dimensions of the textarea.
-      #     # Outputs <textarea name="body" id="body" cols="25" rows="10"></textarea>
-      #     <%= text_area_tag "body", nil, :size => "25x10" %>
+      #   text_area_tag 'body', nil, :rows => 10, :cols => 25
+      #   # => <textarea cols="25" id="body" name="body" rows="10"></textarea>
+      #
+      #   text_area_tag 'body', nil, :size => "25x10"
+      #   # => <textarea name="body" id="body" cols="25" rows="10"></textarea>
+      #
+      #   text_area_tag 'description', "Description goes here.", :disabled => true
+      #   # => <textarea disabled="disabled" id="description" name="description">Description goes here.</textarea>
+      #
+      #   text_area_tag 'comment', nil, :class => 'comment_input'
+      #   # => <textarea class="comment_input" id="comment" name="comment"></textarea>
       def text_area_tag(name, content = nil, options = {})
         options.stringify_keys!
 
@@ -112,14 +241,52 @@ module ActionView
         content_tag :textarea, content, { "name" => name, "id" => name }.update(options.stringify_keys)
       end
 
-      # Creates a check box.
+      # Creates a check box form input tag.
+      #
+      # ==== Options
+      # * <tt>:disabled</tt> - If set to true, the user will not be able to use this input.
+      # * Any other key creates standard HTML options for the tag.
+      #
+      # ==== Examples
+      #   check_box_tag 'accept'
+      #   # => <input id="accept" name="accept" type="checkbox" value="1" />
+      #
+      #   check_box_tag 'rock', 'rock music'
+      #   # => <input id="rock" name="rock" type="checkbox" value="rock music" />
+      #
+      #   check_box_tag 'receive_email', 'yes', true
+      #   # => <input checked="checked" id="receive_email" name="receive_email" type="checkbox" value="yes" />
+      #
+      #   check_box_tag 'tos', 'yes', false, :class => 'accept_tos'
+      #   # => <input class="accept_tos" id="tos" name="tos" type="checkbox" value="yes" />
+      #
+      #   check_box_tag 'eula', 'accepted', false, :disabled => true
+      #   # => <input disabled="disabled" id="eula" name="eula" type="checkbox" value="accepted" />
       def check_box_tag(name, value = "1", checked = false, options = {})
         html_options = { "type" => "checkbox", "name" => name, "id" => name, "value" => value }.update(options.stringify_keys)
         html_options["checked"] = "checked" if checked
         tag :input, html_options
       end
 
-      # Creates a radio button.
+      # Creates a radio button; use groups of radio buttons named the same to allow users to 
+      # select from a group of options.
+      #
+      # ==== Options
+      # * <tt>:disabled</tt> - If set to true, the user will not be able to use this input.
+      # * Any other key creates standard HTML options for the tag.
+      #
+      # ==== Examples
+      #   radio_button_tag 'gender', 'male'
+      #   # => <input id="gender_male" name="gender" type="radio" value="male" />
+      #
+      #   radio_button_tag 'receive_updates', 'no', true
+      #   # => <input checked="checked" id="receive_updates_no" name="receive_updates" type="radio" value="no" />
+      #
+      #   radio_button_tag 'time_slot', "3:00 p.m.", false, :disabled => true
+      #   # => <input disabled="disabled" id="time_slot_300_pm" name="time_slot" type="radio" value="3:00 p.m." />
+      #
+      #   radio_button_tag 'color', "green", true, :class => "color_input"
+      #   # => <input checked="checked" class="color_input" id="color_green" name="color" type="radio" value="green" />
       def radio_button_tag(name, value, checked = false, options = {})
         pretty_tag_value = value.to_s.gsub(/\s/, "_").gsub(/(?!-)\W/, "").downcase
         pretty_name = name.gsub(/\[/, "_").gsub(/\]/, "")
@@ -128,14 +295,33 @@ module ActionView
         tag :input, html_options
       end
 
-      # Creates a submit button with the text <tt>value</tt> as the caption. If options contains a pair with the key of <tt>:disable_with</tt>,
-      # then the value will be used to rename a disabled version of the submit button.
-      #
-      # Options:
-      # * <tt>:disable_with</tt> - When specified the button will be disabled when clicked and the <tt>value</tt> will be replaced with the
-      # the string provided.
-      #     # Outputs <input name="commit" onclick="this.disabled=true;this.value='Saving...';this.form.submit();" type="submit" value="Send" />
-      #     <%= submit_tag 'Send', :disable_with => 'Saving...' %>
+      # Creates a submit button with the text <tt>value</tt> as the caption. 
+      #
+      # ==== Options
+      # * <tt>:disabled</tt> - If set to true, the user will not be able to use this input.
+      # * <tt>:disable_with</tt> - Value of this parameter will be used as the value for a disabled version 
+      #                            of the submit button when the form is submitted.
+      # * Any other key creates standard HTML options for the tag.
+      #
+      # ==== Examples
+      #   submit_tag
+      #   # => <input name="commit" type="submit" value="Save changes" />
+      #
+      #   submit_tag "Edit this article"
+      #   # => <input name="commit" type="submit" value="Edit this article" />
+      #
+      #   submit_tag "Save edits", :disabled => true
+      #   # => <input disabled="disabled" name="commit" type="submit" value="Save edits" />
+      #
+      #   submit_tag "Complete sale", :disable_with => "Please wait..."
+      #   # => <input name="commit" onclick="this.disabled=true;this.value='Please wait...';this.form.submit();" 
+      #   #    type="submit" value="Complete sale" />
+      #
+      #   submit_tag nil, :class => "form_submit"
+      #   # => <input class="form_submit" name="commit" type="submit" />
+      #
+      #   submit_tag "Edit", :disable_width => "Editing...", :class => 'edit-button'
+      #   # => <input class="edit-button" disable_width="Editing..." name="commit" type="submit" value="Edit" />
       def submit_tag(value = "Save changes", options = {})
         options.stringify_keys!
         
@@ -157,6 +343,23 @@ module ActionView
       # Displays an image which when clicked will submit the form.
       #
       # <tt>source</tt> is passed to AssetTagHelper#image_path
+      #
+      # ==== Options
+      # * <tt>:disabled</tt> - If set to true, the user will not be able to use this input.
+      # * Any other key creates standard HTML options for the tag.
+      #
+      # ==== Examples
+      #   image_submit_tag("login.png")
+      #   # => <input src="/images/login.png" type="image" />
+      #
+      #   image_submit_tag("purchase.png"), :disabled => true
+      #   # => <input disabled="disabled" src="/images/purchase.png" type="image" />
+      #
+      #   image_submit_tag("search.png"), :class => 'search-button'
+      #   # => <input class="search-button" src="/images/search.png" type="image" />
+      #
+      #   image_submit_tag("agree.png"), :disabled => true, :class => "agree-disagree-button"
+      #   # => <input class="agree-disagree-button" disabled="disabled" src="/images/agree.png" type="image" />
       def image_submit_tag(source, options = {})
         tag :input, { "type" => "image", "src" => image_path(source) }.update(options.stringify_keys)
       end