Included Modules

Class Index [+]

Quicksearch

ActionView::Helpers::TextHelper

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 by default sanitize the given content, 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>"

Constants

AUTO_LINK_RE
AUTO_LINK_CRE

regexps for determining context, used high-volume

AUTO_EMAIL_RE
BRACKETS

Public Instance Methods

concat(string) click to toggle source

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
        concat "Logged in!"
      else
        concat link_to('login', :action => login)
      end
      # will either display "Logged in!" or a login link
  %>
    # File lib/action_view/helpers/text_helper.rb, line 51
51:       def concat(string)
52:         output_buffer << string
53:       end
current_cycle(name = "default") click to toggle source

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.

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 %>
     # File lib/action_view/helpers/text_helper.rb, line 384
384:       def current_cycle(name = "default")
385:         cycle = get_cycle(name)
386:         cycle.current_value unless cycle.nil?
387:       end
cycle(first_value, *values) click to toggle source

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("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 %>
     # File lib/action_view/helpers/text_helper.rb, line 356
356:       def cycle(first_value, *values)
357:         if (values.last.instance_of? Hash)
358:           params = values.pop
359:           name = params[:name]
360:         else
361:           name = "default"
362:         end
363:         values.unshift(first_value)
364: 
365:         cycle = get_cycle(name)
366:         if (cycle.nil? || cycle.values != values)
367:           cycle = set_cycle(name, Cycle.new(*values))
368:         end
369:         return cycle.to_s
370:       end
excerpt(text, phrase, *args) click to toggle source

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

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 ’1’)

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>
     # File lib/action_view/helpers/text_helper.rb, line 111
111:       def highlight(text, phrases, *args)
112:         options = args.extract_options!
113:         unless args.empty?
114:           options[:highlighter] = args[0] || '<strong class="highlight">\1</strong>'
115:         end
116:         options.reverse_merge!(:highlighter => '<strong class="highlight">\1</strong>')
117: 
118:         text = sanitize(text) unless options[:sanitize] == false
119:         if text.blank? || phrases.blank?
120:           text
121:         else
122:           match = Array(phrases).map { |p| Regexp.escape(p) }.join('|')
123:           text.gsub(/(#{match})(?!(?:[^<]*?)(?:["'])[^<>]*>)/, options[:highlighter])
124:         end.html_safe
125:       end
pluralize(count, singular, plural = nil) click to toggle source

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
     # File lib/action_view/helpers/text_helper.rb, line 195
195:       def pluralize(count, singular, plural = nil)
196:         "#{count || 0} " + ((count == 1 || count =~ /^1(\.0+)?$/) ? singular : (plural || singular.pluralize))
197:       end
reset_cycle(name = "default") click to toggle source

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>
     # File lib/action_view/helpers/text_helper.rb, line 408
408:       def reset_cycle(name = "default")
409:         cycle = get_cycle(name)
410:         cycle.reset unless cycle.nil?
411:       end
safe_concat(string) click to toggle source
    # File lib/action_view/helpers/text_helper.rb, line 55
55:       def safe_concat(string)
56:         output_buffer.respond_to?(:safe_concat) ? output_buffer.safe_concat(string) : concat(string)
57:       end
simple_format(text, html_options={}, options={}) click to toggle source

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>"
     # File lib/action_view/helpers/text_helper.rb, line 253
253:       def simple_format(text, html_options={}, options={})
254:         text = ''.html_safe if text.nil?
255:         start_tag = tag('p', html_options, true)
256:         text = sanitize(text) unless options[:sanitize] == false
257:         text.gsub!(/\r\n?/, "\n")                    # \r\n and \r -> \n
258:         text.gsub!(/\n\n+/, "</p>\n\n#{start_tag}")  # 2+ newline  -> paragraph
259:         text.gsub!(/([^\n]\n)(?=[^\n])/, '\1<br />') # 1 newline   -> br
260:         text.insert 0, start_tag
261:         text.html_safe.safe_concat("</p>")
262:       end
truncate(text, options = {}) click to toggle source

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 “…”) for a total length not exceeding :length.

Pass a :separator to truncate text at a natural break.

The result is not marked as HTML-safe, so will be subject to the default escaping when used in views, unless wrapped by raw(). Care should be taken if text contains HTML tags or entities, because truncation may produce invalid HTML (such as unbalanced or incomplete tags).

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>")
  # => "<p>Once upon a time in a wo..."
    # File lib/action_view/helpers/text_helper.rb, line 85
85:       def truncate(text, options = {})
86:         options.reverse_merge!(:length => 30)
87:         text.truncate(options.delete(:length), options) if text
88:       end
word_wrap(text, *args) click to toggle source

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
     # File lib/action_view/helpers/text_helper.rb, line 220
220:       def word_wrap(text, *args)
221:         options = args.extract_options!
222:         unless args.blank?
223:           options[:line_width] = args[0] || 80
224:         end
225:         options.reverse_merge!(:line_width => 80)
226: 
227:         text.split("\n").collect do |line|
228:           line.length > options[:line_width] ? line.gsub(/(.{1,#{options[:line_width]}})(\s+|$)/, "\\1\n").strip : line
229:         end * "\n"
230:       end

Private Instance Methods

auto_linked?(left, right) click to toggle source

Detects already linked context or position in the middle of a tag

     # File lib/action_view/helpers/text_helper.rb, line 530
530:         def auto_linked?(left, right)
531:           (left =~ AUTO_LINK_CRE[0] and right =~ AUTO_LINK_CRE[1]) or
532:             (left.rindex(AUTO_LINK_CRE[2]) and $' !~ AUTO_LINK_CRE[3])
533:         end
get_cycle(name) click to toggle source

The cycle helpers need to store the cycles in a place that is guaranteed to be reset every time a page is rendered, so it uses an instance variable of ActionView::Base.

     # File lib/action_view/helpers/text_helper.rb, line 454
454:         def get_cycle(name)
455:           @_cycles = Hash.new unless defined?(@_cycles)
456:           return @_cycles[name]
457:         end
set_cycle(name, cycle_object) click to toggle source
     # File lib/action_view/helpers/text_helper.rb, line 459
459:         def set_cycle(name, cycle_object)
460:           @_cycles = Hash.new unless defined?(@_cycles)
461:           @_cycles[name] = cycle_object
462:         end

Disabled; run with --debug to generate this.

[Validate]

Generated with the Darkfish Rdoc Generator 1.1.6.