actionpack 3.2.22.5 → 4.0.0.beta1

data/lib/action_view/helpers/form_options_helper.rb

@@ -1,21 +1,20 @@
 require 'cgi'
 require 'erb'
 require 'action_view/helpers/form_helper'
-require 'active_support/core_ext/object/blank'
 require 'active_support/core_ext/string/output_safety'
+require 'active_support/core_ext/array/extract_options'
+require 'active_support/core_ext/array/wrap'
 
 module ActionView
   # = Action View Form Option Helpers
   module Helpers
     # Provides a number of methods for turning different kinds of containers into a set of option tags.
-    # == Options
+    #
     # The <tt>collection_select</tt>, <tt>select</tt> and <tt>time_zone_select</tt> methods take an <tt>options</tt> parameter, a hash:
     #
     # * <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})
+    #   select("post", "category", Post::CATEGORIES, {include_blank: true})
     #
     # could become:
     #
@@ -25,11 +24,11 @@ module ActionView
     #     <option>poem</option>
     #   </select>
     #
-    # Another common case is a select tag for an <tt>belongs_to</tt>-associated object.
+    # Another common case is a select tag for a <tt>belongs_to</tt>-associated object.
     #
     # Example with @post.person_id => 2:
     #
-    #   select("post", "person_id", Person.all.collect {|p| [ p.name, p.id ] }, {:include_blank => 'None'})
+    #   select("post", "person_id", Person.all.collect {|p| [ p.name, p.id ] }, {include_blank: 'None'})
     #
     # could become:
     #
@@ -42,9 +41,7 @@ module ActionView
     #
     # * <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.
     #
-    # Example:
-    #
-    #   select("post", "person_id", Person.all.collect {|p| [ p.name, p.id ] }, {:prompt => 'Select Person'})
+    #   select("post", "person_id", Person.all.collect {|p| [ p.name, p.id ] }, {prompt: 'Select Person'})
     #
     # could become:
     #
@@ -58,9 +55,7 @@ module ActionView
     # Like the other form helpers, +select+ can accept an <tt>:index</tt> option to manually set the ID used in the resulting output. Unlike other helpers, +select+ expects this
     # option to be in the +html_options+ parameter.
     #
-    # Example:
-    #
-    #   select("album[]", "genre", %w[rap rock country], {}, { :index => nil })
+    #   select("album[]", "genre", %w[rap rock country], {}, { index: nil })
     #
     # becomes:
     #
@@ -72,9 +67,7 @@ module ActionView
     #
     # * <tt>:disabled</tt> - can be a single value or an array of values that will be disabled options in the final output.
     #
-    # Example:
-    #
-    #   select("post", "category", Post::CATEGORIES, {:disabled => 'restricted'})
+    #   select("post", "category", Post::CATEGORIES, {disabled: 'restricted'})
     #
     # could become:
     #
@@ -87,9 +80,7 @@ module ActionView
     #
     # When used with the <tt>collection_select</tt> helper, <tt>:disabled</tt> can also be a Proc that identifies those options that should be disabled.
     #
-    # Example:
-    #
-    #   collection_select(:post, :category_id, Category.all, :id, :name, {:disabled => lambda{|category| category.archived? }})
+    #   collection_select(:post, :category_id, Category.all, :id, :name, {disabled: lambda{|category| category.archived? }})
     #
     # If the categories "2008 stuff" and "Christmas" return true when the method <tt>archived?</tt> is called, this would return:
     #   <select name="post[category_id]">
@@ -111,7 +102,7 @@ module ActionView
       #   * A nested collection: see grouped_options_for_select
       #
       # Example with @post.person_id => 1:
-      #   select("post", "person_id", Person.all.collect {|p| [ p.name, p.id ] }, { :include_blank => true })
+      #   select("post", "person_id", Person.all.collect {|p| [ p.name, p.id ] }, { include_blank: true })
       #
       # could become:
       #
@@ -128,8 +119,8 @@ module ActionView
       # This allows the user to submit a form page more than once with the expected results of creating multiple records.
       # In addition, this allows a single partial to be used to generate form inputs for both edit and create forms.
       #
-      # By default, <tt>post.person_id</tt> is the selected option. Specify <tt>:selected => value</tt> to use a different selection
-      # or <tt>:selected => nil</tt> to leave all options unselected. Similarly, you can specify values to be disabled in the option
+      # By default, <tt>post.person_id</tt> is the selected option. Specify <tt>selected: value</tt> to use a different selection
+      # or <tt>selected: nil</tt> to leave all options unselected. Similarly, you can specify values to be disabled in the option
       # tags by specifying the <tt>:disabled</tt> option. This can either be a single value or an array of values to be disabled.
       #
       # ==== Gotcha
@@ -140,7 +131,7 @@ module ActionView
       # the user deselects all roles from +role_ids+ multiple select box, no +role_ids+ parameter is sent. So,
       # any mass-assignment idiom like
       #
-      #   @user.update_attributes(params[:user])
+      #   @user.update(params[:user])
       #
       # wouldn't update roles.
       #
@@ -153,8 +144,11 @@ module ActionView
       # form, and parameters extraction gets the last occurrence of any repeated
       # key in the query string, that works for ordinary forms.
       #
+      # In case if you don't want the helper to generate this hidden field you can specify
+      # <tt>include_hidden: false</tt> option.
+      #
       def select(object, method, choices, options = {}, html_options = {})
-        InstanceTag.new(object, method, self, options.delete(:object)).to_select_tag(choices, options, html_options)
+        Tags::Select.new(object, method, self, choices, options, html_options).render
       end
 
       # Returns <tt><select></tt> and <tt><option></tt> tags for the collection of existing return values of
@@ -164,12 +158,16 @@ module ActionView
       #
       # 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.
+      # <tt><option></tt> tag, respectively. They can also be any object that responds to +call+, such
+      # as a +proc+, that will be called for each member of the +collection+ to
+      # retrieve the value/text.
       #
       # 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
@@ -178,7 +176,8 @@ module ActionView
       #   end
       #
       # Sample usage (selecting the associated Author for an instance of Post, <tt>@post</tt>):
-      #   collection_select(:post, :author_id, Author.all, :id, :name_with_initial, :prompt => true)
+      #
+      #   collection_select(:post, :author_id, Author.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]">
@@ -188,10 +187,9 @@ module ActionView
       #     <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, options.delete(:object)).to_collection_select_tag(collection, value_method, text_method, options, html_options)
+        Tags::CollectionSelect.new(object, method, self, collection, value_method, text_method, options, html_options).render
       end
 
-
       # Returns <tt><select></tt>, <tt><optgroup></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>
@@ -211,23 +209,28 @@ module ActionView
       #   +collection+, returns a value to be used as the contents of its <tt><option></tt> tag.
       #
       # 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
+      #
       #   class City < ActiveRecord::Base
       #     belongs_to :country
       #     # attribs: id, name, country_id
       #   end
       #
       # Sample usage:
+      #
       #   grouped_collection_select(:city, :country_id, @continents, :countries, :name, :id, :name)
       #
       # Possible output:
+      #
       #   <select name="city[country_id]">
       #     <optgroup label="Africa">
       #       <option value="1">South Africa</option>
@@ -240,7 +243,7 @@ module ActionView
       #   </select>
       #
       def grouped_collection_select(object, method, collection, group_method, group_label_method, option_key_method, option_value_method, options = {}, html_options = {})
-        InstanceTag.new(object, method, self, options.delete(:object)).to_grouped_collection_select_tag(collection, group_method, group_label_method, option_key_method, option_value_method, options, html_options)
+        Tags::GroupedCollectionSelect.new(object, method, self, collection, group_method, group_label_method, option_key_method, option_value_method, options, html_options).render
       end
 
       # Return select and option tags for the given object and method, using
@@ -261,20 +264,19 @@ module ActionView
       # Finally, this method supports a <tt>:default</tt> option, which selects
       # a default ActiveSupport::TimeZone if the object's time zone is +nil+.
       #
-      # Examples:
-      #   time_zone_select( "user", "time_zone", nil, :include_blank => true)
+      #   time_zone_select( "user", "time_zone", nil, include_blank: true)
       #
-      #   time_zone_select( "user", "time_zone", nil, :default => "Pacific Time (US & Canada)" )
+      #   time_zone_select( "user", "time_zone", nil, default: "Pacific Time (US & Canada)" )
       #
-      #   time_zone_select( "user", 'time_zone', ActiveSupport::TimeZone.us_zones, :default => "Pacific Time (US & Canada)")
+      #   time_zone_select( "user", 'time_zone', ActiveSupport::TimeZone.us_zones, default: "Pacific Time (US & Canada)")
       #
       #   time_zone_select( "user", 'time_zone', [ ActiveSupport::TimeZone['Alaska'], ActiveSupport::TimeZone['Hawaii'] ])
       #
       #   time_zone_select( "user", 'time_zone', /Australia/)
       #
-      #   time_zone_select( "user", "time_zone", ActiveSupport::TimeZone.all.sort, :model => ActiveSupport::TimeZone)
+      #   time_zone_select( "user", "time_zone", ActiveSupport::TimeZone.all.sort, model: ActiveSupport::TimeZone)
       def time_zone_select(object, method, priority_zones = nil, options = {}, html_options = {})
-        InstanceTag.new(object, method, self,  options.delete(:object)).to_time_zone_select_tag(priority_zones, options, html_options)
+        Tags::TimeZoneSelect.new(object, method, self, priority_zones, options, html_options).render
       end
 
       # Accepts a container (hash, array, enumerable, your type) and returns a string of option tags. Given a container
@@ -283,67 +285,83 @@ module ActionView
       # become lasts. If +selected+ is specified, the matching "last" or element will get the selected option-tag. +selected+
       # may also be an array of values to be selected when using a multiple select.
       #
-      # Examples (call, result):
       #   options_for_select([["Dollar", "$"], ["Kroner", "DKK"]])
-      #     <option value="$">Dollar</option>\n<option value="DKK">Kroner</option>
+      #   # => <option value="$">Dollar</option>
+      #   # => <option value="DKK">Kroner</option>
       #
       #   options_for_select([ "VISA", "MasterCard" ], "MasterCard")
-      #     <option>VISA</option>\n<option selected="selected">MasterCard</option>
+      #   # => <option>VISA</option>
+      #   # => <option selected="selected">MasterCard</option>
       #
       #   options_for_select({ "Basic" => "$20", "Plus" => "$40" }, "$40")
-      #     <option value="$20">Basic</option>\n<option value="$40" selected="selected">Plus</option>
+      #   # => <option value="$20">Basic</option>
+      #   # => <option value="$40" selected="selected">Plus</option>
       #
       #   options_for_select([ "VISA", "MasterCard", "Discover" ], ["VISA", "Discover"])
-      #     <option selected="selected">VISA</option>\n<option>MasterCard</option>\n<option selected="selected">Discover</option>
+      #   # => <option selected="selected">VISA</option>
+      #   # => <option>MasterCard</option>
+      #   # => <option selected="selected">Discover</option>
       #
       # You can optionally provide html attributes as the last element of the array.
       #
-      # Examples:
-      #   options_for_select([ "Denmark", ["USA", {:class => 'bold'}], "Sweden" ], ["USA", "Sweden"])
-      #     <option value="Denmark">Denmark</option>\n<option value="USA" class="bold" selected="selected">USA</option>\n<option value="Sweden" selected="selected">Sweden</option>
+      #   options_for_select([ "Denmark", ["USA", {class: 'bold'}], "Sweden" ], ["USA", "Sweden"])
+      #   # => <option value="Denmark">Denmark</option>
+      #   # => <option value="USA" class="bold" selected="selected">USA</option>
+      #   # => <option value="Sweden" selected="selected">Sweden</option>
       #
-      #   options_for_select([["Dollar", "$", {:class => "bold"}], ["Kroner", "DKK", {:onclick => "alert('HI');"}]])
-      #     <option value="$" class="bold">Dollar</option>\n<option value="DKK" onclick="alert('HI');">Kroner</option>
+      #   options_for_select([["Dollar", "$", {class: "bold"}], ["Kroner", "DKK", {onclick: "alert('HI');"}]])
+      #   # => <option value="$" class="bold">Dollar</option>
+      #   # => <option value="DKK" onclick="alert('HI');">Kroner</option>
       #
       # If you wish to specify disabled option tags, set +selected+ to be a hash, with <tt>:disabled</tt> being either a value
       # or array of values to be disabled. In this case, you can use <tt>:selected</tt> to specify selected option tags.
       #
-      # Examples:
-      #   options_for_select(["Free", "Basic", "Advanced", "Super Platinum"], :disabled => "Super Platinum")
-      #     <option value="Free">Free</option>\n<option value="Basic">Basic</option>\n<option value="Advanced">Advanced</option>\n<option value="Super Platinum" disabled="disabled">Super Platinum</option>
+      #   options_for_select(["Free", "Basic", "Advanced", "Super Platinum"], disabled: "Super Platinum")
+      #   # => <option value="Free">Free</option>
+      #   # => <option value="Basic">Basic</option>
+      #   # => <option value="Advanced">Advanced</option>
+      #   # => <option value="Super Platinum" disabled="disabled">Super Platinum</option>
       #
-      #   options_for_select(["Free", "Basic", "Advanced", "Super Platinum"], :disabled => ["Advanced", "Super Platinum"])
-      #     <option value="Free">Free</option>\n<option value="Basic">Basic</option>\n<option value="Advanced" disabled="disabled">Advanced</option>\n<option value="Super Platinum" disabled="disabled">Super Platinum</option>
+      #   options_for_select(["Free", "Basic", "Advanced", "Super Platinum"], disabled: ["Advanced", "Super Platinum"])
+      #   # => <option value="Free">Free</option>
+      #   # => <option value="Basic">Basic</option>
+      #   # => <option value="Advanced" disabled="disabled">Advanced</option>
+      #   # => <option value="Super Platinum" disabled="disabled">Super Platinum</option>
       #
-      #   options_for_select(["Free", "Basic", "Advanced", "Super Platinum"], :selected => "Free", :disabled => "Super Platinum")
-      #     <option value="Free" selected="selected">Free</option>\n<option value="Basic">Basic</option>\n<option value="Advanced">Advanced</option>\n<option value="Super Platinum" disabled="disabled">Super Platinum</option>
+      #   options_for_select(["Free", "Basic", "Advanced", "Super Platinum"], selected: "Free", disabled: "Super Platinum")
+      #   # => <option value="Free" selected="selected">Free</option>
+      #   # => <option value="Basic">Basic</option>
+      #   # => <option value="Advanced">Advanced</option>
+      #   # => <option value="Super Platinum" disabled="disabled">Super Platinum</option>
       #
       # NOTE: Only the option tags are returned, you have to wrap this call in a regular HTML select tag.
       def options_for_select(container, selected = nil)
         return container if String === container
 
-        selected, disabled = extract_selected_and_disabled(selected).map do | r |
-           Array.wrap(r).map { |item| item.to_s }
+        selected, disabled = extract_selected_and_disabled(selected).map do |r|
+          Array(r).map { |item| item.to_s }
         end
 
         container.map do |element|
           html_attributes = option_html_attributes(element)
           text, value = option_text_and_value(element).map { |item| item.to_s }
-          selected_attribute = ' selected="selected"' if option_value_selected?(value, selected)
-          disabled_attribute = ' disabled="disabled"' if disabled && option_value_selected?(value, disabled)
-          %(<option value="#{ERB::Util.html_escape(value)}"#{selected_attribute}#{disabled_attribute}#{html_attributes}>#{ERB::Util.html_escape(text)}</option>)
-        end.join("\n").html_safe
 
+          html_attributes[:selected] = 'selected' if option_value_selected?(value, selected)
+          html_attributes[:disabled] = 'disabled' if disabled && option_value_selected?(value, disabled)
+          html_attributes[:value] = value
+
+          content_tag_string(:option, text, html_attributes)
+        end.join("\n").html_safe
       end
 
       # Returns a string of option tags that have been compiled by iterating over the +collection+ and assigning
       # the result of a call to the +value_method+ as the option value and the +text_method+ as the option text.
-      # Example:
+      #
       #   options_from_collection_for_select(@people, 'id', 'name')
-      # This will output the same HTML as if you did this:
-      #   <option value="#{person.id}">#{person.name}</option>
+      #   # => <option value="#{person.id}">#{person.name}</option>
       #
       # This is more often than not used inside a #select_tag like this example:
+      #
       #   select_tag 'person', options_from_collection_for_select(@people, 'id', 'name')
       #
       # If +selected+ is specified as a value or array of values, the element(s) returning a match on +value_method+
@@ -362,12 +380,13 @@ module ActionView
       # should produce the desired results.
       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)]
+          [value_for_collection(element, text_method), value_for_collection(element, value_method)]
         end
         selected, disabled = extract_selected_and_disabled(selected)
-        select_deselect = {}
-        select_deselect[:selected] = extract_values_from_collection(collection, value_method, selected)
-        select_deselect[:disabled] = extract_values_from_collection(collection, value_method, disabled)
+        select_deselect = {
+          :selected => extract_values_from_collection(collection, value_method, selected),
+          :disabled => extract_values_from_collection(collection, value_method, disabled)
+        }
 
         options_for_select(options, select_deselect)
       end
@@ -391,10 +410,12 @@ module ActionView
       #   to be specified.
       #
       # 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
@@ -420,10 +441,10 @@ module ActionView
       # 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.map do |group|
-          group_label_string = eval("group.#{group_label_method}")
-          "<optgroup label=\"#{ERB::Util.html_escape(group_label_string)}\">" +
-            options_from_collection_for_select(eval("group.#{group_method}"), option_key_method, option_value_method, selected_key) +
-            '</optgroup>'
+          option_tags = options_from_collection_for_select(
+            group.send(group_method), option_key_method, option_value_method, selected_key)
+
+          content_tag(:optgroup, option_tags, :label => group.send(group_label_method))
         end.join.html_safe
       end
 
@@ -438,10 +459,12 @@ module ActionView
       # * +selected_key+ - A value equal to the +value+ attribute for one of the <tt><option></tt> tags,
       #   which will have the +selected+ attribute set. Note: It is possible for this value to match multiple options
       #   as you might have the same option in multiple groups. Each will then get <tt>selected="selected"</tt>.
-      # * +prompt+ - set to true or a prompt string. When the select element doesn't have a value yet, this
+      #
+      # Options:
+      # * <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.
+      # * <tt>:divider</tt> - the divider for the options groups.
       #
-      # Sample usage (Array):
       #   grouped_options = [
       #    ['North America',
       #      [['United States','US'],'Canada']],
@@ -450,37 +473,70 @@ module ActionView
       #   ]
       #   grouped_options_for_select(grouped_options)
       #
-      # Sample usage (Hash):
       #   grouped_options = {
-      #    'North America' => [['United States','US'], 'Canada'],
-      #    'Europe' => ['Denmark','Germany','France']
+      #     'North America' => [['United States','US'], 'Canada'],
+      #     'Europe' => ['Denmark','Germany','France']
       #   }
       #   grouped_options_for_select(grouped_options)
       #
       # Possible output:
+      #   <optgroup label="North America">
+      #     <option value="US">United States</option>
+      #     <option value="Canada">Canada</option>
+      #   </optgroup>
       #   <optgroup label="Europe">
       #     <option value="Denmark">Denmark</option>
       #     <option value="Germany">Germany</option>
       #     <option value="France">France</option>
       #   </optgroup>
-      #   <optgroup label="North America">
+      #
+      #   grouped_options = [
+      #     [['United States','US'], 'Canada'],
+      #     ['Denmark','Germany','France']
+      #   ]
+      #   grouped_options_for_select(grouped_options, nil, divider: '---------')
+      #
+      # Possible output:
+      #   <optgroup label="---------">
       #     <option value="US">United States</option>
       #     <option value="Canada">Canada</option>
       #   </optgroup>
+      #   <optgroup label="---------">
+      #     <option value="Denmark">Denmark</option>
+      #     <option value="Germany">Germany</option>
+      #     <option value="France">France</option>
+      #   </optgroup>
       #
       # <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 grouped_options_for_select(grouped_options, selected_key = nil, prompt = nil)
-        body = ''
-        body << content_tag(:option, prompt, { :value => "" }, true) if prompt
+      def grouped_options_for_select(grouped_options, selected_key = nil, options = {})
+        if options.is_a?(Hash)
+          prompt  = options[:prompt]
+          divider = options[:divider]
+        else
+          prompt  = options
+          options = {}
+          message = "Passing the prompt to grouped_options_for_select as an argument is deprecated. " \
+                    "Please use an options hash like `{ prompt: #{prompt.inspect} }`."
+          ActiveSupport::Deprecation.warn message
+        end
 
-        grouped_options = grouped_options.sort if grouped_options.is_a?(Hash)
+        body = "".html_safe
 
-        grouped_options.each do |group|
-          body << content_tag(:optgroup, options_for_select(group[1], selected_key), :label => group[0])
+        if prompt
+          body.safe_concat content_tag(:option, prompt_text(prompt), :value => "")
         end
 
-        body.html_safe
+        grouped_options.each do |container|
+          if divider
+            label = divider
+          else
+            label, container = container
+          end
+          body.safe_concat content_tag(:optgroup, options_for_select(container, selected_key), :label => label)
+        end
+
+        body
       end
 
       # Returns a string of option tags for pretty much any time zone in the
@@ -502,42 +558,164 @@ module ActionView
       # NOTE: Only the option tags are returned, you have to wrap this call in
       # a regular HTML select tag.
       def time_zone_options_for_select(selected = nil, priority_zones = nil, model = ::ActiveSupport::TimeZone)
-        zone_options = ""
+        zone_options = "".html_safe
 
         zones = model.all
         convert_zones = lambda { |list| list.map { |z| [ z.to_s, z.name ] } }
 
         if priority_zones
           if priority_zones.is_a?(Regexp)
-            priority_zones = model.all.find_all {|z| z =~ priority_zones}
+            priority_zones = zones.grep(priority_zones)
           end
-          zone_options += options_for_select(convert_zones[priority_zones], selected)
-          zone_options += "<option value=\"\" disabled=\"disabled\">-------------</option>\n"
 
-          zones = zones.reject { |z| priority_zones.include?( z ) }
+          zone_options.safe_concat options_for_select(convert_zones[priority_zones], selected)
+          zone_options.safe_concat content_tag(:option, '-------------', :value => '', :disabled => 'disabled')
+          zone_options.safe_concat "\n"
+
+          zones = zones - priority_zones
         end
 
-        zone_options += options_for_select(convert_zones[zones], selected)
-        zone_options.html_safe
+        zone_options.safe_concat options_for_select(convert_zones[zones], selected)
+      end
+
+      # Returns radio button 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.
+      #
+      # 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 radio button tag,
+      # respectively. They can also be any object that responds to +call+, such
+      # as a +proc+, that will be called for each member of the +collection+ to
+      # retrieve the value/text.
+      #
+      # 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_radio_buttons(:post, :author_id, Author.all, :id, :name_with_initial)
+      #
+      # If <tt>@post.author_id</tt> is already <tt>1</tt>, this would return:
+      #   <input id="post_author_id_1" name="post[author_id]" type="radio" value="1" checked="checked" />
+      #   <label for="post_author_id_1">D. Heinemeier Hansson</label>
+      #   <input id="post_author_id_2" name="post[author_id]" type="radio" value="2" />
+      #   <label for="post_author_id_2">D. Thomas</label>
+      #   <input id="post_author_id_3" name="post[author_id]" type="radio" value="3" />
+      #   <label for="post_author_id_3">M. Clark</label>
+      #
+      # It is also possible to customize the way the elements will be shown by
+      # giving a block to the method:
+      #   collection_radio_buttons(:post, :author_id, Author.all, :id, :name_with_initial) do |b|
+      #     b.label { b.radio_button }
+      #   end
+      #
+      # The argument passed to the block is a special kind of builder for this
+      # collection, which has the ability to generate the label and radio button
+      # for the current item in the collection, with proper text and value.
+      # Using it, you can change the label and radio button display order or
+      # even use the label as wrapper, as in the example above.
+      #
+      # The builder methods <tt>label</tt> and <tt>radio_button</tt> also accept
+      # extra html options:
+      #   collection_radio_buttons(:post, :author_id, Author.all, :id, :name_with_initial) do |b|
+      #     b.label(class: "radio_button") { b.radio_button(class: "radio_button") }
+      #   end
+      #
+      # There are also three special methods available: <tt>object</tt>, <tt>text</tt> and
+      # <tt>value</tt>, which are the current item being rendered, its text and value methods,
+      # respectively. You can use them like this:
+      #   collection_radio_buttons(:post, :author_id, Author.all, :id, :name_with_initial) do |b|
+      #      b.label(:"data-value" => b.value) { b.radio_button + b.text }
+      #   end
+      def collection_radio_buttons(object, method, collection, value_method, text_method, options = {}, html_options = {}, &block)
+        Tags::CollectionRadioButtons.new(object, method, self, collection, value_method, text_method, options, html_options).render(&block)
+      end
+
+      # Returns check box 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.
+      #
+      # 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 check box tag,
+      # respectively. They can also be any object that responds to +call+, such
+      # as a +proc+, that will be called for each member of the +collection+ to
+      # retrieve the value/text.
+      #
+      # Example object structure for use with this method:
+      #   class Post < ActiveRecord::Base
+      #     has_and_belongs_to_many :author
+      #   end
+      #   class Author < ActiveRecord::Base
+      #     has_and_belongs_to_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_check_boxes(:post, :author_ids, Author.all, :id, :name_with_initial)
+      #
+      # If <tt>@post.author_ids</tt> is already <tt>[1]</tt>, this would return:
+      #   <input id="post_author_ids_1" name="post[author_ids][]" type="checkbox" value="1" checked="checked" />
+      #   <label for="post_author_ids_1">D. Heinemeier Hansson</label>
+      #   <input id="post_author_ids_2" name="post[author_ids][]" type="checkbox" value="2" />
+      #   <label for="post_author_ids_2">D. Thomas</label>
+      #   <input id="post_author_ids_3" name="post[author_ids][]" type="checkbox" value="3" />
+      #   <label for="post_author_ids_3">M. Clark</label>
+      #   <input name="post[author_ids][]" type="hidden" value="" />
+      #
+      # It is also possible to customize the way the elements will be shown by
+      # giving a block to the method:
+      #   collection_check_boxes(:post, :author_ids, Author.all, :id, :name_with_initial) do |b|
+      #     b.label { b.check_box }
+      #   end
+      #
+      # The argument passed to the block is a special kind of builder for this
+      # collection, which has the ability to generate the label and check box
+      # for the current item in the collection, with proper text and value.
+      # Using it, you can change the label and check box display order or even
+      # use the label as wrapper, as in the example above.
+      #
+      # The builder methods <tt>label</tt> and <tt>check_box</tt> also accept
+      # extra html options:
+      #   collection_check_boxes(:post, :author_ids, Author.all, :id, :name_with_initial) do |b|
+      #     b.label(class: "check_box") { b.check_box(class: "check_box") }
+      #   end
+      #
+      # There are also three special methods available: <tt>object</tt>, <tt>text</tt> and
+      # <tt>value</tt>, which are the current item being rendered, its text and value methods,
+      # respectively. You can use them like this:
+      #   collection_check_boxes(:post, :author_ids, Author.all, :id, :name_with_initial) do |b|
+      #      b.label(:"data-value" => b.value) { b.check_box + b.text }
+      #   end
+      def collection_check_boxes(object, method, collection, value_method, text_method, options = {}, html_options = {}, &block)
+        Tags::CollectionCheckBoxes.new(object, method, self, collection, value_method, text_method, options, html_options).render(&block)
       end
 
       private
         def option_html_attributes(element)
-          return "" unless Array === element
-          html_attributes = []
-          element.select { |e| Hash === e }.reduce({}, :merge).each do |k, v|
-            html_attributes << " #{k}=\"#{ERB::Util.html_escape(v.to_s)}\""
+          if Array === element
+            element.select { |e| Hash === e }.reduce({}, :merge!)
+          else
+            {}
           end
-          html_attributes.join
         end
 
         def option_text_and_value(option)
           # Options are [text, value] pairs or strings used for both.
-          case
-          when Array === option
-            option = option.reject { |e| Hash === e }
-            [option.first, option.last]
-          when !option.is_a?(String) && option.respond_to?(:first) && option.respond_to?(:last)
+          if !option.is_a?(String) && option.respond_to?(:first) && option.respond_to?(:last)
+            option = option.reject { |e| Hash === e } if Array === option
             [option.first, option.last]
           else
             [option, option]
@@ -545,20 +723,17 @@ module ActionView
         end
 
         def option_value_selected?(value, selected)
-          if selected.respond_to?(:include?) && !selected.is_a?(String)
-            selected.include? value
-          else
-            value == selected
-          end
+          Array(selected).include? value
         end
 
         def extract_selected_and_disabled(selected)
           if selected.is_a?(Proc)
-            [ selected, nil ]
+            [selected, nil]
           else
             selected = Array.wrap(selected)
             options = selected.extract_options!.symbolize_keys
-            [ options.include?(:selected) ? options[:selected] : selected, options[:disabled] ]
+            selected_items = options.fetch(:selected, selected)
+            [selected_items, options[:disabled]]
           end
         end
 
@@ -571,88 +746,88 @@ module ActionView
             selected
           end
         end
-    end
-
-    class InstanceTag #:nodoc:
-      include FormOptionsHelper
-
-      def to_select_tag(choices, options, html_options)
-        selected_value = options.has_key?(:selected) ? options[:selected] : value(object)
-        choices = choices.to_a if choices.is_a?(Range)
-
-        # Grouped choices look like this:
-        #
-        #   [nil, []]
-        #   { nil => [] }
-        #
-        if !choices.empty? && choices.first.respond_to?(:last) && Array === choices.first.last
-          option_tags = grouped_options_for_select(choices, :selected => selected_value, :disabled => options[:disabled])
-        else
-          option_tags = options_for_select(choices, :selected => selected_value, :disabled => options[:disabled])
-        end
-
-        select_content_tag(option_tags, options, html_options)
-      end
-
-      def to_collection_select_tag(collection, value_method, text_method, options, html_options)
-        selected_value = options.has_key?(:selected) ? options[:selected] : value(object)
-        select_content_tag(
-          options_from_collection_for_select(collection, value_method, text_method, :selected => selected_value, :disabled => options[:disabled]), options, html_options
-        )
-      end
-
-      def to_grouped_collection_select_tag(collection, group_method, group_label_method, option_key_method, option_value_method, options, html_options)
-        select_content_tag(
-          option_groups_from_collection_for_select(collection, group_method, group_label_method, option_key_method, option_value_method, value(object)), options, html_options
-        )
-      end
-
-      def to_time_zone_select_tag(priority_zones, options, html_options)
-        select_content_tag(
-            time_zone_options_for_select(value(object) || options[:default], priority_zones, options[:model] || ActiveSupport::TimeZone), options, html_options
-        )
-      end
 
-      private
-        def add_options(option_tags, options, value = nil)
-          if options[:include_blank]
-            option_tags = content_tag_string('option', options[:include_blank].kind_of?(String) ? options[:include_blank] : nil, :value => '') + "\n" + option_tags
-          end
-          if value.blank? && options[:prompt]
-            prompt = options[:prompt].kind_of?(String) ? options[:prompt] : I18n.translate('helpers.select.prompt', :default => 'Please select')
-            option_tags = content_tag_string('option', prompt, :value => '') + "\n" + option_tags
-          end
-          option_tags
+        def value_for_collection(item, value)
+          value.respond_to?(:call) ? value.call(item) : item.send(value)
         end
 
-        def select_content_tag(option_tags, options, html_options)
-          html_options = html_options.stringify_keys
-          add_default_name_and_id(html_options)
-          select = content_tag("select", add_options(option_tags, options, value(object)), html_options)
-          if html_options["multiple"]
-            tag("input", :disabled => html_options["disabled"], :name => html_options["name"], :type => "hidden", :value => "") + select
-          else
-            select
-          end
+        def prompt_text(prompt)
+          prompt = prompt.kind_of?(String) ? prompt : I18n.translate('helpers.select.prompt', :default => 'Please select')
         end
     end
 
     class FormBuilder
+      # Wraps ActionView::Helpers::FormOptionsHelper#select for form builders:
+      #
+      #   <%= form_for @post do |f| %>
+      #     <%= f.select :person_id, Person.all.collect {|p| [ p.name, p.id ] }, { include_blank: true }) %>
+      #     <%= f.submit %>
+      #   <% end %>
+      #
+      # Please refer to the documentation of the base helper for details.
       def select(method, choices, options = {}, html_options = {})
         @template.select(@object_name, method, choices, objectify_options(options), @default_options.merge(html_options))
       end
 
+      # Wraps ActionView::Helpers::FormOptionsHelper#collection_select for form builders:
+      #
+      #   <%= form_for @post do |f| %>
+      #     <%= f.collection_select :person_id, Author.all, :id, :name_with_initial, prompt: true %>
+      #     <%= f.submit %>
+      #   <% end %>
+      #
+      # Please refer to the documentation of the base helper for details.
       def collection_select(method, collection, value_method, text_method, options = {}, html_options = {})
         @template.collection_select(@object_name, method, collection, value_method, text_method, objectify_options(options), @default_options.merge(html_options))
       end
 
+      # Wraps ActionView::Helpers::FormOptionsHelper#grouped_collection_select for form builders:
+      #
+      #   <%= form_for @city do |f| %>
+      #     <%= f.grouped_collection_select :country_id, :country_id, @continents, :countries, :name, :id, :name %>
+      #     <%= f.submit %>
+      #   <% end %>
+      #
+      # Please refer to the documentation of the base helper for details.
       def grouped_collection_select(method, collection, group_method, group_label_method, option_key_method, option_value_method, options = {}, html_options = {})
         @template.grouped_collection_select(@object_name, method, collection, group_method, group_label_method, option_key_method, option_value_method, objectify_options(options), @default_options.merge(html_options))
       end
 
+      # Wraps ActionView::Helpers::FormOptionsHelper#time_zone_select for form builders:
+      #
+      #   <%= form_for @user do |f| %>
+      #     <%= f.time_zone_select :time_zone, nil, include_blank: true %>
+      #     <%= f.submit %>
+      #   <% end %>
+      #
+      # Please refer to the documentation of the base helper for details.
       def time_zone_select(method, priority_zones = nil, options = {}, html_options = {})
         @template.time_zone_select(@object_name, method, priority_zones, objectify_options(options), @default_options.merge(html_options))
       end
+
+      # Wraps ActionView::Helpers::FormOptionsHelper#collection_check_boxes for form builders:
+      #
+      #   <%= form_for @post do |f| %>
+      #     <%= f.collection_check_boxes :author_ids, Author.all, :id, :name_with_initial %>
+      #     <%= f.submit %>
+      #   <% end %>
+      #
+      # Please refer to the documentation of the base helper for details.
+      def collection_check_boxes(method, collection, value_method, text_method, options = {}, html_options = {}, &block)
+        @template.collection_check_boxes(@object_name, method, collection, value_method, text_method, objectify_options(options), @default_options.merge(html_options), &block)
+      end
+
+      # Wraps ActionView::Helpers::FormOptionsHelper#collection_radio_buttons for form builders:
+      #
+      #   <%= form_for @post do |f| %>
+      #     <%= f.collection_radio_buttons :author_id, Author.all, :id, :name_with_initial %>
+      #     <%= f.submit %>
+      #   <% end %>
+      #
+      # Please refer to the documentation of the base helper for details.
+      def collection_radio_buttons(method, collection, value_method, text_method, options = {}, html_options = {}, &block)
+        @template.collection_radio_buttons(@object_name, method, collection, value_method, text_method, objectify_options(options), @default_options.merge(html_options), &block)
+      end
     end
   end
 end