Skip to content
This repository
Browse code

Fix doc for #check_box [#6311 state:resolved]

Signed-off-by: Xavier Noria <fxn@hashref.com>
  • Loading branch information...
commit 4f0c8ef9f1e68be88b22cce6a857e1a9b6434182 1 parent bc302f2
jrdioko authored fxn committed
35  actionpack/lib/action_view/helpers/form_helper.rb
@@ -665,7 +665,7 @@ def text_area(object_name, method, options = {})
665 665
       #
666 666
       # The HTML specification says unchecked check boxes are not successful, and
667 667
       # thus web browsers do not send them. Unfortunately this introduces a gotcha:
668  
-      # if an Invoice model has a +paid+ flag, and in the form that edits a paid
  668
+      # if an +Invoice+ model has a +paid+ flag, and in the form that edits a paid
669 669
       # invoice the user unchecks its check box, no +paid+ parameter is sent. So,
670 670
       # any mass-assignment idiom like
671 671
       #
@@ -673,12 +673,15 @@ def text_area(object_name, method, options = {})
673 673
       #
674 674
       # wouldn't update the flag.
675 675
       #
676  
-      # To prevent this the helper generates a hidden field with the same name as
677  
-      # the checkbox after the very check box. So, the client either sends only the
678  
-      # hidden field (representing the check box is unchecked), or both fields.
679  
-      # Since the HTML specification says key/value pairs have to be sent in the
680  
-      # same order they appear in the form and Rails parameters extraction always
681  
-      # gets the first occurrence of any given key, that works in ordinary forms.
  676
+      # To prevent this the helper generates an auxiliary hidden field before
  677
+      # the very check box. The hidden field has the same name and its
  678
+      # attributes mimick an unchecked check box.
  679
+      #
  680
+      # This way, the client either sends only the hidden field (representing
  681
+      # the check box is unchecked), or both fields. Since the HTML specification
  682
+      # says key/value pairs have to be sent in the same order they appear in the
  683
+      # form, and parameters extraction gets the last occurrence of any repeated
  684
+      # key in the query string, that works for ordinary forms.
682 685
       #
683 686
       # Unfortunately that workaround does not work when the check box goes
684 687
       # within an array-like parameter, as in
@@ -689,22 +692,26 @@ def text_area(object_name, method, options = {})
689 692
       #   <% end %>
690 693
       #
691 694
       # because parameter name repetition is precisely what Rails seeks to distinguish
692  
-      # the elements of the array.
  695
+      # the elements of the array. For each item with a checked check box you
  696
+      # get an extra ghost item with only that attribute, assigned to "0".
  697
+      #
  698
+      # In that case it is preferable to either use +check_box_tag+ or to use
  699
+      # hashes instead of arrays.
693 700
       #
694 701
       # ==== Examples
695 702
       #   # Let's say that @post.validated? is 1:
696 703
       #   check_box("post", "validated")
697  
-      #   # => <input type="checkbox" id="post_validated" name="post[validated]" value="1" />
698  
-      #   #    <input name="post[validated]" type="hidden" value="0" />
  704
+      #   # => <input name="post[validated]" type="hidden" value="0" />
  705
+      #   #    <input type="checkbox" id="post_validated" name="post[validated]" value="1" />
699 706
       #
700 707
       #   # Let's say that @puppy.gooddog is "no":
701 708
       #   check_box("puppy", "gooddog", {}, "yes", "no")
702  
-      #   # => <input type="checkbox" id="puppy_gooddog" name="puppy[gooddog]" value="yes" />
703  
-      #   #    <input name="puppy[gooddog]" type="hidden" value="no" />
  709
+      #   # => <input name="puppy[gooddog]" type="hidden" value="no" />
  710
+      #   #    <input type="checkbox" id="puppy_gooddog" name="puppy[gooddog]" value="yes" />
704 711
       #
705 712
       #   check_box("eula", "accepted", { :class => 'eula_check' }, "yes", "no")
706  
-      #   # => <input type="checkbox" class="eula_check" id="eula_accepted" name="eula[accepted]" value="yes" />
707  
-      #   #    <input name="eula[accepted]" type="hidden" value="no" />
  713
+      #   # => <input name="eula[accepted]" type="hidden" value="no" />
  714
+      #   #    <input type="checkbox" class="eula_check" id="eula_accepted" name="eula[accepted]" value="yes" />
708 715
       #
709 716
       def check_box(object_name, method, options = {}, checked_value = "1", unchecked_value = "0")
710 717
         InstanceTag.new(object_name, method, self, options.delete(:object)).to_check_box_tag(options, checked_value, unchecked_value)

0 notes on commit 4f0c8ef

Please sign in to comment.
Something went wrong with that request. Please try again.