Skip to content
This repository
Browse code

Clean up multiple calls to #stringify_keys in TagHelper, add better d…

…ocumentation and testing for TagHelper. Closes #6394 [Bob Silva]

git-svn-id: http://svn-commit.rubyonrails.org/rails/trunk@5857 5ecf4fe2-1ee6-0310-87b1-e25e094e27de
  • Loading branch information...
commit 730c8e8391310330a175454cc73066979ee8b04c 1 parent 1400e7f
risk danger olson authored January 05, 2007
2  actionpack/CHANGELOG
... ...
@@ -1,5 +1,7 @@
1 1
 *SVN*
2 2
 
  3
+* Clean up multiple calls to #stringify_keys in TagHelper, add better documentation and testing for TagHelper.  Closes #6394 [Bob Silva]
  4
+
3 5
 * [DOCS] fix reference to ActionController::Macros::AutoComplete for #text_field_with_auto_complete. Closes #2578 [Jan Prill]
4 6
 
5 7
 * Make sure html_document is reset between integration test requests. [ctm]
65  actionpack/lib/action_view/helpers/tag_helper.rb
@@ -2,30 +2,48 @@
2 2
 require 'erb'
3 3
 
4 4
 module ActionView
5  
-  module Helpers
6  
-    # This is poor man's Builder for the rare cases where you need to programmatically make tags but can't use Builder.
  5
+  module Helpers #:nodoc:
  6
+    # Use these methods to generate HTML tags programmatically when you can't use
  7
+    # a Builder. By default, they output XHTML compliant tags.
7 8
     module TagHelper
8 9
       include ERB::Util
9 10
 
10  
-      # Examples:
11  
-      # * <tt>tag("br") => <br /></tt>
12  
-      # * <tt>tag("input", { "type" => "text"}) => <input type="text" /></tt>
  11
+      # Returns an empty HTML tag of type +name+ which by default is XHTML 
  12
+      # compliant. Setting +open+ to true will create an open tag compatible 
  13
+      # with HTML 4.0 and below. Add HTML attributes by passing an attributes 
  14
+      # hash to +options+. For attributes with no value like (disabled and 
  15
+      # readonly), give it a value of true in the +options+ hash. You can use
  16
+      # symbols or strings for the attribute names.
  17
+      #
  18
+      #   tag("br")
  19
+      #    # => <br />
  20
+      #   tag("br", nil, true)
  21
+      #    # => <br>
  22
+      #   tag("input", { :type => 'text', :disabled => true }) 
  23
+      #    # => <input type="text" disabled="disabled" />
13 24
       def tag(name, options = nil, open = false)
14  
-        "<#{name}#{tag_options(options.stringify_keys) if options}" + (open ? ">" : " />")
  25
+        "<#{name}#{tag_options(options) if options}" + (open ? ">" : " />")
15 26
       end
16 27
 
17  
-      # Examples:
18  
-      # * <tt>content_tag(:p, "Hello world!") => <p>Hello world!</p></tt>
19  
-      # * <tt>content_tag(:div, content_tag(:p, "Hello world!"), :class => "strong") => </tt>
20  
-      #   <tt><div class="strong"><p>Hello world!</p></div></tt>
  28
+      # Returns an HTML block tag of type +name+ surrounding the +content+. Add
  29
+      # HTML attributes by passing an attributes hash to +options+. For attributes 
  30
+      # with no value like (disabled and readonly), give it a value of true in 
  31
+      # the +options+ hash. You can use symbols or strings for the attribute names.
  32
+      #
  33
+      #   content_tag(:p, "Hello world!")
  34
+      #    # => <p>Hello world!</p>
  35
+      #   content_tag(:div, content_tag(:p, "Hello world!"), :class => "strong")
  36
+      #    # => <div class="strong"><p>Hello world!</p></div>
  37
+      #   content_tag("select", options, :multiple => true)
  38
+      #    # => <select multiple="multiple">...options...</select>
21 39
       #
22  
-      # ERb example:
23  
-      #  <% content_tag :div, :class => "strong" do -%>
24  
-      #    Hello world!
25  
-      #  <% end -%>
  40
+      # Instead of passing the content as an argument, you can also use a block
  41
+      # in which case, you pass your +options+ as the second parameter.
26 42
       #
27  
-      # Will output:
28  
-      #   <div class="strong"><p>Hello world!</p></div>
  43
+      #   <% content_tag :div, :class => "strong" do -%>
  44
+      #     Hello world!
  45
+      #   <% end -%>
  46
+      #    # => <div class="strong"><p>Hello world!</p></div>
29 47
       def content_tag(name, content_or_options_with_block = nil, options = nil, &block)
30 48
         if block_given?
31 49
           options = content_or_options_with_block if content_or_options_with_block.is_a?(Hash)
@@ -37,27 +55,28 @@ def content_tag(name, content_or_options_with_block = nil, options = nil, &block
37 55
         end
38 56
       end
39 57
 
40  
-      # Returns a CDATA section for the given +content+.  CDATA sections
  58
+      # Returns a CDATA section with the given +content+.  CDATA sections
41 59
       # are used to escape blocks of text containing characters which would
42 60
       # otherwise be recognized as markup. CDATA sections begin with the string
43  
-      # <tt>&lt;![CDATA[</tt> and end with (and may not contain) the string 
44  
-      # <tt>]]></tt>. 
  61
+      # <tt><![CDATA[</tt> and end with (and may not contain) the string <tt>]]></tt>.
  62
+      #
  63
+      #   cdata_section("<hello world>")
  64
+      #    # => <![CDATA[<hello world>]]>
45 65
       def cdata_section(content)
46 66
         "<![CDATA[#{content}]]>"
47 67
       end
48 68
 
49  
-      # Escapes a given string, while leaving any currently escaped entities alone.
  69
+      # Returns the escaped +html+ without affecting existing escaped entities.
50 70
       #
51 71
       #   escape_once("1 > 2 &amp; 3")
52  
-      #   # => "1 &lt; 2 &amp; 3"
53  
-      #
  72
+      #    # => "1 &lt; 2 &amp; 3"
54 73
       def escape_once(html)
55 74
         fix_double_escape(html_escape(html.to_s))
56 75
       end
57 76
 
58 77
       private
59 78
         def content_tag_string(name, content, options)
60  
-          tag_options = options ? tag_options(options.stringify_keys) : ""
  79
+          tag_options = options ? tag_options(options) : ""
61 80
           "<#{name}#{tag_options}>#{content}</#{name}>"
62 81
         end
63 82
       
5  actionpack/test/template/tag_helper_test.rb
@@ -7,8 +7,9 @@ class TagHelperTest < Test::Unit::TestCase
7 7
   include ActionView::Helpers::CaptureHelper
8 8
 
9 9
   def test_tag
10  
-    assert_equal "<p class=\"show\" />", tag("p", "class" => "show")
11  
-    assert_equal tag("p", "class" => "show"), tag("p", :class => "show")
  10
+    assert_equal "<br />", tag("br")
  11
+    assert_equal "<br clear=\"left\" />", tag(:br, :clear => "left")
  12
+    assert_equal "<br>", tag("br", nil, true)
12 13
   end
13 14
 
14 15
   def test_tag_options

0 notes on commit 730c8e8

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