actionview 4.2.11 → 5.0.7

data/lib/action_view/helpers/debug_helper.rb

@@ -26,7 +26,7 @@ module ActionView
         Marshal::dump(object)
         object = ERB::Util.html_escape(object.to_yaml)
         content_tag(:pre, object, :class => "debug_dump")
-      rescue Exception  # errors from Marshal or YAML
+      rescue # errors from Marshal or YAML
         # Object couldn't be dumped, perhaps because of singleton methods -- this is the fallback
         content_tag(:code, object.inspect, :class => "debug_dump")
       end

data/lib/action_view/helpers/form_helper.rb

@@ -4,6 +4,7 @@ require 'action_view/helpers/tag_helper'
 require 'action_view/helpers/form_tag_helper'
 require 'action_view/helpers/active_model_helper'
 require 'action_view/model_naming'
+require 'action_view/record_identifier'
 require 'active_support/core_ext/module/attribute_accessors'
 require 'active_support/core_ext/hash/slice'
 require 'active_support/core_ext/string/output_safety'
@@ -66,9 +67,10 @@ module ActionView
     #
     # In particular, thanks to the conventions followed in the generated field names, the
     # controller gets a nested hash <tt>params[:person]</tt> with the person attributes
-    # set in the form. That hash is ready to be passed to <tt>Person.create</tt>:
+    # set in the form. That hash is ready to be passed to <tt>Person.new</tt>:
     #
-    #   if @person = Person.create(params[:person])
+    #   @person = Person.new(params[:person])
+    #   if @person.save
     #     # success
     #   else
     #     # error handling
@@ -110,6 +112,9 @@ module ActionView
       include FormTagHelper
       include UrlHelper
       include ModelNaming
+      include RecordIdentifier
+
+      attr_internal :default_form_builder
 
       # Creates a form that allows the user to create or update the attributes
       # of a specific model object.
@@ -138,6 +143,7 @@ module ActionView
       # will get expanded to
       #
       #   <%= text_field :person, :first_name %>
+      #
       # which results in an HTML <tt><input></tt> tag whose +name+ attribute is
       # <tt>person[first_name]</tt>. This means that when the form is submitted,
       # the value entered by the user will be available in the controller as
@@ -759,7 +765,7 @@ module ActionView
       #   # => <label for="post_privacy_public">Public Post</label>
       #
       #   label(:post, :terms) do
-      #     'Accept <a href="/terms">Terms</a>.'.html_safe
+      #     raw('Accept <a href="/terms">Terms</a>.')
       #   end
       #   # => <label for="post_terms">Accept <a href="/terms">Terms</a>.</label>
       def label(object_name, method, content_or_options = nil, options = nil, &block)
@@ -843,8 +849,8 @@ module ActionView
       #   file_field(:user, :avatar)
       #   # => <input type="file" id="user_avatar" name="user[avatar]" />
       #
-      #   file_field(:post, :image, :multiple => true)
-      #   # => <input type="file" id="post_image" name="post[image]" multiple="true" />
+      #   file_field(:post, :image, multiple: true)
+      #   # => <input type="file" id="post_image" name="post[image][]" multiple="multiple" />
       #
       #   file_field(:post, :attached, accept: 'text/html')
       #   # => <input accept="text/html" type="file" id="post_attached" name="post[attached]" />
@@ -1014,7 +1020,7 @@ module ActionView
       #   date_field("user", "born_on")
       #   # => <input id="user_born_on" name="user[born_on]" type="date" />
       #
-      # The default value is generated by trying to call "to_date"
+      # The default value is generated by trying to call +strftime+ with "%Y-%m-%d"
       # on the object's value, which makes it behave as expected for instances
       # of DateTime and ActiveSupport::TimeWithZone. You can still override that
       # by passing the "value" option explicitly, e.g.
@@ -1068,38 +1074,9 @@ module ActionView
         Tags::TimeField.new(object_name, method, self, options).render
       end
 
-      # Returns a text_field of type "datetime".
-      #
-      #   datetime_field("user", "born_on")
-      #   # => <input id="user_born_on" name="user[born_on]" type="datetime" />
-      #
-      # The default value is generated by trying to call +strftime+ with "%Y-%m-%dT%T.%L%z"
-      # on the object's value, which makes it behave as expected for instances
-      # of DateTime and ActiveSupport::TimeWithZone.
-      #
-      #   @user.born_on = Date.new(1984, 1, 12)
-      #   datetime_field("user", "born_on")
-      #   # => <input id="user_born_on" name="user[born_on]" type="datetime" value="1984-01-12T00:00:00.000+0000" />
-      #
-      # You can create values for the "min" and "max" attributes by passing
-      # instances of Date or Time to the options hash.
-      #
-      #   datetime_field("user", "born_on", min: Date.today)
-      #   # => <input id="user_born_on" name="user[born_on]" type="datetime" min="2014-05-20T00:00:00.000+0000" />
-      #
-      # Alternatively, you can pass a String formatted as an ISO8601 datetime
-      # with UTC offset as the values for "min" and "max."
-      #
-      #   datetime_field("user", "born_on", min: "2014-05-20T00:00:00+0000")
-      #   # => <input id="user_born_on" name="user[born_on]" type="datetime" min="2014-05-20T00:00:00.000+0000" />
-      #
-      def datetime_field(object_name, method, options = {})
-        Tags::DatetimeField.new(object_name, method, self, options).render
-      end
-
       # Returns a text_field of type "datetime-local".
       #
-      #   datetime_local_field("user", "born_on")
+      #   datetime_field("user", "born_on")
       #   # => <input id="user_born_on" name="user[born_on]" type="datetime-local" />
       #
       # The default value is generated by trying to call +strftime+ with "%Y-%m-%dT%T"
@@ -1107,25 +1084,27 @@ module ActionView
       # of DateTime and ActiveSupport::TimeWithZone.
       #
       #   @user.born_on = Date.new(1984, 1, 12)
-      #   datetime_local_field("user", "born_on")
+      #   datetime_field("user", "born_on")
       #   # => <input id="user_born_on" name="user[born_on]" type="datetime-local" value="1984-01-12T00:00:00" />
       #
       # You can create values for the "min" and "max" attributes by passing
       # instances of Date or Time to the options hash.
       #
-      #   datetime_local_field("user", "born_on", min: Date.today)
+      #   datetime_field("user", "born_on", min: Date.today)
       #   # => <input id="user_born_on" name="user[born_on]" type="datetime-local" min="2014-05-20T00:00:00.000" />
       #
       # Alternatively, you can pass a String formatted as an ISO8601 datetime as
       # the values for "min" and "max."
       #
-      #   datetime_local_field("user", "born_on", min: "2014-05-20T00:00:00")
+      #   datetime_field("user", "born_on", min: "2014-05-20T00:00:00")
       #   # => <input id="user_born_on" name="user[born_on]" type="datetime-local" min="2014-05-20T00:00:00.000" />
       #
-      def datetime_local_field(object_name, method, options = {})
+      def datetime_field(object_name, method, options = {})
         Tags::DatetimeLocalField.new(object_name, method, self, options).render
       end
 
+      alias datetime_local_field datetime_field
+
       # Returns a text_field of type "month".
       #
       #   month_field("user", "born_on")
@@ -1211,7 +1190,7 @@ module ActionView
         end
 
         def default_form_builder_class
-          builder = ActionView::Base.default_form_builder
+          builder = default_form_builder || ActionView::Base.default_form_builder
           builder.respond_to?(:constantize) ? builder.constantize : builder
         end
     end
@@ -1586,14 +1565,22 @@ module ActionView
           record_name   = model_name_from_record_or_class(record_object).param_key
         end
 
+        object_name = @object_name
         index = if options.has_key?(:index)
           options[:index]
         elsif defined?(@auto_index)
-          self.object_name = @object_name.to_s.sub(/\[\]$/,"")
+          object_name = object_name.to_s.sub(/\[\]$/, "")
           @auto_index
         end
 
-        record_name = index ? "#{object_name}[#{index}][#{record_name}]" : "#{object_name}[#{record_name}]"
+        record_name = if index
+                        "#{object_name}[#{index}][#{record_name}]"
+                      elsif record_name.to_s.end_with?('[]')
+                        record_name = record_name.to_s.sub(/(.*)\[\]$/, "[\\1][#{record_object.id}]")
+                        "#{object_name}#{record_name}"
+                      else
+                        "#{object_name}[#{record_name}]"
+                      end
         fields_options[:child_index] = index
 
         @template.fields_for(record_name, record_object, fields_options, &block)
@@ -1607,7 +1594,7 @@ module ActionView
       # target labels for radio_button tags (where the value is used in the ID of the input tag).
       #
       # ==== Examples
-      #   label(:post, :title)
+      #   label(:title)
       #   # => <label for="post_title">Title</label>
       #
       # You can localize your labels based on model and attribute names.
@@ -1620,7 +1607,7 @@ module ActionView
       #
       # Which then will result in
       #
-      #   label(:post, :body)
+      #   label(:body)
       #   # => <label for="post_body">Write your entire text here</label>
       #
       # Localization can also be based purely on the translation of the attribute-name
@@ -1631,21 +1618,22 @@ module ActionView
       #       post:
       #         cost: "Total cost"
       #
-      #   label(:post, :cost)
+      #   label(:cost)
       #   # => <label for="post_cost">Total cost</label>
       #
-      #   label(:post, :title, "A short title")
+      #   label(:title, "A short title")
       #   # => <label for="post_title">A short title</label>
       #
-      #   label(:post, :title, "A short title", class: "title_label")
+      #   label(:title, "A short title", class: "title_label")
       #   # => <label for="post_title" class="title_label">A short title</label>
       #
-      #   label(:post, :privacy, "Public Post", value: "public")
+      #   label(:privacy, "Public Post", value: "public")
       #   # => <label for="post_privacy_public">Public Post</label>
       #
-      #   label(:post, :terms) do
-      #     'Accept <a href="/terms">Terms</a>.'.html_safe
+      #   label(:terms) do
+      #     raw('Accept <a href="/terms">Terms</a>.')
       #   end
+      #   # => <label for="post_terms">Accept <a href="/terms">Terms</a>.</label>
       def label(method, text = nil, options = {}, &block)
         @template.label(@object_name, method, text, objectify_options(options), &block)
       end
@@ -1694,16 +1682,17 @@ module ActionView
       # hashes instead of arrays.
       #
       #   # Let's say that @post.validated? is 1:
-      #   check_box("post", "validated")
+      #   check_box("validated")
       #   # => <input name="post[validated]" type="hidden" value="0" />
       #   #    <input checked="checked" type="checkbox" id="post_validated" name="post[validated]" value="1" />
       #
       #   # Let's say that @puppy.gooddog is "no":
-      #   check_box("puppy", "gooddog", {}, "yes", "no")
+      #   check_box("gooddog", {}, "yes", "no")
       #   # => <input name="puppy[gooddog]" type="hidden" value="no" />
       #   #    <input type="checkbox" id="puppy_gooddog" name="puppy[gooddog]" value="yes" />
       #
-      #   check_box("eula", "accepted", { class: 'eula_check' }, "yes", "no")
+      #   # Let's say that @eula.accepted is "no":
+      #   check_box("accepted", { class: 'eula_check' }, "yes", "no")
       #   # => <input name="eula[accepted]" type="hidden" value="no" />
       #   #    <input type="checkbox" class="eula_check" id="eula_accepted" name="eula[accepted]" value="yes" />
       def check_box(method, options = {}, checked_value = "1", unchecked_value = "0")
@@ -1718,13 +1707,14 @@ module ActionView
       # +options+ hash. You may pass HTML options there as well.
       #
       #   # Let's say that @post.category returns "rails":
-      #   radio_button("post", "category", "rails")
-      #   radio_button("post", "category", "java")
+      #   radio_button("category", "rails")
+      #   radio_button("category", "java")
       #   # => <input type="radio" id="post_category_rails" name="post[category]" value="rails" checked="checked" />
       #   #    <input type="radio" id="post_category_java" name="post[category]" value="java" />
       #
-      #   radio_button("user", "receive_newsletter", "yes")
-      #   radio_button("user", "receive_newsletter", "no")
+      #   # Let's say that @user.category returns "no":
+      #   radio_button("receive_newsletter", "yes")
+      #   radio_button("receive_newsletter", "no")
       #   # => <input type="radio" id="user_receive_newsletter_yes" name="user[receive_newsletter]" value="yes" />
       #   #    <input type="radio" id="user_receive_newsletter_no" name="user[receive_newsletter]" value="no" checked="checked" />
       def radio_button(method, tag_value, options = {})
@@ -1737,14 +1727,17 @@ module ActionView
       # shown.
       #
       # ==== Examples
-      #   hidden_field(:signup, :pass_confirm)
-      #   # => <input type="hidden" id="signup_pass_confirm" name="signup[pass_confirm]" value="#{@signup.pass_confirm}" />
+      #   # Let's say that @signup.pass_confirm returns true:
+      #   hidden_field(:pass_confirm)
+      #   # => <input type="hidden" id="signup_pass_confirm" name="signup[pass_confirm]" value="true" />
       #
-      #   hidden_field(:post, :tag_list)
-      #   # => <input type="hidden" id="post_tag_list" name="post[tag_list]" value="#{@post.tag_list}" />
+      #   # Let's say that @post.tag_list returns "blog, ruby":
+      #   hidden_field(:tag_list)
+      #   # => <input type="hidden" id="post_tag_list" name="post[tag_list]" value="blog, ruby" />
       #
-      #   hidden_field(:user, :token)
-      #   # => <input type="hidden" id="user_token" name="user[token]" value="#{@user.token}" />
+      #   # Let's say that @user.token returns "abcde":
+      #   hidden_field(:token)
+      #   # => <input type="hidden" id="user_token" name="user[token]" value="abcde" />
       #
       def hidden_field(method, options = {})
         @emitted_hidden_id = true if method == :id
@@ -1765,19 +1758,24 @@ module ActionView
       # * <tt>:accept</tt> - If set to one or multiple mime-types, the user will be suggested a filter when choosing a file. You still need to set up model validations.
       #
       # ==== Examples
-      #   file_field(:user, :avatar)
+      #   # Let's say that @user has avatar:
+      #   file_field(:avatar)
       #   # => <input type="file" id="user_avatar" name="user[avatar]" />
       #
-      #   file_field(:post, :image, :multiple => true)
-      #   # => <input type="file" id="post_image" name="post[image]" multiple="true" />
+      #   # Let's say that @post has image:
+      #   file_field(:image, :multiple => true)
+      #   # => <input type="file" id="post_image" name="post[image][]" multiple="multiple" />
       #
-      #   file_field(:post, :attached, accept: 'text/html')
+      #   # Let's say that @post has attached:
+      #   file_field(:attached, accept: 'text/html')
       #   # => <input accept="text/html" type="file" id="post_attached" name="post[attached]" />
       #
-      #   file_field(:post, :image, accept: 'image/png,image/gif,image/jpeg')
+      #   # Let's say that @post has image:
+      #   file_field(:image, accept: 'image/png,image/gif,image/jpeg')
       #   # => <input type="file" id="post_image" name="post[image]" accept="image/png,image/gif,image/jpeg" />
       #
-      #   file_field(:attachment, :file, class: 'file_input')
+      #   # Let's say that @attachment has file:
+      #   file_field(:file, class: 'file_input')
       #   # => <input type="file" id="attachment_file" name="attachment[file]" class="file_input" />
       def file_field(method, options = {})
         self.multipart = true
@@ -1845,7 +1843,7 @@ module ActionView
       #           create: "Add %{model}"
       #
       # ==== Examples
-      #   button("Create a post")
+      #   button("Create post")
       #   # => <button name='button' type='submit'>Create post</button>
       #
       #   button do
@@ -1906,7 +1904,11 @@ module ActionView
             explicit_child_index = options[:child_index]
             output = ActiveSupport::SafeBuffer.new
             association.each do |child|
-              options[:child_index] = nested_child_index(name) unless explicit_child_index
+              if explicit_child_index
+                options[:child_index] = explicit_child_index.call if explicit_child_index.respond_to?(:call)
+              else
+                options[:child_index] = nested_child_index(name)
+              end
               output << fields_for_nested_model("#{name}[#{options[:child_index]}]", child, options, block)
             end
             output

data/lib/action_view/helpers/form_options_helper.rb

@@ -18,10 +18,10 @@ module ActionView
     #
     #   could become:
     #
-    #     <select name="post[category]">
-    #       <option></option>
-    #       <option>joke</option>
-    #       <option>poem</option>
+    #     <select name="post[category]" id="post_category">
+    #       <option value=""></option>
+    #       <option value="joke">joke</option>
+    #       <option value="poem">poem</option>
     #     </select>
     #
     #   Another common case is a select tag for a <tt>belongs_to</tt>-associated object.
@@ -32,11 +32,11 @@ module ActionView
     #
     #   could become:
     #
-    #     <select name="post[person_id]">
+    #     <select name="post[person_id]" id="post_person_id">
     #       <option value="">None</option>
     #       <option value="1">David</option>
-    #       <option value="2" selected="selected">Sam</option>
-    #       <option value="3">Tobias</option>
+    #       <option value="2" selected="selected">Eileen</option>
+    #       <option value="3">Rafael</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.
@@ -45,11 +45,11 @@ module ActionView
     #
     #   could become:
     #
-    #     <select name="post[person_id]">
+    #     <select name="post[person_id]" id="post_person_id">
     #       <option value="">Select Person</option>
     #       <option value="1">David</option>
-    #       <option value="2">Sam</option>
-    #       <option value="3">Tobias</option>
+    #       <option value="2">Eileen</option>
+    #       <option value="3">Rafael</option>
     #     </select>
     #
     # * <tt>:index</tt> - 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
@@ -71,19 +71,19 @@ module ActionView
     #
     #   could become:
     #
-    #     <select name="post[category]">
-    #       <option></option>
-    #       <option>joke</option>
-    #       <option>poem</option>
-    #       <option disabled="disabled">restricted</option>
+    #     <select name="post[category]" id="post_category">
+    #       <option value=""></option>
+    #       <option value="joke">joke</option>
+    #       <option value="poem">poem</option>
+    #       <option disabled="disabled" value="restricted">restricted</option>
     #     </select>
     #
     #   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.
     #
-    #     collection_select(:post, :category_id, Category.all, :id, :name, {disabled: lambda{|category| category.archived? }})
+    #     collection_select(:post, :category_id, Category.all, :id, :name, {disabled: -> (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]">
+    #     <select name="post[category_id]" id="post_category_id">
     #       <option value="1" disabled="disabled">2008 stuff</option>
     #       <option value="2" disabled="disabled">Christmas</option>
     #       <option value="3">Jokes</option>
@@ -109,11 +109,11 @@ module ActionView
       #
       # would become:
       #
-      #   <select name="post[person_id]">
+      #   <select name="post[person_id]" id="post_person_id">
       #     <option value=""></option>
       #     <option value="1" selected="selected">David</option>
-      #     <option value="2">Sam</option>
-      #     <option value="3">Tobias</option>
+      #     <option value="2">Eileen</option>
+      #     <option value="3">Rafael</option>
       #   </select>
       #
       # assuming the associated person has ID 1.
@@ -192,7 +192,7 @@ module ActionView
       #   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]">
+      #   <select name="post[author_id]" id="post_author_id">
       #     <option value="">Please select</option>
       #     <option value="1" selected="selected">D. Heinemeier Hansson</option>
       #     <option value="2">D. Thomas</option>
@@ -243,7 +243,7 @@ module ActionView
       #
       # Possible output:
       #
-      #   <select name="city[country_id]">
+      #   <select name="city[country_id]" id="city_country_id">
       #     <optgroup label="Africa">
       #       <option value="1">South Africa</option>
       #       <option value="3">Somalia</option>
@@ -268,10 +268,11 @@ module ActionView
       # for more information.)
       #
       # You can also supply an array of ActiveSupport::TimeZone objects
-      # as +priority_zones+, so that they will be listed above the rest of the
-      # (long) list. (You can use ActiveSupport::TimeZone.us_zones as a convenience
-      # for obtaining a list of the US time zones, or a Regexp to select the zones
-      # of your choice)
+      # as +priority_zones+ so that they will be listed above the rest of the
+      # (long) list. You can use ActiveSupport::TimeZone.us_zones for a list
+      # of US time zones, ActiveSupport::TimeZone.country_zones(country_code)
+      # for another country's time zones, or a Regexp to select the zones of
+      # your choice.
       #
       # Finally, this method supports a <tt>:default</tt> option, which selects
       # a default ActiveSupport::TimeZone if the object's time zone is +nil+.
@@ -302,17 +303,17 @@ module ActionView
       #   # => <option value="DKK">Kroner</option>
       #
       #   options_for_select([ "VISA", "MasterCard" ], "MasterCard")
-      #   # => <option>VISA</option>
-      #   # => <option selected="selected">MasterCard</option>
+      #   # => <option value="VISA">VISA</option>
+      #   # => <option selected="selected" value="MasterCard">MasterCard</option>
       #
       #   options_for_select({ "Basic" => "$20", "Plus" => "$40" }, "$40")
       #   # => <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>
-      #   # => <option>MasterCard</option>
-      #   # => <option selected="selected">Discover</option>
+      #   # => <option selected="selected" value="VISA">VISA</option>
+      #   # => <option value="MasterCard">MasterCard</option>
+      #   # => <option selected="selected" value="Discover">Discover</option>
       #
       # You can optionally provide HTML attributes as the last element of the array.
       #
@@ -351,12 +352,12 @@ module ActionView
         return container if String === container
 
         selected, disabled = extract_selected_and_disabled(selected).map do |r|
-          Array(r).map { |item| item.to_s }
+          Array(r).map(&: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 }
+          text, value = option_text_and_value(element).map(&:to_s)
 
           html_attributes[:selected] ||= option_value_selected?(value, selected)
           html_attributes[:disabled] ||= disabled && option_value_selected?(value, disabled)
@@ -456,7 +457,7 @@ module ActionView
           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))
+          content_tag("optgroup".freeze, option_tags, label: group.send(group_label_method))
         end.join.html_safe
       end
 
@@ -528,7 +529,7 @@ module ActionView
         body = "".html_safe
 
         if prompt
-          body.safe_concat content_tag(:option, prompt_text(prompt), value: "")
+          body.safe_concat content_tag("option".freeze, prompt_text(prompt), value: "")
         end
 
         grouped_options.each do |container|
@@ -541,14 +542,14 @@ module ActionView
           end
 
           html_attributes = { label: label }.merge!(html_attributes)
-          body.safe_concat content_tag(:optgroup, options_for_select(container, selected_key), html_attributes)
+          body.safe_concat content_tag("optgroup".freeze, options_for_select(container, selected_key), html_attributes)
         end
 
         body
       end
 
       # Returns a string of option tags for pretty much any time zone in the
-      # world. Supply a ActiveSupport::TimeZone name as +selected+ to have it
+      # world. Supply an ActiveSupport::TimeZone name as +selected+ to have it
       # marked as the selected option tag. You can also supply an array of
       # ActiveSupport::TimeZone objects as +priority_zones+, so that they will
       # be listed above the rest of the (long) list. (You can use
@@ -556,7 +557,7 @@ module ActionView
       # of the US time zones, or a Regexp to select the zones of your choice)
       #
       # The +selected+ parameter must be either +nil+, or a string that names
-      # a ActiveSupport::TimeZone.
+      # an ActiveSupport::TimeZone.
       #
       # By default, +model+ is the ActiveSupport::TimeZone constant (which can
       # be obtained in Active Record as a value object). The only requirement
@@ -577,7 +578,7 @@ module ActionView
           end
 
           zone_options.safe_concat options_for_select(convert_zones[priority_zones], selected)
-          zone_options.safe_concat content_tag(:option, '-------------', value: '', disabled: true)
+          zone_options.safe_concat content_tag("option".freeze, '-------------', value: '', disabled: true)
           zone_options.safe_concat "\n"
 
           zones = zones - priority_zones
@@ -644,6 +645,24 @@ module ActionView
       #   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
+      #
+      # ==== Gotcha
+      #
+      # The HTML specification says when nothing is select on a collection of radio buttons
+      # web browsers do not send any value to server.
+      # Unfortunately this introduces a gotcha:
+      # if a +User+ model has a +category_id+ field, and in the form none category is selected no +category_id+ parameter is sent. So,
+      # any strong parameters idiom like
+      #
+      #   params.require(:user).permit(...)
+      #
+      # will raise an error since no +{user: ...}+ will be present.
+      #
+      # To prevent this the helper generates an auxiliary hidden field before
+      # every collection of radio buttons. The hidden field has the same name as collection radio button and blank value.
+      #
+      # In case if you don't want the helper to generate this hidden field you can specify
+      # <tt>include_hidden: false</tt> option.
       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
@@ -707,6 +726,27 @@ module ActionView
       #   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
+      #
+      # ==== Gotcha
+      #
+      # When no selection is made for a collection of checkboxes most
+      # web browsers will not send any value.
+      #
+      # For example, if we have a +User+ model with +category_ids+ field and we
+      # have the following code in our update action:
+      #
+      #   @user.update(params[:user])
+      #
+      # If no +category_ids+ are selected then we can safely assume this field
+      # will not be updated.
+      #
+      # This is possible thanks to a hidden field generated by the helper method
+      # for every collection of checkboxes.
+      # This hidden field is given the same field name as the checkboxes with a
+      # blank value.
+      #
+      # In the rare case you don't want this hidden field, you can pass the
+      # <tt>include_hidden: false</tt> option to the helper method.
       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