diff options
Diffstat (limited to 'actionpack/lib/action_view/helpers/text_helper.rb')
| -rw-r--r-- | actionpack/lib/action_view/helpers/text_helper.rb | 266 |
1 files changed, 218 insertions, 48 deletions
diff --git a/actionpack/lib/action_view/helpers/text_helper.rb b/actionpack/lib/action_view/helpers/text_helper.rb index d986233796..8db8ce7009 100644 --- a/actionpack/lib/action_view/helpers/text_helper.rb +++ b/actionpack/lib/action_view/helpers/text_helper.rb @@ -3,35 +3,48 @@ require 'html/document' module ActionView module Helpers #:nodoc: - # The TextHelper Module provides a set of methods for filtering, formatting - # and transforming strings that can reduce the amount of inline Ruby code in + # The TextHelper module provides a set of methods for filtering, formatting + # and transforming strings, which can reduce the amount of inline Ruby code in # your views. These helper methods extend ActionView making them callable - # within your template files as shown in the following example which truncates - # the title of each post to 10 characters. - # - # <% @posts.each do |post| %> - # # post == 'This is my title' - # Title: <%= truncate(post.title, 10) %> - # <% end %> - # => Title: This is my... + # within your template files. module TextHelper # The preferred method of outputting text in your views is to use the # <%= "text" %> eRuby syntax. The regular _puts_ and _print_ methods # do not operate as expected in an eRuby code block. If you absolutely must - # output text within a code block, you can use the concat method. + # output text within a non-output code block (i.e., <% %>), you can use the concat method. # - # <% concat "hello", binding %> - # is equivalent to using: - # <%= "hello" %> + # ==== Examples + # <% + # concat "hello", binding + # # is the equivalent of <%= "hello" %> + # + # if (logged_in == true): + # concat "Logged in!", binding + # else + # concat link_to('login', :action => login), binding + # end + # # will either display "Logged in!" or a login link + # %> def concat(string, binding) eval(ActionView::Base.erb_variable, binding) << string end # If +text+ is longer than +length+, +text+ will be truncated to the length of - # +length+ and the last three characters will be replaced with the +truncate_string+. + # +length+ (defaults to 30) and the last three characters will be replaced with the +truncate_string+ + # (defaults to "..."). # + # ==== Examples # truncate("Once upon a time in a world far far away", 14) - # => Once upon a... + # # => Once upon a... + # + # truncate("Once upon a time in a world far far away") + # # => Once upon a time in a world f... + # + # truncate("And they found that many people were sleeping better.", 25, "(clipped)") + # # => And they found that many (clipped) + # + # truncate("And they found that many people were sleeping better.", 15, "... (continued)") + # # => And they found... (continued) def truncate(text, length = 30, truncate_string = "...") if text.nil? then return end l = length - truncate_string.chars.length @@ -40,13 +53,21 @@ module ActionView # Highlights one or more +phrases+ everywhere in +text+ by inserting it into # a +highlighter+ string. The highlighter can be specialized by passing +highlighter+ - # as a single-quoted string with \1 where the phrase is to be inserted. + # as a single-quoted string with \1 where the phrase is to be inserted (defaults to + # '<strong class="highlight">\1</strong>') # + # ==== Examples # highlight('You searched for: rails', 'rails') # # => You searched for: <strong class="highlight">rails</strong> # + # highlight('You searched for: ruby, rails, dhh', 'actionpack') + # # => You searched for: ruby, rails, dhh + # # highlight('You searched for: rails', ['for', 'rails'], '<em>\1</em>') # # => You searched <em>for</em>: <em>rails</em> + # + # highlight('You searched for: rails', 'rails', "<a href='search?q=\1'>\1</a>") + # # => You searched for: <a href='search?q=rails>rails</a> def highlight(text, phrases, highlighter = '<strong class="highlight">\1</strong>') if text.blank? || phrases.blank? text @@ -57,16 +78,26 @@ module ActionView end # Extracts an excerpt from +text+ that matches the first instance of +phrase+. - # The +radius+ expands the excerpt on each side of +phrase+ by the number of characters - # defined in +radius+. If the excerpt radius overflows the beginning or end of the +text+, + # The +radius+ expands the excerpt on each side of the first occurance of +phrase+ by the number of characters + # defined in +radius+ (which defaults to 100). If the excerpt radius overflows the beginning or end of the +text+, # then the +excerpt_string+ will be prepended/appended accordingly. If the +phrase+ # isn't found, nil is returned. # + # ==== Examples # excerpt('This is an example', 'an', 5) - # => "...s is an examp..." + # # => "...s is an examp..." # # excerpt('This is an example', 'is', 5) - # => "This is an..." + # # => "This is an..." + # + # excerpt('This is an example', 'is') + # # => "This is an example" + # + # excerpt('This next thing is an example', 'ex', 2) + # # => "...next t..." + # + # excerpt('This is also an example', 'an', 8, '<chop> ') + # # => "<chop> is also an example" def excerpt(text, phrase, radius = 100, excerpt_string = "...") if text.nil? || phrase.nil? then return end phrase = Regexp.escape(phrase) @@ -89,9 +120,18 @@ module ActionView # is loaded, it will use the Inflector to determine the plural form, otherwise # it will just add an 's' to the +singular+ word. # - # pluralize(1, 'person') => 1 person - # pluralize(2, 'person') => 2 people - # pluralize(3, 'person', 'users') => 3 users + # ==== Examples + # pluralize(1, 'person') + # # => 1 person + # + # pluralize(2, 'person') + # # => 2 people + # + # pluralize(3, 'person', 'users') + # # => 3 users + # + # pluralize(0, 'person') + # # => 0 people def pluralize(count, singular, plural = nil) "#{count || 0} " + if count == 1 || count == '1' singular @@ -105,10 +145,21 @@ module ActionView end # Wraps the +text+ into lines no longer than +line_width+ width. This method - # breaks on the first whitespace character that does not exceed +line_width+. + # breaks on the first whitespace character that does not exceed +line_width+ + # (which is 80 by default). # + # ==== Examples # word_wrap('Once upon a time', 4) - # => Once\nupon\na\ntime + # # => Once\nupon\na\ntime + # + # word_wrap('Once upon a time', 8) + # # => Once upon\na time + # + # word_wrap('Once upon a time') + # # => Once upon a time + # + # word_wrap('Once upon a time', 1) + # # => Once\nupon\na\ntime def word_wrap(text, line_width = 80) text.gsub(/\n/, "\n\n").gsub(/(.{1,#{line_width}})(\s+|$)/, "\\1\n").strip end @@ -116,9 +167,24 @@ module ActionView begin require_library_or_gem "redcloth" unless Object.const_defined?(:RedCloth) - # Returns the text with all the Textile codes turned into HTML tags. + # Returns the text with all the Textile[http://www.textism.com/tools/textile] codes turned into HTML tags. + # + # You can learn more about Textile's syntax at its website[http://www.textism.com/tools/textile]. # <i>This method is only available if RedCloth[http://whytheluckystiff.net/ruby/redcloth/] # is available</i>. + # + # ==== Examples + # textilize("*This is Textile!* Rejoice!") + # # => "<p><strong>This is Textile!</strong> Rejoice!</p>" + # + # textilize("I _love_ ROR(Ruby on Rails)!") + # # => "<p>I <em>love</em> <acronym title="Ruby on Rails">ROR</acronym>!</p>" + # + # textilize("h2. Textile makes markup -easy- simple!") + # # => "<h2>Textile makes markup <del>easy</del> simple!</h2>" + # + # textilize("Visit the Rails website "here":http://www.rubyonrails.org/.) + # # => "<p>Visit the Rails website <a href="http://www.rubyonrails.org/">here</a>.</p>" def textilize(text) if text.blank? "" @@ -131,8 +197,23 @@ module ActionView # Returns the text with all the Textile codes turned into HTML tags, # but without the bounding <p> tag that RedCloth adds. + # + # You can learn more about Textile's syntax at its website[http://www.textism.com/tools/textile]. # <i>This method is only available if RedCloth[http://whytheluckystiff.net/ruby/redcloth/] # is available</i>. + # + # ==== Examples + # textilize_without_paragraph("*This is Textile!* Rejoice!") + # # => "<strong>This is Textile!</strong> Rejoice!" + # + # textilize_without_paragraph("I _love_ ROR(Ruby on Rails)!") + # # => "I <em>love</em> <acronym title="Ruby on Rails">ROR</acronym>!" + # + # textilize_without_paragraph("h2. Textile makes markup -easy- simple!") + # # => "<h2>Textile makes markup <del>easy</del> simple!</h2>" + # + # textilize_without_paragraph("Visit the Rails website "here":http://www.rubyonrails.org/.) + # # => "Visit the Rails website <a href="http://www.rubyonrails.org/">here</a>." def textilize_without_paragraph(text) textiled = textilize(text) if textiled[0..2] == "<p>" then textiled = textiled[3..-1] end @@ -149,6 +230,20 @@ module ActionView # Returns the text with all the Markdown codes turned into HTML tags. # <i>This method is only available if BlueCloth[http://www.deveiate.org/projects/BlueCloth] # is available</i>. + # + # ==== Examples + # markdown("We are using __Markdown__ now!") + # # => "<p>We are using <strong>Markdown</strong> now!</p>" + # + # markdown("We like to _write_ `code`, not just _read_ it!") + # # => "<p>We like to <em>write</em> <code>code</code>, not just <em>read</em> it!</p>" + # + # markdown("The [Markdown website](http://daringfireball.net/projects/markdown/) has more information.") + # # => "<p>The <a href="http://daringfireball.net/projects/markdown/">Markdown website</a> + # # has more information.</p>" + # + # markdown('') + # # => '<p><img src="http://rubyonrails.com/images/rails.png" alt="The ROR logo" title="Ruby on Rails" /></p>' def markdown(text) text.blank? ? "" : BlueCloth.new(text).to_html end @@ -161,6 +256,20 @@ module ActionView # paragraph and wrapped in <tt><p></tt> tags. One newline (<tt>\n</tt>) is # considered as a linebreak and a <tt><br /></tt> tag is appended. This # method does not remove the newlines from the +text+. + # + # ==== Examples + # my_text = """Here is some basic text... + # ...with a line break.""" + # + # simple_format(my_text) + # # => "<p>Here is some basic text...<br />...with a line break.</p>" + # + # more_text = """We want to put a paragraph... + # + # ...right there.""" + # + # simple_format(more_text) + # # => "<p>We want to put a paragraph...</p><p>...right there.</p>" def simple_format(text) content_tag 'p', text.to_s. gsub(/\r\n?/, "\n"). # \r\n and \r -> \n @@ -168,21 +277,31 @@ module ActionView gsub(/([^\n]\n)(?=[^\n])/, '\1<br />') # 1 newline -> br end - # Turns all urls and email addresses into clickable links. The +link+ parameter - # will limit what should be linked. You can add html attributes to the links using + # Turns all URLs and e-mail addresses into clickable links. The +link+ parameter + # will limit what should be linked. You can add HTML attributes to the links using # +href_options+. Options for +link+ are <tt>:all</tt> (default), - # <tt>:email_addresses</tt>, and <tt>:urls</tt>. + # <tt>:email_addresses</tt>, and <tt>:urls</tt>. If a block is given, each URL and + # e-mail address is yielded and the result is used as the link text. + # + # ==== Examples + # auto_link("Go to http://www.rubyonrails.org and say hello to david@loudthinking.com") + # # => "Go to <a href="http://www.rubyonrails.org">http://www.rubyonrails.org</a> and + # # say hello to <a href="mailto:david@loudthinking.com">david@loudthinking.com</a>" # - # auto_link("Go to http://www.rubyonrails.org and say hello to david@loudthinking.com") => - # Go to <a href="http://www.rubyonrails.org">http://www.rubyonrails.org</a> and - # say hello to <a href="mailto:david@loudthinking.com">david@loudthinking.com</a> + # auto_link("Visit http://www.loudthinking.com/ or e-mail david@loudthinking.com", :urls) + # # => "Visit <a href=\"http://www.loudthinking.com/\">http://www.loudthinking.com/</a> + # # or e-mail david@loudthinking.com" # - # If a block is given, each url and email address is yielded and the - # result is used as the link text. + # auto_link("Visit http://www.loudthinking.com/ or e-mail david@loudthinking.com", :email_addresses) + # # => "Visit http://www.loudthinking.com/ or e-mail <a href=\"mailto:david@loudthinking.com\">david@loudthinking.com</a>" # - # auto_link(post.body, :all, :target => '_blank') do |text| + # post_body = "Welcome to my new blog at http://www.myblog.com/. Please e-mail me at me@email.com." + # auto_link(post_body, :all, :target => '_blank') do |text| # truncate(text, 15) # end + # # => "Welcome to my new blog at <a href=\"http://www.myblog.com/\" target=\"_blank\">http://www.m...</a>. + # Please e-mail me at <a href=\"mailto:me@email.com\">me@email.com</a>." + # def auto_link(text, link = :all, href_options = {}, &block) return '' if text.blank? case link @@ -192,10 +311,17 @@ module ActionView end end - # Strips link tags from +text+ leaving just the link label. + # Strips all link tags from +text+ leaving just the link text. # + # ==== Examples # strip_links('<a href="http://www.rubyonrails.org">Ruby on Rails</a>') - # => Ruby on Rails + # # => Ruby on Rails + # + # strip_links('Please e-mail me at <a href="mailto:me@email.com">me@email.com</a>.') + # # => Please e-mail me at me@email.com. + # + # strip_links('Blog: <a href="http://www.myblog.com/" class="nav" target=\"_blank\">Visit</a>.') + # # => Blog: Visit def strip_links(text) text.gsub(/<a\b.*?>(.*?)<\/a>/mi, '\1') end @@ -204,15 +330,23 @@ module ActionView VERBOTEN_ATTRS = /^on/i unless defined?(VERBOTEN_ATTRS) # Sanitizes the +html+ by converting <form> and <script> tags into regular - # text, and removing all "onxxx" attributes (so that arbitrary Javascript - # cannot be executed). It also removes href= and src= attributes that start with + # text, and removing all "on*" (e.g., onClick) attributes so that arbitrary Javascript + # cannot be executed. It also removes <tt>href</tt> and <tt>src</tt> attributes that start with # "javascript:". You can modify what gets sanitized by defining VERBOTEN_TAGS # and VERBOTEN_ATTRS before this Module is loaded. # + # ==== Examples # sanitize('<script> do_nasty_stuff() </script>') - # => <script> do_nasty_stuff() </script> + # # => <script> do_nasty_stuff() </script> + # # sanitize('<a href="javascript: sucker();">Click here for $100</a>') - # => <a>Click here for $100</a> + # # => <a>Click here for $100</a> + # + # sanitize('<a href="#" onClick="kill_all_humans();">Click here!!!</a>') + # # => <a href="#">Click here!!!</a> + # + # sanitize('<img src="javascript:suckers_run_this();" />') + # # => <img /> def sanitize(html) # only do this if absolutely necessary if html.index("<") @@ -248,6 +382,16 @@ module ActionView # Strips all HTML tags from the +html+, including comments. This uses the # html-scanner tokenizer and so its HTML parsing ability is limited by # that of html-scanner. + # + # ==== Examples + # strip_tags("Strip <i>these</i> tags!") + # # => Strip these tags! + # + # strip_tags("<b>Bold</b> no more! <a href='more.html'>See more here</a>...") + # # => Bold no more! See more here... + # + # strip_tags("<div id='top-bar'>Welcome to my website!</div>") + # # => Welcome to my website! def strip_tags(html) return html if html.blank? if html.index("<") @@ -269,25 +413,34 @@ module ActionView # Creates a Cycle object whose _to_s_ method cycles through elements of an # array every time it is called. This can be used for example, to alternate - # classes for table rows: + # classes for table rows. You can use named cycles to allow nesting in loops. + # Passing a Hash as the last parameter with a <tt>:name</tt> key will create a + # named cycle. You can manually reset a cycle by calling reset_cycle and passing the + # name of the cycle. # + # ==== Examples + # # Alternate CSS classes for even and odd numbers... + # @items = [1,2,3,4] + # <table> # <% @items.each do |item| %> # <tr class="<%= cycle("even", "odd") -%>"> # <td>item</td> # </tr> # <% end %> + # </table> # - # You can use named cycles to allow nesting in loops. Passing a Hash as - # the last parameter with a <tt>:name</tt> key will create a named cycle. - # You can manually reset a cycle by calling reset_cycle and passing the - # name of the cycle. # + # # Cycle CSS classes for rows, and text colors for values within each row + # @items = x = [{:first => 'Robert', :middle => 'Daniel', :last => 'James'}, + # {:first => 'Emily', :middle => 'Shannon', :maiden => 'Pike', :last => 'Hicks'}, + # {:first => 'June', :middle => 'Dae', :last => 'Jones'}] # <% @items.each do |item| %> # <tr class="<%= cycle("even", "odd", :name => "row_class") # <td> # <% item.values.each do |value| %> + # <!-- Create a named cycle "colors" --> # <span style="color:<%= cycle("red", "green", "blue", :name => "colors") -%>"> - # value + # <%= value %> # </span> # <% end %> # <% reset_cycle("colors") %> @@ -312,6 +465,23 @@ module ActionView # Resets a cycle so that it starts from the first element the next time # it is called. Pass in +name+ to reset a named cycle. + # + # ==== Example + # # Alternate CSS classes for even and odd numbers... + # @items = [[1,2,3,4], [5,6,3], [3,4,5,6,7,4]] + # <table> + # <% @items.each do |item| %> + # <tr class="<%= cycle("even", "odd") -%>"> + # <% item.each do |value| %> + # <span style="color:<%= cycle("#333", "#666", "#999", :name => "colors") -%>"> + # <%= value %> + # </span> + # <% end %> + # + # <% reset_cycle("colors") %> + # </tr> + # <% end %> + # </table> def reset_cycle(name = "default") cycle = get_cycle(name) cycle.reset unless cycle.nil? |