Module: ActionView::Helpers::TextHelper

Defined in:
lib/action_view/helpers/text_helper.rb

Overview

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

Defined Under Namespace

Classes: Cycle

Constant Summary collapse

VERBOTEN_TAGS = 
%w(form script plaintext)
VERBOTEN_ATTRS = 
/^on/i
%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:]]|\s|<|$)       # trailing text
}x

Instance Method Summary collapse

Instance Method Details

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.

auto_link("Go to http://www.rubyonrails.org and say hello to [email protected]") =>
  Go to <a href="http://www.rubyonrails.org">http://www.rubyonrails.org</a> and
  say hello to <a href="mailto:[email protected]">[email protected]</a>

If a block is given, each url and email address is yielded and the result is used as the link text.

auto_link(post.body, :all, :target => '_blank') do |text|
  truncate(text, 15)
end



178
179
180
181
182
183
184
185
 
# File 'lib/action_view/helpers/text_helper.rb', line 178

def auto_link(text, link = :all, href_options = {}, &block)
  return '' if text.blank?
  case link
    when :all             then auto_link_urls(auto_link_email_addresses(text, &block), href_options, &block)
    when :email_addresses then auto_link_email_addresses(text, &block)
    when :urls            then auto_link_urls(text, href_options, &block)
  end
end

#concat(string, binding) ⇒ Object

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



25
26
27
 
# File 'lib/action_view/helpers/text_helper.rb', line 25

def concat(string, binding)
  eval("_erbout", binding).concat(string)
end

#cycle(first_value, *values) ⇒ Object

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:

<% @items.each do |item| %>
  <tr class="<%= cycle("even", "odd") -%>">
    <td>item</td>
  </tr>
<% end %>

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.

 <% @items.each do |item| %>
   <tr class="<%= cycle("even", "odd", :name => "row_class")
     <td>
       <% item.values.each do |value| %>
         <span style="color:<%= cycle("red", "green", "blue", :name => "colors") -%>">
           value
         </span>
       <% end %>
       <% reset_cycle("colors") %>
     </td>
  </tr>
<% end %>



302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
 
# File 'lib/action_view/helpers/text_helper.rb', line 302

def cycle(first_value, *values)
  if (values.last.instance_of? Hash)
    params = values.pop
    name = params[:name]
  else
    name = "default"
  end
  values.unshift(first_value)

  cycle = get_cycle(name)
  if (cycle.nil? || cycle.values != values)
    cycle = set_cycle(name, Cycle.new(*values))
  end
  return cycle.to_s
end

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

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



62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
 
# File 'lib/action_view/helpers/text_helper.rb', line 62

def excerpt(text, phrase, radius = 100, excerpt_string = "...")
  if text.nil? || phrase.nil? then return end
  phrase = Regexp.escape(phrase)

  if found_pos = text.chars =~ /(#{phrase})/i
    start_pos = [ found_pos - radius, 0 ].max
    end_pos   = [ found_pos + phrase.chars.length + radius, text.chars.length ].min

    prefix  = start_pos > 0 ? excerpt_string : ""
    postfix = end_pos < text.chars.length ? excerpt_string : ""

    prefix + text.chars[start_pos..end_pos].strip + postfix
  else
    nil
  end
end

#highlight(text, phrase, highlighter = '<strong class="highlight">\1</strong>') ⇒ Object

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: <strong class="highlight">rails</strong>



46
47
48
49
 
# File 'lib/action_view/helpers/text_helper.rb', line 46

def highlight(text, phrase, highlighter = '<strong class="highlight">\1</strong>')
  if phrase.blank? then return text end
  text.gsub(/(#{Regexp.escape(phrase)})/i, highlighter) unless text.nil?
end

#pluralize(count, singular, plural = nil) ⇒ Object

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



87
88
89
90
91
92
93
94
95
96
97
 
# File 'lib/action_view/helpers/text_helper.rb', line 87

def pluralize(count, singular, plural = nil)
   "#{count} " + if count == 1 || count == '1'
    singular
  elsif plural
    plural
  elsif Object.const_defined?("Inflector")
    Inflector.pluralize(singular)
  else
    singular + "s"
  end
end

#reset_cycle(name = "default") ⇒ Object

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.



320
321
322
323
 
# File 'lib/action_view/helpers/text_helper.rb', line 320

def reset_cycle(name = "default")
  cycle = get_cycle(name)
  cycle.reset unless cycle.nil?
end

#sanitize(html) ⇒ Object

Sanitizes the html by converting <form> and <script> tags into regular text, and removing all “onxxx” attributes (so that arbitrary Javascript cannot be executed). It also removes href= and src= attributes that start with “javascript:”. You can modify what gets sanitized by defining VERBOTEN_TAGS and VERBOTEN_ATTRS before this Module is loaded.

sanitize('<script> do_nasty_stuff() </script>')
 => &lt;script> do_nasty_stuff() &lt;/script>
sanitize('<a href="javascript: sucker();">Click here for $100</a>')
 => <a>Click here for $100</a>



221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
 
# File 'lib/action_view/helpers/text_helper.rb', line 221

def sanitize(html)
  # only do this if absolutely necessary
  if html.index("<")
    tokenizer = HTML::Tokenizer.new(html)
    new_text = ""

    while token = tokenizer.next
      node = HTML::Node.parse(nil, 0, 0, token, false)
      new_text << case node
        when HTML::Tag
          if VERBOTEN_TAGS.include?(node.name)
            node.to_s.gsub(/</, "&lt;")
          else
            if node.closing != :close
              node.attributes.delete_if { |attr,v| attr =~ VERBOTEN_ATTRS }
              %w(href src).each do |attr|
                node.attributes.delete attr if node.attributes[attr] =~ /^javascript:/i
              end
            end
            node.to_s
          end
        else
          node.to_s.gsub(/</, "&lt;")
      end
    end

    html = new_text
  end

  html
end

#simple_format(text) ⇒ Object

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.



156
157
158
159
160
161
 
# File 'lib/action_view/helpers/text_helper.rb', line 156

def simple_format(text)
  content_tag 'p', text.to_s.
    gsub(/\r\n?/, "\n").                    # \r\n and \r -> \n
    gsub(/\n\n+/, "</p>\n\n<p>").           # 2+ newline  -> paragraph
    gsub(/([^\n]\n)(?=[^\n])/, '\1<br />')  # 1 newline   -> br
end

#strip_links(text) ⇒ Object

Strips link tags from text leaving just the link label.

strip_links('<a href="http://www.rubyonrails.org">Ruby on Rails</a>')
 => Ruby on Rails



191
192
193
 
# File 'lib/action_view/helpers/text_helper.rb', line 191

def strip_links(text)
  text.gsub(/<a\b.*?>(.*?)<\/a>/mi, '\1')
end

#strip_tags(html) ⇒ Object

Strips all HTML tags from the html, including comments. This uses the html-scanner tokenizer and so its HTML parsing ability is limited by that of html-scanner.



256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
 
# File 'lib/action_view/helpers/text_helper.rb', line 256

def strip_tags(html)     
  return html if html.blank?
  if html.index("<")
    text = ""
    tokenizer = HTML::Tokenizer.new(html)

    while token = tokenizer.next
      node = HTML::Node.parse(nil, 0, 0, token, false)
      # result is only the content of any Text nodes
      text << node.to_s if node.class == HTML::Text  
    end
    # strip any comments, and if they have a newline at the end (ie. line with
    # only a comment) strip that too
    text.gsub(/<!--(.*?)-->[\n]?/m, "") 
  else
    html # already plain text
  end 
end

#truncate(text, length = 30, truncate_string = "...") ⇒ Object

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



34
35
36
37
38
 
# File 'lib/action_view/helpers/text_helper.rb', line 34

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

#word_wrap(text, line_width = 80) ⇒ Object

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



104
105
106
 
# File 'lib/action_view/helpers/text_helper.rb', line 104

def word_wrap(text, line_width = 80)
  text.gsub(/\n/, "\n\n").gsub(/(.{1,#{line_width}})(\s+|$)/, "\\1\n").strip
end