actionpack 1.13.6 → 2.0.0

data/lib/action_view/helpers/form_options_helper.rb

@@ -1,6 +1,6 @@
 require 'cgi'
 require 'erb'
-require File.dirname(__FILE__) + '/form_helper'
+require 'action_view/helpers/form_helper'
 
 module ActionView
   module Helpers
@@ -10,7 +10,9 @@ module ActionView
     # and <tt>time_zone_select</tt> methods take an <tt>options</tt> parameter,
     # a hash.
     #
-    # * <tt>:include_blank</tt> - set to true if the first option element of the select element is a blank. Useful if there is not a default value required for the select element. For example,
+    # * <tt>:include_blank</tt> - set to true or a prompt string if the first option element of the select element is a blank. Useful if there is not a default value required for the select element.
+    #
+    # For example,
     #
     #   select("post", "category", Post::CATEGORIES, {:include_blank => true})
     #
@@ -22,15 +24,31 @@ module ActionView
     #     <option>poem</option>
     #   </select>
     #
+    # Another common case is a select tag for an <tt>belongs_to</tt>-associated object.
+    #
+    # Example with @post.person_id => 2:
+    #
+    #   select("post", "person_id", Person.find(:all).collect {|p| [ p.name, p.id ] }, {:include_blank => 'None'})
+    #
+    # could become:
+    #
+    #   <select name="post[person_id]">
+    #     <option value="">None</option>
+    #     <option value="1">David</option>
+    #     <option value="2" selected="selected">Sam</option>
+    #     <option value="3">Tobias</option>
+    #   </select>
+    #
     # * <tt>:prompt</tt> - set to true or a prompt string. When the select element doesn't have a value yet, this prepends an option with a generic prompt -- "Please select" -- or the given prompt string.
     #
-    # Another common case is a select tag for an <tt>belongs_to</tt>-associated object. For example,
+    # Example:
     #
-    #   select("post", "person_id", Person.find(:all).collect {|p| [ p.name, p.id ] })
+    #   select("post", "person_id", Person.find(:all).collect {|p| [ p.name, p.id ] }, {:prompt => 'Select Person'})
     #
     # could become:
     #
     #   <select name="post[person_id]">
+    #     <option value="">Select Person</option>
     #     <option value="1">David</option>
     #     <option value="2">Sam</option>
     #     <option value="3">Tobias</option>
@@ -48,7 +66,7 @@ module ActionView
       # could become:
       #
       #   <select name="post[person_id]">
-      #     <option></option>
+      #     <option value=""></option>
       #     <option value="1" selected="selected">David</option>
       #     <option value="2">Sam</option>
       #     <option value="3">Tobias</option>
@@ -66,7 +84,36 @@ module ActionView
         InstanceTag.new(object, method, self, nil, options.delete(:object)).to_select_tag(choices, options, html_options)
       end
 
-      # Return select and option tags for the given object and method using options_from_collection_for_select to generate the list of option tags.
+      # Returns <tt><select></tt> and <tt><option></tt> tags for the collection of existing return values of
+      # +method+ for +object+'s class. The value returned from calling +method+ on the instance +object+ will
+      # be selected. If calling +method+ returns +nil+, no selection is made without including <tt>:prompt</tt>
+      # or <tt>:include_blank</tt> in the +options+ hash.
+      #
+      # The <tt>:value_method</tt> and <tt>:text_method</tt> parameters are methods to be called on each member
+      # of +collection+. The return values are used as the +value+ attribute and contents of each
+      # <tt><option></tt> tag, respectively.
+      # 
+      # Example object structure for use with this method:
+      #   class Post < ActiveRecord::Base
+      #     belongs_to :author
+      #   end
+      #   class Author < ActiveRecord::Base
+      #     has_many :posts
+      #     def name_with_initial
+      #       "#{first_name.first}. #{last_name}"
+      #     end
+      #   end
+      #
+      # Sample usage (selecting the associated +Author+ for an instance of +Post+, <tt>@post</tt>):
+      #   collection_select(:post, :author_id, Author.find(:all), :id, :name_with_initial, {:prompt => true})
+      #
+      # If <tt>@post.author_id</tt> is already <tt>1</tt>, this would return:
+      #   <select name="post[author_id]">
+      #     <option value="">Please select</option>
+      #     <option value="1" selected="selected">D. Heinemeier Hansson</option>
+      #     <option value="2">D. Thomas</option>
+      #     <option value="3">M. Clark</option>
+      #   </select>
       def collection_select(object, method, collection, value_method, text_method, options = {}, html_options = {})
         InstanceTag.new(object, method, self, nil, options.delete(:object)).to_collection_select_tag(collection, value_method, text_method, options, html_options)
       end
@@ -112,17 +159,9 @@ module ActionView
         container = container.to_a if Hash === container
 
         options_for_select = container.inject([]) do |options, element|
-          if !element.is_a?(String) and element.respond_to?(:first) and element.respond_to?(:last)
-            is_selected = ( (selected.respond_to?(:include?) && !selected.is_a?(String) ? selected.include?(element.last) : element.last == selected) )
-            if is_selected
-              options << "<option value=\"#{html_escape(element.last.to_s)}\" selected=\"selected\">#{html_escape(element.first.to_s)}</option>"
-            else
-              options << "<option value=\"#{html_escape(element.last.to_s)}\">#{html_escape(element.first.to_s)}</option>"
-            end
-          else
-            is_selected = ( (selected.respond_to?(:include?) && !selected.is_a?(String) ? selected.include?(element) : element == selected) )
-            options << ((is_selected) ? "<option value=\"#{html_escape(element.to_s)}\" selected=\"selected\">#{html_escape(element.to_s)}</option>" : "<option value=\"#{html_escape(element.to_s)}\">#{html_escape(element.to_s)}</option>")
-          end
+          text, value = option_text_and_value(element)
+          selected_attribute = ' selected="selected"' if option_value_selected?(value, selected)
+          options << %(<option value="#{html_escape(value.to_s)}"#{selected_attribute}>#{html_escape(text.to_s)}</option>)
         end
 
         options_for_select.join("\n")
@@ -130,55 +169,68 @@ module ActionView
 
       # Returns a string of option tags that have been compiled by iterating over the +collection+ and assigning the
       # the result of a call to the +value_method+ as the option value and the +text_method+ as the option text.
-      # If +selected_value+ is specified, the element returning a match on +value_method+ will get the selected option tag.
+      # If +selected+ is specified, the element returning a match on +value_method+ will get the selected option tag.
       #
       # Example (call, result). Imagine a loop iterating over each +person+ in <tt>@project.people</tt> to generate an input tag:
       #   options_from_collection_for_select(@project.people, "id", "name")
       #     <option value="#{person.id}">#{person.name}</option>
       #
       # NOTE: Only the option tags are returned, you have to wrap this call in a regular HTML select tag.
-      def options_from_collection_for_select(collection, value_method, text_method, selected_value = nil)
-        options_for_select(
-          collection.inject([]) { |options, object| options << [ object.send(text_method), object.send(value_method) ] },
-          selected_value
-        )
+      def options_from_collection_for_select(collection, value_method, text_method, selected = nil)
+        options = collection.map do |element|
+          [element.send(text_method), element.send(value_method)]
+        end
+        options_for_select(options, selected)
       end
 
-      # Returns a string of option tags, like options_from_collection_for_select, but surrounds them with <optgroup> tags.
+      # Returns a string of <tt><option></tt> tags, like <tt>#options_from_collection_for_select</tt>, but
+      # groups them by <tt><optgroup></tt> tags based on the object relationships of the arguments.
       #
-      # An array of group objects are passed. Each group should return an array of options when calling group_method
-      # Each group should return its name when calling group_label_method.
+      # Parameters:
+      # +collection+::          An array of objects representing the <tt><optgroup></tt> tags
+      # +group_method+::        The name of a method which, when called on a member of +collection+, returns an
+      #                         array of child objects representing the <tt><option></tt> tags
+      # +group_label_method+::  The name of a method which, when called on a member of +collection+, returns a
+      #                         string to be used as the +label+ attribute for its <tt><optgroup></tt> tag
+      # +option_key_method+::   The name of a method which, when called on a child object of a member of
+      #                         +collection+, returns a value to be used as the +value+ attribute for its
+      #                         <tt><option></tt> tag
+      # +option_value_method+:: The name of a method which, when called on a child object of a member of
+      #                         +collection+, returns a value to be used as the contents of its
+      #                         <tt><option></tt> tag
+      # +selected_key+::        A value equal to the +value+ attribute for one of the <tt><option></tt> tags,
+      #                         which will have the +selected+ attribute set. Corresponds to the return value
+      #                         of one of the calls to +option_key_method+. If +nil+, no selection is made.
       #
-      # html_option_groups_from_collection(@continents, "countries", "continent_name", "country_id", "country_name", @selected_country.id)
+      # Example object structure for use with this method:
+      #   class Continent < ActiveRecord::Base
+      #     has_many :countries
+      #     # attribs: id, name
+      #   end
+      #   class Country < ActiveRecord::Base
+      #     belongs_to :continent
+      #     # attribs: id, name, continent_id
+      #   end
       #
-      # Could become:
-      #  <optgroup label="Africa">
-      #   <select>Egypt</select>
-      #   <select>Rwanda</select>
-      #   ...
-      #  </optgroup>
-      #  <optgroup label="Asia">
-      #   <select>China</select>
-      #   <select>India</select>
-      #   <select>Japan</select>
-      #   ...
-      #  </optgroup>
+      # Sample usage:
+      #   option_groups_from_collection_for_select(@continents, :countries, :name, :id, :name, 3)
       #
-      # with objects of the following classes:
-      # class Continent
-      #   def initialize(p_name, p_countries) @continent_name = p_name; @countries = p_countries; end
-      #   def continent_name() @continent_name; end
-      #   def countries() @countries; end
-      # end
-      # class Country
-      #   def initialize(id, name) @id = id; @name = name end
-      #   def country_id() @id; end
-      #   def country_name() @name; end
-      # end
+      # Possible output:
+      #   <optgroup label="Africa">
+      #     <option value="1">Egypt</option>
+      #     <option value="4">Rwanda</option>
+      #     ...
+      #   </optgroup>
+      #   <optgroup label="Asia">
+      #     <option value="3" selected="selected">China</option>
+      #     <option value="12">India</option>
+      #     <option value="5">Japan</option>
+      #     ...
+      #   </optgroup>
       #
-      # NOTE: Only the option tags are returned, you have to wrap this call in a regular HTML select tag.
-      def option_groups_from_collection_for_select(collection, group_method, group_label_method,
-            option_key_method, option_value_method, selected_key = nil)
+      # <b>Note:</b> Only the <tt><optgroup></tt> and <tt><option></tt> tags are returned, so you still have to
+      # wrap the output in an appropriate <tt><select></tt> tag.
+      def option_groups_from_collection_for_select(collection, group_method, group_label_method, option_key_method, option_value_method, selected_key = nil)
         collection.inject("") do |options_for_select, group|
           group_label_string = eval("group.#{group_label_method}")
           options_for_select += "<optgroup label=\"#{html_escape(group_label_string)}\">"
@@ -197,16 +249,10 @@ module ActionView
 
         if priority_countries
           country_options += options_for_select(priority_countries, selected)
-          country_options += "<option value=\"\">-------------</option>\n"
-        end
-
-        if priority_countries && priority_countries.include?(selected)
-          country_options += options_for_select(COUNTRIES - priority_countries, selected)
-        else
-          country_options += options_for_select(COUNTRIES, selected)
+          country_options += "<option value=\"\" disabled=\"disabled\">-------------</option>\n"
         end
 
-        return country_options
+        return country_options + options_for_select(COUNTRIES, selected)
       end
 
       # Returns a string of option tags for pretty much any time zone in the
@@ -234,7 +280,7 @@ module ActionView
 
         if priority_zones
           zone_options += options_for_select(convert_zones[priority_zones], selected)
-          zone_options += "<option value=\"\">-------------</option>\n"
+          zone_options += "<option value=\"\" disabled=\"disabled\">-------------</option>\n"
 
           zones = zones.reject { |z| priority_zones.include?( z ) }
         end
@@ -244,51 +290,61 @@ module ActionView
       end
 
       private
+        def option_text_and_value(option)
+          # Options are [text, value] pairs or strings used for both.
+          if !option.is_a?(String) and option.respond_to?(:first) and option.respond_to?(:last)
+            [option.first, option.last]
+          else
+            [option, option]
+          end
+        end
+
+        def option_value_selected?(value, selected)
+          if selected.respond_to?(:include?) && !selected.is_a?(String)
+            selected.include? value
+          else
+            value == selected
+          end
+        end
+
         # All the countries included in the country_options output.
-        COUNTRIES = [ "Afghanistan", "Albania", "Algeria", "American Samoa", "Andorra", "Angola", "Anguilla", 
-            "Antarctica", "Antigua And Barbuda", "Argentina", "Armenia", "Aruba", "Australia", 
-            "Austria", "Azerbaijan", "Bahamas", "Bahrain", "Bangladesh", "Barbados", "Belarus", 
-            "Belgium", "Belize", "Benin", "Bermuda", "Bhutan", "Bolivia", "Bosnia and Herzegowina", 
-            "Botswana", "Bouvet Island", "Brazil", "British Indian Ocean Territory", 
-            "Brunei Darussalam", "Bulgaria", "Burkina Faso", "Burma", "Burundi", "Cambodia", 
-            "Cameroon", "Canada", "Cape Verde", "Cayman Islands", "Central African Republic", 
-            "Chad", "Chile", "China", "Christmas Island", "Cocos (Keeling) Islands", "Colombia", 
-            "Comoros", "Congo", "Congo, the Democratic Republic of the", "Cook Islands", 
-            "Costa Rica", "Cote d'Ivoire", "Croatia", "Cuba", "Cyprus", "Czech Republic", "Denmark", 
-            "Djibouti", "Dominica", "Dominican Republic", "East Timor", "Ecuador", "Egypt", 
-            "El Salvador", "England", "Equatorial Guinea", "Eritrea", "Espana", "Estonia", 
-            "Ethiopia", "Falkland Islands", "Faroe Islands", "Fiji", "Finland", "France", 
-            "French Guiana", "French Polynesia", "French Southern Territories", "Gabon", "Gambia", 
-            "Georgia", "Germany", "Ghana", "Gibraltar", "Great Britain", "Greece", "Greenland", 
-            "Grenada", "Guadeloupe", "Guam", "Guatemala", "Guinea", "Guinea-Bissau", "Guyana", 
-            "Haiti", "Heard and Mc Donald Islands", "Honduras", "Hong Kong", "Hungary", "Iceland", 
-            "India", "Indonesia", "Ireland", "Israel", "Italy", "Iran", "Iraq", "Jamaica", "Japan", "Jordan", 
-            "Kazakhstan", "Kenya", "Kiribati", "Korea, Republic of", "Korea (South)", "Kuwait", 
-            "Kyrgyzstan", "Lao People's Democratic Republic", "Latvia", "Lebanon", "Lesotho", 
-            "Liberia", "Liechtenstein", "Lithuania", "Luxembourg", "Macau", "Macedonia", 
-            "Madagascar", "Malawi", "Malaysia", "Maldives", "Mali", "Malta", "Marshall Islands", 
-            "Martinique", "Mauritania", "Mauritius", "Mayotte", "Mexico", 
-            "Micronesia, Federated States of", "Moldova, Republic of", "Monaco", "Mongolia", 
-            "Montserrat", "Morocco", "Mozambique", "Myanmar", "Namibia", "Nauru", "Nepal", 
-            "Netherlands", "Netherlands Antilles", "New Caledonia", "New Zealand", "Nicaragua", 
-            "Niger", "Nigeria", "Niue", "Norfolk Island", "Northern Ireland", 
-            "Northern Mariana Islands", "Norway", "Oman", "Pakistan", "Palau", "Panama", 
-            "Papua New Guinea", "Paraguay", "Peru", "Philippines", "Pitcairn", "Poland", 
-            "Portugal", "Puerto Rico", "Qatar", "Reunion", "Romania", "Russia", "Rwanda", 
-            "Saint Kitts and Nevis", "Saint Lucia", "Saint Vincent and the Grenadines", 
-            "Samoa (Independent)", "San Marino", "Sao Tome and Principe", "Saudi Arabia", 
-            "Scotland", "Senegal", "Serbia and Montenegro", "Seychelles", "Sierra Leone", "Singapore", 
-            "Slovakia", "Slovenia", "Solomon Islands", "Somalia", "South Africa", 
-            "South Georgia and the South Sandwich Islands", "South Korea", "Spain", "Sri Lanka", 
-            "St. Helena", "St. Pierre and Miquelon", "Suriname", "Svalbard and Jan Mayen Islands", 
-            "Swaziland", "Sweden", "Switzerland", "Taiwan", "Tajikistan", "Tanzania", "Thailand", 
-            "Togo", "Tokelau", "Tonga", "Trinidad", "Trinidad and Tobago", "Tunisia", "Turkey", 
-            "Turkmenistan", "Turks and Caicos Islands", "Tuvalu", "Uganda", "Ukraine", 
-            "United Arab Emirates", "United Kingdom", "United States", 
-            "United States Minor Outlying Islands", "Uruguay", "Uzbekistan", "Vanuatu", 
-            "Vatican City State (Holy See)", "Venezuela", "Viet Nam", "Virgin Islands (British)", 
-            "Virgin Islands (U.S.)", "Wales", "Wallis and Futuna Islands", "Western Sahara", 
-            "Yemen", "Zambia", "Zimbabwe" ] unless const_defined?("COUNTRIES")
+        COUNTRIES = ["Afghanistan", "Aland Islands", "Albania", "Algeria", "American Samoa", "Andorra", "Angola",
+          "Anguilla", "Antarctica", "Antigua And Barbuda", "Argentina", "Armenia", "Aruba", "Australia", "Austria",
+          "Azerbaijan", "Bahamas", "Bahrain", "Bangladesh", "Barbados", "Belarus", "Belgium", "Belize", "Benin",
+          "Bermuda", "Bhutan", "Bolivia", "Bosnia and Herzegowina", "Botswana", "Bouvet Island", "Brazil",
+          "British Indian Ocean Territory", "Brunei Darussalam", "Bulgaria", "Burkina Faso", "Burundi", "Cambodia",
+          "Cameroon", "Canada", "Cape Verde", "Cayman Islands", "Central African Republic", "Chad", "Chile", "China",
+          "Christmas Island", "Cocos (Keeling) Islands", "Colombia", "Comoros", "Congo",
+          "Congo, the Democratic Republic of the", "Cook Islands", "Costa Rica", "Cote d'Ivoire", "Croatia", "Cuba",
+          "Cyprus", "Czech Republic", "Denmark", "Djibouti", "Dominica", "Dominican Republic", "Ecuador", "Egypt",
+          "El Salvador", "Equatorial Guinea", "Eritrea", "Estonia", "Ethiopia", "Falkland Islands (Malvinas)",
+          "Faroe Islands", "Fiji", "Finland", "France", "French Guiana", "French Polynesia",
+          "French Southern Territories", "Gabon", "Gambia", "Georgia", "Germany", "Ghana", "Gibraltar", "Greece", "Greenland", "Grenada", "Guadeloupe", "Guam", "Guatemala", "Guernsey", "Guinea",
+          "Guinea-Bissau", "Guyana", "Haiti", "Heard and McDonald Islands", "Holy See (Vatican City State)",
+          "Honduras", "Hong Kong", "Hungary", "Iceland", "India", "Indonesia", "Iran, Islamic Republic of", "Iraq",
+          "Ireland", "Isle of Man", "Israel", "Italy", "Jamaica", "Japan", "Jersey", "Jordan", "Kazakhstan", "Kenya",
+          "Kiribati", "Korea, Democratic People's Republic of", "Korea, Republic of", "Kuwait", "Kyrgyzstan",
+          "Lao People's Democratic Republic", "Latvia", "Lebanon", "Lesotho", "Liberia", "Libyan Arab Jamahiriya",
+          "Liechtenstein", "Lithuania", "Luxembourg", "Macao", "Macedonia, The Former Yugoslav Republic Of",
+          "Madagascar", "Malawi", "Malaysia", "Maldives", "Mali", "Malta", "Marshall Islands", "Martinique",
+          "Mauritania", "Mauritius", "Mayotte", "Mexico", "Micronesia, Federated States of", "Moldova, Republic of",
+          "Monaco", "Mongolia", "Montenegro", "Montserrat", "Morocco", "Mozambique", "Myanmar", "Namibia", "Nauru",
+          "Nepal", "Netherlands", "Netherlands Antilles", "New Caledonia", "New Zealand", "Nicaragua", "Niger",
+          "Nigeria", "Niue", "Norfolk Island", "Northern Mariana Islands", "Norway", "Oman", "Pakistan", "Palau",
+          "Palestinian Territory, Occupied", "Panama", "Papua New Guinea", "Paraguay", "Peru", "Philippines",
+          "Pitcairn", "Poland", "Portugal", "Puerto Rico", "Qatar", "Reunion", "Romania", "Russian Federation",
+          "Rwanda", "Saint Barthelemy", "Saint Helena", "Saint Kitts and Nevis", "Saint Lucia",
+          "Saint Pierre and Miquelon", "Saint Vincent and the Grenadines", "Samoa", "San Marino",
+          "Sao Tome and Principe", "Saudi Arabia", "Senegal", "Serbia", "Seychelles", "Sierra Leone", "Singapore",
+          "Slovakia", "Slovenia", "Solomon Islands", "Somalia", "South Africa",
+          "South Georgia and the South Sandwich Islands", "Spain", "Sri Lanka", "Sudan", "Suriname",
+          "Svalbard and Jan Mayen", "Swaziland", "Sweden", "Switzerland", "Syrian Arab Republic",
+          "Taiwan, Province of China", "Tajikistan", "Tanzania, United Republic of", "Thailand", "Timor-Leste",
+          "Togo", "Tokelau", "Tonga", "Trinidad and Tobago", "Tunisia", "Turkey", "Turkmenistan",
+          "Turks and Caicos Islands", "Tuvalu", "Uganda", "Ukraine", "United Arab Emirates", "United Kingdom",
+          "United States", "United States Minor Outlying Islands", "Uruguay", "Uzbekistan", "Vanuatu", "Venezuela",
+          "Viet Nam", "Virgin Islands, British", "Virgin Islands, U.S.", "Wallis and Futuna", "Western Sahara",
+          "Yemen", "Zambia", "Zimbabwe"] unless const_defined?("COUNTRIES")
     end
 
     class InstanceTag #:nodoc:
@@ -315,7 +371,12 @@ module ActionView
         html_options = html_options.stringify_keys
         add_default_name_and_id(html_options)
         value = value(object)
-        content_tag("select", add_options(country_options_for_select(value, priority_countries), options, value), html_options)
+        content_tag("select",
+          add_options(
+            country_options_for_select(value, priority_countries),
+            options, value
+          ), html_options
+        )
       end
 
       def to_time_zone_select_tag(priority_zones, options, html_options)
@@ -332,8 +393,9 @@ module ActionView
 
       private
         def add_options(option_tags, options, value = nil)
-          option_tags = "<option value=\"\"></option>\n" + option_tags if options[:include_blank]
-
+          if options[:include_blank]
+            option_tags = "<option value=\"\">#{options[:include_blank] if options[:include_blank].kind_of?(String)}</option>\n" + option_tags
+          end
           if value.blank? && options[:prompt]
             ("<option value=\"\">#{options[:prompt].kind_of?(String) ? options[:prompt] : 'Please select'}</option>\n") + option_tags
           else

data/lib/action_view/helpers/form_tag_helper.rb

@@ -1,109 +1,142 @@
 require 'cgi'
-require File.dirname(__FILE__) + '/tag_helper'
+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 = options.stringify_keys
-        html_options["enctype"] = "multipart/form-data" if html_options.delete("multipart")
-        html_options["action"]  = url_for(url_for_options, *parameters_for_url)
-
-        method_tag = ""
-        
-        case method = html_options.delete("method").to_s
-          when /^get$/i # must be case-insentive, but can't use downcase as might be nil
-            html_options["method"] = "get"
-          when /^post$/i, "", nil
-            html_options["method"] = "post"
-          else
-            html_options["method"] = "post"
-            method_tag = content_tag(:div, tag(:input, :type => "hidden", :name => "_method", :value => method), :style => 'margin:0;padding:0')
-        end
-        
+        html_options = html_options_for_form(url_for_options, options, *parameters_for_url)
         if block_given?
-          content = capture(&block)
-          concat(tag(:form, html_options, true) + method_tag, block.binding)
-          concat(content, block.binding)
-          concat("</form>", block.binding)
+          form_tag_in_block(html_options, &block)
         else
-          tag(:form, html_options, true) + method_tag
+          form_tag_html(html_options)
         end
       end
 
-      alias_method :start_form_tag, :form_tag
-
-      # Outputs "</form>"
-      def end_form_tag
-        "</form>"
-      end
-      
-      deprecate :end_form_tag, :start_form_tag => :form_tag
-
       # 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.
       #
-      # <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>
+      # ==== 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.
+      #
+      # ==== 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.
       #
-      # Takes the same options as text_field_tag
+      # ==== Examples
+      #   hidden_field_tag 'tags_list'
+      #   # => <input id="tags_list" name="tags_list" type="hidden" />
+      #
+      #   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 %>
@@ -111,55 +144,197 @@ 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.
+      #
+      # ==== 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" />
       #
-      # Takes the same options as text_field_tag
+      #   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 (columns by rows) of the textarea (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!
 
         if size = options.delete("size")
-          options["cols"], options["rows"] = size.split("x")
+          options["cols"], options["rows"] = size.split("x") if size.respond_to?(:split)
         end
 
         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
-        html_options = { "type" => "radio", "name" => name, "id" => "#{name}_#{pretty_tag_value}", "value" => value }.update(options.stringify_keys)
+        pretty_name = name.to_s.gsub(/\[/, "_").gsub(/\]/, "")
+        html_options = { "type" => "radio", "name" => name, "id" => "#{pretty_name}_#{pretty_tag_value}", "value" => value }.update(options.stringify_keys)
         html_options["checked"] = "checked" if checked
         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 "disable_with",
-      # then the value will be used to rename a disabled version of the submit button.
+      # 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_with => "Editing...", :class => 'edit-button'
+      #   # => <input class="edit-button" disable_with="Editing..." name="commit" type="submit" value="Edit" />
       def submit_tag(value = "Save changes", options = {})
         options.stringify_keys!
         
         if disable_with = options.delete("disable_with")
-          options["onclick"] = "this.disabled=true;this.value='#{disable_with}';this.form.submit();#{options["onclick"]}"
+          options["onclick"] = [
+            "this.setAttribute('originalValue', this.value)",
+            "this.disabled=true",
+            "this.value='#{disable_with}'",
+            "#{options["onclick"]}",
+            "result = (this.form.onsubmit ? (this.form.onsubmit() ? this.form.submit() : false) : this.form.submit())",
+            "if (result == false) { this.value = this.getAttribute('originalValue'); this.disabled = false }",
+            "return result",
+          ].join(";")
         end
           
         tag :input, { "type" => "submit", "name" => "commit", "value" => value }.update(options.stringify_keys)
@@ -168,9 +343,90 @@ 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)
+        tag :input, { "type" => "image", "src" => path_to_image(source) }.update(options.stringify_keys)
+      end
+
+      # Creates a field set for grouping HTML form elements.
+      #
+      # <tt>legend</tt> will become the fieldset's title (optional as per W3C).
+      #
+      # === Examples
+      #   <% field_set_tag do %>
+      #     <p><%= text_field_tag 'name' %></p>
+      #   <% end %>
+      #   # => <fieldset><p><input id="name" name="name" type="text" /></p></fieldset>
+      #
+      #   <% field_set_tag 'Your details' do %>
+      #     <p><%= text_field_tag 'name' %></p>
+      #   <% end %>
+      #   # => <fieldset><legend>Your details</legend><p><input id="name" name="name" type="text" /></p></fieldset>
+      def field_set_tag(legend = nil, &block)
+        content = capture(&block)
+        concat(tag(:fieldset, {}, true), block.binding)
+        concat(content_tag(:legend, legend), block.binding) unless legend.blank?
+        concat(content, block.binding)
+        concat("</fieldset>", block.binding)
       end
+      
+      private
+        def html_options_for_form(url_for_options, options, *parameters_for_url)
+          returning options.stringify_keys do |html_options|
+            html_options["enctype"] = "multipart/form-data" if html_options.delete("multipart")
+            html_options["action"]  = url_for(url_for_options, *parameters_for_url)
+          end
+        end
+        
+        def extra_tags_for_form(html_options)
+          case method = html_options.delete("method").to_s
+            when /^get$/i # must be case-insentive, but can't use downcase as might be nil
+              html_options["method"] = "get"
+              ''
+            when /^post$/i, "", nil
+              html_options["method"] = "post"
+              protect_against_forgery? ? content_tag(:div, token_tag, :style => 'margin:0;padding:0') : ''
+            else
+              html_options["method"] = "post"
+              content_tag(:div, tag(:input, :type => "hidden", :name => "_method", :value => method) + token_tag, :style => 'margin:0;padding:0')
+          end
+        end
+        
+        def form_tag_html(html_options)
+          extra_tags = extra_tags_for_form(html_options)
+          tag(:form, html_options, true) + extra_tags
+        end
+        
+        def form_tag_in_block(html_options, &block)
+          content = capture(&block)
+          concat(form_tag_html(html_options), block.binding)
+          concat(content, block.binding)
+          concat("</form>", block.binding)
+        end
+
+        def token_tag
+          unless protect_against_forgery?
+            ''
+          else
+            tag(:input, :type => "hidden", :name => request_forgery_protection_token.to_s, :value => form_authenticity_token)
+          end
+        end
     end
   end
 end