Module: ActionView::Helpers::TextHelper

Module | ActionView::Helpers::TextHelper
In: | 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

auto_link concat cycle excerpt highlight markdown pluralize reset_cycle simple_format textilize textilize_without_paragraph truncate word_wrap

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

auto_link(text, link = :all, href_options = {}, &block)

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 `: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", :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", :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, :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>."

concat(string, binding)

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

cycle(first_value, *values)

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

      # 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 %>

excerpt(text, phrase, radius = 100, excerpt_string = "...")

Extracts an excerpt from `text` that matches the first instance of `phrase`. The `radius` 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 `excerpt_string` 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', 5)
      # => "...s is an exam..."

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

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

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

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

highlight(text, phrases, highlighter = '<strong class="highlight">\1</strong>')

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'], '<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>

markdown(text)

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

pluralize(count, singular, plural = nil)

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

reset_cycle(name = "default")

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>

simple_format(text, html_options={})

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

textilize(text)

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

textilize_without_paragraph(text)

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

truncate(text, length = 30, truncate_string = "...")

If `text` is longer than `length`, `text` will be truncated to the length of `length` (defaults to 30) and the last 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...

      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)

word_wrap(text, line_width = 80)

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', 4)
      # => 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

[Validate]