diff --git a/actionpack/lib/action_view/helpers/text_helper.rb b/actionpack/lib/action_view/helpers/text_helper.rb index 33d86441ef4034e16abaa5b637b4664cd54856ed..f1d67c53bba89bef04fa5109cc67ccfba240964d 100644 --- a/actionpack/lib/action_view/helpers/text_helper.rb +++ b/actionpack/lib/action_view/helpers/text_helper.rb @@ -2,40 +2,63 @@ module ActionView module Helpers #:nodoc: - # Provides a set of methods for working with text strings that can help unburden the level of inline Ruby code in the - # templates. In the example below we iterate over a collection of posts provided to the template and print each title - # after making sure it doesn't run longer than 20 characters: - # <% for post in @posts %> - # Title: <%= truncate(post.title, 20) %> + # The TextHelper Module provides a set of methods for filtering, formatting + # and transforming strings that 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... module TextHelper - # The regular puts and print are outlawed in eRuby. It's recommended to use the <%= "hello" %> form instead of print "hello". - # If you absolutely must use a method-based output, you can use concat. It's used like this: <% concat "hello", binding %>. Notice that - # it doesn't have an equal sign in front. Using <%= concat "hello" %> would result in a double hello. + # 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. + # + # <% concat "hello", binding %> + # is equivalent to using: + # <%= "hello" %> def concat(string, binding) eval("_erbout", binding).concat(string) end - # Truncates +text+ to the length of +length+ and replaces the last three characters with the +truncate_string+ - # if the +text+ is longer than +length+. + # 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+. + # + # truncate("Once upon a time in a world far far away", 14) + # => Once upon a... def truncate(text, length = 30, truncate_string = "...") if text.nil? then return end l = length - truncate_string.chars.length text.chars.length > length ? text.chars[0...l] + truncate_string : text end - # Highlights the +phrase+ where it is found in the +text+ by surrounding it like - # I'm a highlight phrase. The highlighter can be specialized by - # passing +highlighter+ as single-quoted string with \1 where the phrase is supposed to be inserted. - # N.B.: The +phrase+ is sanitized to include only letters, digits, and spaces before use. + # Highlights +phrase+ everywhere it is found 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. + # + # highlight('You searched for: rails', 'rails') + # => You searched for: rails def highlight(text, phrase, highlighter = '\1') if phrase.blank? then return text end text.gsub(/(#{Regexp.escape(phrase)})/i, highlighter) unless text.nil? end - # Extracts an excerpt from the +text+ surrounding the +phrase+ with a number of characters on each side determined - # by +radius+. If the phrase isn't found, nil is returned. Ex: - # excerpt("hello my world", "my", 3) => "...lo my wo..." + # 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+, + # then the +excerpt_string+ will be prepended/appended accordingly. If the +phrase+ + # isn't found, nil is returned. + # + # excerpt('This is an example', 'an', 5) + # => "...s is an examp..." + # + # excerpt('This is an example', 'is', 5) + # => "This is an..." def excerpt(text, phrase, radius = 100, excerpt_string = "...") if text.nil? || phrase.nil? then return end phrase = Regexp.escape(phrase) @@ -53,7 +76,14 @@ def excerpt(text, phrase, radius = 100, excerpt_string = "...") end end - # Attempts to pluralize the +singular+ word unless +count+ is 1. See source for pluralization rules. + # Attempts to pluralize the +singular+ word unless +count+ is 1. If +plural+ + # is supplied, it will use that when count is > 1, if the ActiveSupport Inflector + # 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 def pluralize(count, singular, plural = nil) "#{count} " + if count == 1 || count == '1' singular @@ -66,7 +96,11 @@ def pluralize(count, singular, plural = nil) end end - # Word wrap long lines to line_width. + # 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+. + # + # word_wrap('Once upon a time', 4) + # => 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 @@ -74,8 +108,9 @@ def word_wrap(text, line_width = 80) begin require_library_or_gem "redcloth" unless Object.const_defined?(:RedCloth) - # Returns the text with all the Textile codes turned into HTML-tags. - # This method is only available if RedCloth can be required. + # Returns the text with all the Textile codes turned into HTML tags. + # This method is only available if RedCloth[http://whytheluckystiff.net/ruby/redcloth/] + # is available. def textilize(text) if text.blank? "" @@ -86,8 +121,10 @@ def textilize(text) end end - # Returns the text with all the Textile codes turned into HTML-tags, but without the regular bounding
tag. - # This method is only available if RedCloth can be required. + # Returns the text with all the Textile codes turned into HTML tags, + # but without the bounding
tag that RedCloth adds. + # This method is only available if RedCloth[http://whytheluckystiff.net/ruby/redcloth/] + # is available. def textilize_without_paragraph(text) textiled = textilize(text) if textiled[0..2] == "
" then textiled = textiled[3..-1] end @@ -101,8 +138,9 @@ def textilize_without_paragraph(text) begin require_library_or_gem "bluecloth" unless Object.const_defined?(:BlueCloth) - # Returns the text with all the Markdown codes turned into HTML-tags. - # This method is only available if BlueCloth can be required. + # Returns the text with all the Markdown codes turned into HTML tags. + # This method is only available if BlueCloth[http://www.deveiate.org/projects/BlueCloth] + # is available. def markdown(text) text.blank? ? "" : BlueCloth.new(text).to_html end @@ -110,12 +148,13 @@ def markdown(text) # We can't really help what's not there end - # Returns +text+ transformed into HTML using very simple formatting rules - # Surrounds paragraphs with
tags, and converts line breaks into
- # Two consecutive newlines(\n\n) are considered as a paragraph, one newline (\n) is
- # considered a linebreak, three or more consecutive newlines are turned into two newlines
+ # Returns +text+ transformed into HTML using simple formatting rules.
+ # Two or more consecutive newlines(\n\n) are considered as a
+ # paragraph and wrapped in
tags. One newline (\n) is
+ # considered as a linebreak and a
tag is appended. This
+ # method does not remove the newlines from the +text+.
def simple_format(text)
- text.gsub!(/(\r\n|\n|\r)/, "\n") # lets make them newlines crossplatform
+ text = text.gsub(/(\r\n|\n|\r)/, "\n") # lets make them newlines crossplatform
text.gsub!(/\n\n+/, "\n\n") # zap dupes
text.gsub!(/\n\n/, '
') # turn two newlines into paragraph
text.gsub!(/([^\n])(\n)(?=[^\n])/, '\1\2
') # turn single newline into
@@ -123,16 +162,18 @@ def simple_format(text)
content_tag("p", text)
end
- # Turns all urls and email addresses into clickable links. The +link+ parameter can limit what should be linked.
- # Options are :all (default), :email_addresses, and :urls.
+ # 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
+ # +href_options+. Options for +link+ are :all (default),
+ # :email_addresses, and :urls.
#
- # Example:
- # auto_link("Go to http://www.rubyonrails.com and say hello to david@loudthinking.com") =>
- # Go to http://www.rubyonrails.com and
+ # auto_link("Go to http://www.rubyonrails.org and say hello to david@loudthinking.com") =>
+ # Go to http://www.rubyonrails.org and
# say hello to david@loudthinking.com
#
# If a block is given, each url and email address is yielded and the
- # result is used as the link text. Example:
+ # result is used as the link text.
+ #
# auto_link(post.body, :all, :target => '_blank') do |text|
# truncate(text, 15)
# end
@@ -145,7 +186,10 @@ def auto_link(text, link = :all, href_options = {}, &block)
end
end
- # Turns all links into words, like "else" to "else".
+ # Strips link tags from +text+ leaving just the link label.
+ #
+ # strip_links('Ruby on Rails')
+ # => Ruby on Rails
def strip_links(text)
text.gsub(/(.*?)<\/a>/mi, '\1')
end
@@ -156,7 +200,7 @@ def strip_links(text)
require 'html/node'
rescue LoadError
# if there isn't a copy installed, use the vendor version in
- # action controller
+ # ActionController
$:.unshift File.join(File.dirname(__FILE__), "..", "..",
"action_controller", "vendor", "html-scanner")
require 'html/tokenizer'
@@ -166,12 +210,16 @@ def strip_links(text)
VERBOTEN_TAGS = %w(form script plaintext) unless defined?(VERBOTEN_TAGS)
VERBOTEN_ATTRS = /^on/i unless defined?(VERBOTEN_ATTRS)
- # Sanitizes the given HTML by making form and script tags into regular
+ # Sanitizes the +html+ by converting