Module ActionView::Helpers::TextHelper
In: vendor/rails/actionpack/lib/action_view/helpers/text_helper.rb

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.

Methods

Constants

AUTO_LINK_RE = %r{ ( # leading text <\w+.*?>| # leading HTML tag, or [^=!:'"/]| # leading punctuation, or ^ # beginning of line ) ( (?:https?://)| # protocol spec, or (?:www\.) # www.* ) ( [-\w]+ # subdomain or domain (?:\.[-\w]+)* # remaining subdomains or domain (?::\d+)? # port (?:/(?:[~\w\+@%=\(\)-]|(?:[,.;:'][^\s$]))*)* # path (?:\?[\w\+@%&=.;:-]+)? # query string (?:\#[\w\-]*)? # trailing anchor ) ([[:punct:]]|<|$|) # trailing text }x unless const_defined?(:AUTO_LINK_RE)

Public Instance methods

Turns all URLs and e-mail addresses into clickable links. The :link option will limit what should be linked. You can add HTML attributes to the links using :href_options. Possible values for :link are :all (default), :email_addresses, and :urls. 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("Visit http://www.loudthinking.com/ or e-mail david@loudthinking.com", :link => :urls)
  # => "Visit <a href=\"http://www.loudthinking.com/\">http://www.loudthinking.com/</a>
  #     or e-mail david@loudthinking.com"

  auto_link("Visit http://www.loudthinking.com/ or e-mail david@loudthinking.com", :link => :email_addresses)
  # => "Visit http://www.loudthinking.com/ or e-mail <a href=\"mailto:david@loudthinking.com\">david@loudthinking.com</a>"

  post_body = "Welcome to my new blog at http://www.myblog.com/.  Please e-mail me at me@email.com."
  auto_link(post_body, :href_options => { :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>."

You can still use auto_link with the old API that accepts the link as its optional second parameter and the html_options hash as its optional third parameter:

  post_body = "Welcome to my new blog at http://www.myblog.com/. Please e-mail me at me@email.com."
  auto_link(post_body, :urls)     # => Once upon\na time
  # => "Welcome to my new blog at <a href=\"http://www.myblog.com/\">http://www.myblog.com</a>.
        Please e-mail me at me@email.com."

  auto_link(post_body, :all, :target => "_blank")     # => Once upon\na time
  # => "Welcome to my new blog at <a href=\"http://www.myblog.com/\" target=\"_blank\">http://www.myblog.com</a>.
        Please e-mail me at <a href=\"mailto:me@email.com\">me@email.com</a>."

[Source]

     # File vendor/rails/actionpack/lib/action_view/helpers/text_helper.rb, line 384
384:       def auto_link(text, *args, &block)#link = :all, href_options = {}, &block)
385:         return '' if text.blank?
386: 
387:         options = args.size == 2 ? {} : args.extract_options! # this is necessary because the old auto_link API has a Hash as its last parameter
388:         unless args.empty?
389:           options[:link] = args[0] || :all
390:           options[:html] = args[1] || {}
391:         end
392:         options.reverse_merge!(:link => :all, :html => {})
393: 
394:         case options[:link].to_sym
395:           when :all                         then auto_link_email_addresses(auto_link_urls(text, options[:html], &block), &block)
396:           when :email_addresses             then auto_link_email_addresses(text, &block)
397:           when :urls                        then auto_link_urls(text, options[:html], &block)
398:         end
399:       end

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 non-output code block (i.e., <% %>), you can use the concat method.

Examples

  <%
      concat "hello"
      # is the equivalent of <%= "hello" %>

      if (logged_in == true):
        concat "Logged in!"
      else
        concat link_to('login', :action => login)
      end
      # will either display "Logged in!" or a login link
  %>

[Source]

    # File vendor/rails/actionpack/lib/action_view/helpers/text_helper.rb, line 37
37:       def concat(string, unused_binding = nil)
38:         if unused_binding
39:           ActiveSupport::Deprecation.warn("The binding argument of #concat is no longer needed.  Please remove it from your views and helpers.", caller)
40:         end
41: 
42:         output_buffer << string
43:       end

Returns the current cycle string after a cycle has been started. Useful for complex table highlighing or any other design need which requires the current cycle string in more than one place.

Example

  # Alternate background colors
  @items = [1,2,3,4]
  <% @items.each do |item| %>
    <div style="background-color:<%= cycle("red","white","blue") %>">
      <span style="background-color:<%= current_cycle %>"><%= item %></span>
    </div>
  <% end %>

[Source]

     # File vendor/rails/actionpack/lib/action_view/helpers/text_helper.rb, line 467
467:       def current_cycle(name = "default")
468:         cycle = get_cycle(name)
469:         cycle.current_value unless cycle.nil?
470:       end

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. You can use named cycles to allow nesting in loops. Passing a Hash as the last parameter with a :name key will create a named cycle. The default name for a cycle without a +:name+ key is "default". You can manually reset a cycle by calling reset_cycle and passing the name of the cycle. The current cycle string can be obtained anytime using the current_cycle method.

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>

  # 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 %>
          </span>
        <% end %>
        <% reset_cycle("colors") %>
      </td>
   </tr>
 <% end %>

[Source]

     # File vendor/rails/actionpack/lib/action_view/helpers/text_helper.rb, line 439
439:       def cycle(first_value, *values)
440:         if (values.last.instance_of? Hash)
441:           params = values.pop
442:           name = params[:name]
443:         else
444:           name = "default"
445:         end
446:         values.unshift(first_value)
447: 
448:         cycle = get_cycle(name)
449:         if (cycle.nil? || cycle.values != values)
450:           cycle = set_cycle(name, Cycle.new(*values))
451:         end
452:         return cycle.to_s
453:       end

Extracts an excerpt from text that matches the first instance of phrase. The :radius option expands the excerpt on each side of the first occurrence 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 :omission option (which defaults to "…") will be prepended/appended accordingly. The resulting string will be stripped in any case. If the phrase isn‘t found, nil is returned.

Examples

  excerpt('This is an example', 'an', :radius => 5)
  # => ...s is an exam...

  excerpt('This is an example', 'is', :radius => 5)
  # => This is a...

  excerpt('This is an example', 'is')
  # => This is an example

  excerpt('This next thing is an example', 'ex', :radius => 2)
  # => ...next...

  excerpt('This is also an example', 'an', :radius => 8, :omission => '<chop> ')
  # => <chop> is also an example

You can still use excerpt with the old API that accepts the radius as its optional third and the ellipsis as its optional forth parameter:

  excerpt('This is an example', 'an', 5)                   # => ...s is an exam...
  excerpt('This is also an example', 'an', 8, '<chop> ')   # => <chop> is also an example

[Source]

     # File vendor/rails/actionpack/lib/action_view/helpers/text_helper.rb, line 151
151:       def excerpt(text, phrase, *args)
152:         options = args.extract_options!
153:         unless args.empty?
154:           options[:radius] = args[0] || 100
155:           options[:omission] = args[1] || "..."
156:         end
157:         options.reverse_merge!(:radius => 100, :omission => "...")
158: 
159:         if text && phrase
160:           phrase = Regexp.escape(phrase)
161: 
162:           if found_pos = text.mb_chars =~ /(#{phrase})/i
163:             start_pos = [ found_pos - options[:radius], 0 ].max
164:             end_pos   = [ [ found_pos + phrase.mb_chars.length + options[:radius] - 1, 0].max, text.mb_chars.length ].min
165: 
166:             prefix  = start_pos > 0 ? options[:omission] : ""
167:             postfix = end_pos < text.mb_chars.length - 1 ? options[:omission] : ""
168: 
169:             prefix + text.mb_chars[start_pos..end_pos].strip + postfix
170:           else
171:             nil
172:           end
173:         end
174:       end

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 (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'], :highlighter => '<em>\1</em>')
  # => You searched <em>for</em>: <em>rails</em>

  highlight('You searched for: rails', 'rails', :highlighter => '<a href="search?q=\1">\1</a>')
  # => You searched for: <a href="search?q=rails">rails</a>

You can still use highlight with the old API that accepts the highlighter as its optional third parameter:

  highlight('You searched for: rails', 'rails', '<a href="search?q=\1">\1</a>')     # => You searched for: <a href="search?q=rails">rails</a>

[Source]

     # File vendor/rails/actionpack/lib/action_view/helpers/text_helper.rb, line 109
109:       def highlight(text, phrases, *args)
110:         options = args.extract_options!
111:         unless args.empty?
112:           options[:highlighter] = args[0] || '<strong class="highlight">\1</strong>'
113:         end
114:         options.reverse_merge!(:highlighter => '<strong class="highlight">\1</strong>')
115: 
116:         if text.blank? || phrases.blank?
117:           text
118:         else
119:           match = Array(phrases).map { |p| Regexp.escape(p) }.join('|')
120:           text.gsub(/(#{match})/i, options[:highlighter])
121:         end
122:       end

Returns the text with all the Markdown codes turned into HTML tags. This method is only available if BlueCloth is available.

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('![The ROR logo](http://rubyonrails.com/images/rails.png "Ruby on Rails")')
  # => '<p><img src="http://rubyonrails.com/images/rails.png" alt="The ROR logo" title="Ruby on Rails" /></p>'

[Source]

     # File vendor/rails/actionpack/lib/action_view/helpers/text_helper.rb, line 309
309:         def markdown(text)
310:           text.blank? ? "" : BlueCloth.new(text).to_html
311:         end

Attempts to pluralize the singular word unless count is 1. If plural is supplied, it will use that when count is > 1, otherwise it will use the Inflector to determine the plural form

Examples

  pluralize(1, 'person')
  # => 1 person

  pluralize(2, 'person')
  # => 2 people

  pluralize(3, 'person', 'users')
  # => 3 users

  pluralize(0, 'person')
  # => 0 people

[Source]

     # File vendor/rails/actionpack/lib/action_view/helpers/text_helper.rb, line 192
192:       def pluralize(count, singular, plural = nil)
193:         "#{count || 0} " + ((count == 1 || count == '1') ? singular : (plural || singular.pluralize))
194:       end

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>

[Source]

     # File vendor/rails/actionpack/lib/action_view/helpers/text_helper.rb, line 491
491:       def reset_cycle(name = "default")
492:         cycle = get_cycle(name)
493:         cycle.reset unless cycle.nil?
494:       end

Returns text transformed into HTML using simple formatting rules. Two or more consecutive newlines(\n\n) are considered as a paragraph and wrapped in <p> tags. One newline (\n) is considered as a linebreak and a <br /> tag is appended. This method does not remove the newlines from the text.

You can pass any HTML attributes into html_options. These will be added to all created paragraphs.

Examples

  my_text = "Here is some basic text...\n...with a line break."

  simple_format(my_text)
  # => "<p>Here is some basic text...\n<br />...with a line break.</p>"

  more_text = "We want to put a paragraph...\n\n...right there."

  simple_format(more_text)
  # => "<p>We want to put a paragraph...</p>\n\n<p>...right there.</p>"

  simple_format("Look ma! A class!", :class => 'description')
  # => "<p class='description'>Look ma! A class!</p>"

[Source]

     # File vendor/rails/actionpack/lib/action_view/helpers/text_helper.rb, line 337
337:       def simple_format(text, html_options={})
338:         start_tag = tag('p', html_options, true)
339:         text = text.to_s.dup
340:         text.gsub!(/\r\n?/, "\n")                    # \r\n and \r -> \n
341:         text.gsub!(/\n\n+/, "</p>\n\n#{start_tag}")  # 2+ newline  -> paragraph
342:         text.gsub!(/([^\n]\n)(?=[^\n])/, '\1<br />') # 1 newline   -> br
343:         text.insert 0, start_tag
344:         text << "</p>"
345:       end

Returns the text with all the Textile codes turned into HTML tags.

You can learn more about Textile‘s syntax at its website. This method is only available if RedCloth is available.

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>"

[Source]

     # File vendor/rails/actionpack/lib/action_view/helpers/text_helper.rb, line 250
250:         def textilize(text)
251:           if text.blank?
252:             ""
253:           else
254:             textilized = RedCloth.new(text, [ :hard_breaks ])
255:             textilized.hard_breaks = true if textilized.respond_to?(:hard_breaks=)
256:             textilized.to_html
257:           end
258:         end

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. This method is only available if RedCloth is available.

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>."

[Source]

     # File vendor/rails/actionpack/lib/action_view/helpers/text_helper.rb, line 279
279:         def textilize_without_paragraph(text)
280:           textiled = textilize(text)
281:           if textiled[0..2] == "<p>" then textiled = textiled[3..-1] end
282:           if textiled[-4..-1] == "</p>" then textiled = textiled[0..-5] end
283:           return textiled
284:         end

Truncates a given text after a given :length if text is longer than :length (defaults to 30). The last characters will be replaced with the :omission (defaults to "…").

Examples

  truncate("Once upon a time in a world far far away")
  # => Once upon a time in a world f...

  truncate("Once upon a time in a world far far away", :length => 14)
  # => Once upon a...

  truncate("And they found that many people were sleeping better.", :length => 25, "(clipped)")
  # => And they found that many (clipped)

  truncate("And they found that many people were sleeping better.", :omission => "... (continued)", :length => 15)
  # => And they found... (continued)

You can still use truncate with the old API that accepts the length as its optional second and the ellipsis as its optional third parameter:

  truncate("Once upon a time in a world far far away", 14)
  # => Once upon a time in a world f...

  truncate("And they found that many people were sleeping better.", 15, "... (continued)")
  # => And they found... (continued)

[Source]

    # File vendor/rails/actionpack/lib/action_view/helpers/text_helper.rb, line 70
70:       def truncate(text, *args)
71:         options = args.extract_options!
72:         unless args.empty?
73:           ActiveSupport::Deprecation.warn('truncate takes an option hash instead of separate ' +
74:             'length and omission arguments', caller)
75: 
76:           options[:length] = args[0] || 30
77:           options[:omission] = args[1] || "..."
78:         end
79:         options.reverse_merge!(:length => 30, :omission => "...")
80: 
81:         if text
82:           l = options[:length] - options[:omission].mb_chars.length
83:           chars = text.mb_chars
84:           (chars.length > options[:length] ? chars[0...l] + options[:omission] : text).to_s
85:         end
86:       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 (which is 80 by default).

Examples

  word_wrap('Once upon a time')
  # => Once upon a time

  word_wrap('Once upon a time, in a kingdom called Far Far Away, a king fell ill, and finding a successor to the throne turned out to be more trouble than anyone could have imagined...')
  # => Once upon a time, in a kingdom called Far Far Away, a king fell ill, and finding\n a successor to the throne turned out to be more trouble than anyone could have\n imagined...

  word_wrap('Once upon a time', :line_width => 8)
  # => Once upon\na time

  word_wrap('Once upon a time', :line_width => 1)
  # => Once\nupon\na\ntime

You can still use word_wrap with the old API that accepts the line_width as its optional second parameter:

  word_wrap('Once upon a time', 8)     # => Once upon\na time

[Source]

     # File vendor/rails/actionpack/lib/action_view/helpers/text_helper.rb, line 217
217:       def word_wrap(text, *args)
218:         options = args.extract_options!
219:         unless args.blank?
220:           options[:line_width] = args[0] || 80
221:         end
222:         options.reverse_merge!(:line_width => 80)
223: 
224:         text.split("\n").collect do |line|
225:           line.length > options[:line_width] ? line.gsub(/(.{1,#{options[:line_width]}})(\s+|$)/, "\\1\n").strip : line
226:         end * "\n"
227:       end

[Validate]