From 8c072adf4f35a874cad0748e7e0205bd97faf584 Mon Sep 17 00:00:00 2001
From: Johnathan Ritzi <leivoset@gmail.com>
Date: Tue, 18 Jan 2011 12:10:28 -0800
Subject: [PATCH] Fix doc for #check_box [#6311 state:resolved]

---
 actionpack/lib/action_view/helpers/form_helper.rb |   35 ++++++++++++--------
 1 files changed, 21 insertions(+), 14 deletions(-)

diff --git a/actionpack/lib/action_view/helpers/form_helper.rb b/actionpack/lib/action_view/helpers/form_helper.rb
index 38c44a2..389212d 100644
--- a/actionpack/lib/action_view/helpers/form_helper.rb
+++ b/actionpack/lib/action_view/helpers/form_helper.rb
@@ -665,7 +665,7 @@ module ActionView
       #
       # The HTML specification says unchecked check boxes are not successful, and
       # thus web browsers do not send them. Unfortunately this introduces a gotcha:
-      # if an Invoice model has a +paid+ flag, and in the form that edits a paid
+      # if an +Invoice+ model has a +paid+ flag, and in the form that edits a paid
       # invoice the user unchecks its check box, no +paid+ parameter is sent. So,
       # any mass-assignment idiom like
       #
@@ -673,12 +673,15 @@ module ActionView
       #
       # wouldn't update the flag.
       #
-      # To prevent this the helper generates a hidden field with the same name as
-      # the checkbox after the very check box. So, the client either sends only the
-      # hidden field (representing the check box is unchecked), or both fields.
-      # Since the HTML specification says key/value pairs have to be sent in the
-      # same order they appear in the form and Rails parameters extraction always
-      # gets the first occurrence of any given key, that works in ordinary forms.
+      # To prevent this the helper generates an auxiliary hidden field before
+      # the very check box. The hidden field has the same name and its
+      # attributes mimick an unchecked check box.
+      #
+      # This way, the client either sends only the hidden field (representing
+      # the check box is unchecked), or both fields. Since the HTML specification
+      # says key/value pairs have to be sent in the same order they appear in the
+      # form, and parameters extraction gets the last occurrence of any repeated
+      # key in the query string, that works for ordinary forms.
       #
       # Unfortunately that workaround does not work when the check box goes
       # within an array-like parameter, as in
@@ -689,22 +692,26 @@ module ActionView
       #   <% end %>
       #
       # because parameter name repetition is precisely what Rails seeks to distinguish
-      # the elements of the array.
+      # the elements of the array. For each item with a checked check box you
+      # get an extra ghost item with only that attribute, assigned to "0".
+      #
+      # In that case it is preferable to either use +check_box_tag+ or to use
+      # hashes instead of arrays.
       #
       # ==== Examples
       #   # Let's say that @post.validated? is 1:
       #   check_box("post", "validated")
-      #   # => <input type="checkbox" id="post_validated" name="post[validated]" value="1" />
-      #   #    <input name="post[validated]" type="hidden" value="0" />
+      #   # => <input name="post[validated]" type="hidden" value="0" />
+      #   #    <input type="checkbox" id="post_validated" name="post[validated]" value="1" />
       #
       #   # Let's say that @puppy.gooddog is "no":
       #   check_box("puppy", "gooddog", {}, "yes", "no")
-      #   # => <input type="checkbox" id="puppy_gooddog" name="puppy[gooddog]" value="yes" />
-      #   #    <input name="puppy[gooddog]" type="hidden" value="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")
-      #   # => <input type="checkbox" class="eula_check" id="eula_accepted" name="eula[accepted]" value="yes" />
-      #   #    <input name="eula[accepted]" type="hidden" value="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(object_name, method, options = {}, checked_value = "1", unchecked_value = "0")
         InstanceTag.new(object_name, method, self, options.delete(:object)).to_check_box_tag(options, checked_value, unchecked_value)
-- 
1.6.0.6