Skip to Content Skip to Search

module ActionView::Helpers::TextHelper

Action View Text Helpers

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 Action View making them callable within your template files.

Sanitization

Most text helpers that generate HTML output sanitize the given input by default, but do not escape it. This means HTML tags will appear in the page but all malicious code will be removed. Let’s look at some examples using the simple_format method:

simple_format('<a href="http://example.com/">Example</a>')
# => "<p><a href=\"http://example.com/\">Example</a></p>"

simple_format('<a href="javascript:alert(\'no!\')">Example</a>')
# => "<p><a>Example</a></p>"

If you want to escape all content, you should invoke the h method before calling the text helper.

simple_format h('<a href="http://example.com/">Example</a>')
# => "<p>&lt;a href=\"http://example.com/\"&gt;Example&lt;/a&gt;</p>"

Inherits From

Public instance methods

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.

<% concat "hello" %> is equivalent to <%= "hello" %>

<%
   unless signed_in?
     concat link_to("Sign In", action: :sign_in)
   end
%>

is equivalent to

<% unless signed_in? %>
  <%= link_to "Sign In", action: :sign_in %>
<% end %>
Source code GitHub
# File actionview/lib/action_view/helpers/text_helper.rb, line 63
def concat(string)
  output_buffer << string
end

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

<%# 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 code GitHub
# File actionview/lib/action_view/helpers/text_helper.rb, line 454
def current_cycle(name = "default")
  cycle = get_cycle(name)
  cycle.current_value if cycle
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.

 <%# Alternate CSS classes for even and odd numbers... %>
 <% @items = [1,2,3,4] %>
 <table>
 <% @items.each do |item| %>
   <tr class="<%= cycle("odd", "even") -%>">
     <td><%= item %></td>
   </tr>
 <% end %>
 </table>

 <%# Cycle CSS classes for rows, and text colors for values within each row %>
 <% @items = [
   { 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("odd", "even", 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 code GitHub
# File actionview/lib/action_view/helpers/text_helper.rb, line 430
def cycle(first_value, *values)
  options = values.extract_options!
  name = options.fetch(:name, "default")

  values.unshift(*first_value)

  cycle = get_cycle(name)
  unless cycle && cycle.values == values
    cycle = set_cycle(name, Cycle.new(*values))
  end
  cycle.to_s
end

Extracts the first occurrence of phrase plus surrounding text from text. An omission marker is prepended / appended if the start / end of the result does not coincide with the start / end of text. The result is always stripped in any case. Returns nil if phrase isn’t found.

Options

:radius

The number of characters (or tokens — see :separator option) around phrase to include in the result. Defaults to 100.

:omission

The marker to prepend / append when the start / end of the excerpt does not coincide with the start / end of text. Defaults to "...".

:separator

The separator between tokens to count for :radius. Defaults to "", which treats each character as a token.

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"

excerpt('This is a very beautiful morning', 'very', separator: ' ', radius: 1)
# => "...a very beautiful..."
Source code GitHub
# File actionview/lib/action_view/helpers/text_helper.rb, line 235
def excerpt(text, phrase, options = {})
  return unless text && phrase

  separator = options.fetch(:separator, nil) || ""
  case phrase
  when Regexp
    regex = phrase
  else
    regex = /#{Regexp.escape(phrase)}/i
  end

  return unless matches = text.match(regex)
  phrase = matches[0]

  unless separator.empty?
    text.split(separator).each do |value|
      if value.match?(regex)
        phrase = value
        break
      end
    end
  end

  first_part, second_part = text.split(phrase, 2)

  prefix, first_part   = cut_excerpt_part(:first, first_part, separator, options)
  postfix, second_part = cut_excerpt_part(:second, second_part, separator, options)

  affix = [first_part, separator, phrase, separator, second_part].join.strip
  [prefix, affix, postfix].join
end

Highlights occurrences of phrases in text by formatting them with a highlighter string. phrases can be one or more strings or regular expressions. The result will be marked HTML safe. By default, text is sanitized before highlighting to prevent possible XSS attacks.

If a block is specified, it will be used instead of the highlighter string. Each occurrence of a phrase will be passed to the block, and its return value will be inserted into the final result.

Options

:highlighter

The highlighter string. Uses \1 as the placeholder for a phrase, similar to +String#sub+. Defaults to "<mark>\1</mark>". This option is ignored if a block is specified.

:sanitize

Whether to sanitize text before highlighting. Defaults to true.

Examples

highlight('You searched for: rails', 'rails')
# => "You searched for: <mark>rails</mark>"

highlight('You searched for: rails', /for|rails/)
# => "You searched <mark>for</mark>: <mark>rails</mark>"

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

highlight('You searched for: rails', 'rails') { |match| link_to(search_path(q: match, match)) }
# => "You searched for: <a href=\"search?q=rails\">rails</a>"

highlight('<a href="javascript:alert(\'no!\')">ruby</a> on rails', 'rails', sanitize: false)
# => "<a href=\"javascript:alert('no!')\">ruby</a> on <mark>rails</mark>"
Source code GitHub
# File actionview/lib/action_view/helpers/text_helper.rb, line 174
def highlight(text, phrases, options = {}, &block)
  text = sanitize(text) if options.fetch(:sanitize, true)

  if text.blank? || phrases.blank?
    text || ""
  else
    patterns = Array(phrases).map { |phrase| Regexp === phrase ? phrase : Regexp.escape(phrase) }
    pattern = /(#{patterns.join("|")})/i
    highlighter = options.fetch(:highlighter, '<mark>\1</mark>') unless block

    text.scan(/<[^>]*|[^<]+/).each do |segment|
      if !segment.start_with?("<")
        if block
          segment.gsub!(pattern, &block)
        else
          segment.gsub!(pattern, highlighter)
        end
      end
    end.join
  end.html_safe
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 for the given locale, which defaults to I18n.locale.

The word will be pluralized using rules defined for the locale (you must define your own inflection rules for languages other than English). See ActiveSupport::Inflector.pluralize

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

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

pluralize(3, 'person', plural: 'users')
# => "3 users"

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

pluralize(2, 'Person', locale: :de)
# => "2 Personen"
Source code GitHub
# File actionview/lib/action_view/helpers/text_helper.rb, line 290
def pluralize(count, singular, plural_arg = nil, plural: plural_arg, locale: I18n.locale)
  word = if count == 1 || count.to_s.match?(/^1(\.0+)?$/)
    singular
  else
    plural || singular.pluralize(locale)
  end

  "#{count || 0} #{word}"
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.

<%# 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 code GitHub
# File actionview/lib/action_view/helpers/text_helper.rb, line 477
def reset_cycle(name = "default")
  cycle = get_cycle(name)
  cycle.reset if cycle
end
Source code GitHub
# File actionview/lib/action_view/helpers/text_helper.rb, line 67
def safe_concat(string)
  output_buffer.respond_to?(:safe_concat) ? output_buffer.safe_concat(string) : concat(string)
end

Returns text transformed into HTML using simple formatting rules. Two or more consecutive newlines (\n\n or \r\n\r\n) are considered a paragraph and wrapped in <p> tags. One newline (\n or \r\n) is considered 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.

Options

  • :sanitize - If false, does not sanitize text.

  • :sanitize_options - Any extra options you want appended to the sanitize.

  • :wrapper_tag - String representing the wrapper tag, defaults to "p"

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

simple_format(my_text, {}, wrapper_tag: "div")
# => "<div>Here is some basic text...\n<br />...with a line break.</div>"

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

simple_format("<blink>Unblinkable.</blink>")
# => "<p>Unblinkable.</p>"

simple_format("<blink>Blinkable!</blink> It's true.", {}, sanitize: false)
# => "<p><blink>Blinkable!</blink> It's true.</p>"

simple_format("<a target=\"_blank\" href=\"http://example.com\">Continue</a>", {}, { sanitize_options: { attributes: %w[target href] } })
# => "<p><a target=\"_blank\" href=\"http://example.com\">Continue</a></p>"
Source code GitHub
# File actionview/lib/action_view/helpers/text_helper.rb, line 376
def simple_format(text, html_options = {}, options = {})
  wrapper_tag = options[:wrapper_tag] || "p"

  text = sanitize(text, options.fetch(:sanitize_options, {})) if options.fetch(:sanitize, true)
  paragraphs = split_paragraphs(text)

  if paragraphs.empty?
    content_tag(wrapper_tag, nil, html_options)
  else
    paragraphs.map! { |paragraph|
      content_tag(wrapper_tag, raw(paragraph), html_options)
    }.join("\n\n").html_safe
  end
end

Truncates text if it is longer than a specified :length. If text is truncated, an omission marker will be appended to the result for a total length not exceeding :length.

You can also pass a block to render and append extra content after the omission marker when text is truncated. However, this content can cause the total length to exceed :length characters.

The result will be escaped unless escape: false is specified. In any case, the result will be marked HTML-safe. Care should be taken if text might contain HTML tags or entities, because truncation could produce invalid HTML, such as unbalanced or incomplete tags.

Options

:length

The maximum number of characters that should be returned, excluding any extra content from the block. Defaults to 30.

:omission

The string to append after truncating. Defaults to "...".

:separator

A string or regexp used to find a breaking point at which to truncate. By default, truncation can occur at any character in text.

:escape

Whether to escape the result. Defaults to true.

Examples

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

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

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

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

truncate("<p>Once upon a time in a world far far away</p>")
# => "&lt;p&gt;Once upon a time in a wo..."

truncate("<p>Once upon a time in a world far far away</p>", escape: false)
# => "<p>Once upon a time in a wo..."

truncate("Once upon a time in a world far far away") { link_to "Continue", "#" }
# => "Once upon a time in a world...<a href=\"#\">Continue</a>"
Source code GitHub
# File actionview/lib/action_view/helpers/text_helper.rb, line 122
def truncate(text, options = {}, &block)
  if text
    length  = options.fetch(:length, 30)

    content = text.truncate(length, options)
    content = options[:escape] == false ? content.html_safe : ERB::Util.html_escape(content)
    content << capture(&block) if block_given? && text.length > length
    content
  end
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).

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\na successor to the throne turned out to be more trouble than anyone could have\nimagined..."

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

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

You can also specify a custom break_sequence (“n” by default):

word_wrap('Once upon a time', line_width: 1, break_sequence: "\r\n")
# => "Once\r\nupon\r\na\r\ntime"
Source code GitHub
# File actionview/lib/action_view/helpers/text_helper.rb, line 320
def word_wrap(text, line_width: 80, break_sequence: "\n")
  return +"" if text.empty?

  # Match up to `line_width` characters, followed by one of
  #   (1) non-newline whitespace plus an optional newline
  #   (2) the end of the string, ignoring any trailing newlines
  #   (3) a newline
  #
  # -OR-
  #
  # Match an empty line
  pattern = /(.{1,#{line_width}})(?:[^\S\n]+\n?|\n*\Z|\n)|\n/

  text.gsub(pattern, "\\1#{break_sequence}").chomp!(break_sequence)
end

Definition files