Module: ActionView::Helpers::TextHelper

Extended by:
ActiveSupport::Concern
Includes:
SanitizeHelper
Included in:
ActionView::Helpers, FormOptionsHelper, FormTagHelper
Defined in:
lib/action_view/helpers/text_helper.rb

Overview

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.

Defined Under Namespace

Classes: Cycle

Instance Method Summary collapse

Methods included from SanitizeHelper

#sanitize, #sanitize_css, #strip_links, #strip_tags

Instance Method Details

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 :html. 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 [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>"

auto_link("Visit http://www.loudthinking.com/ or e-mail [email protected]", :link => :urls)
# => "Visit <a href=\"http://www.loudthinking.com/\">http://www.loudthinking.com/</a>
#     or e-mail [email protected]"

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

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

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:[email protected]\">[email protected]</a>."



283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
 
# File 'lib/action_view/helpers/text_helper.rb', line 283

def auto_link(text, *args, &block)#link = :all, html = {}, &block)
  return ''.html_safe if text.blank?

  options = args.size == 2 ? {} : args.extract_options! # this is necessary because the old auto_link API has a Hash as its last parameter
  unless args.empty?
    options[:link] = args[0] || :all
    options[:html] = args[1] || {}
  end
  options.reverse_merge!(:link => :all, :html => {})

  case options[:link].to_sym
    when :all                         then auto_link_email_addresses(auto_link_urls(text, options[:html], options, &block), options[:html], &block)
    when :email_addresses             then auto_link_email_addresses(text, options[:html], &block)
    when :urls                        then auto_link_urls(text, options[:html], options, &block)
  end
end

#concat(string) ⇒ 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 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
%>



33
34
35
 
# File 'lib/action_view/helpers/text_helper.rb', line 33

def concat(string)
  output_buffer << string
end

#current_cycle(name = "default") ⇒ Object

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



366
367
368
369
 
# File 'lib/action_view/helpers/text_helper.rb', line 366

def current_cycle(name = "default")
  cycle = get_cycle(name)
  cycle.current_value unless cycle.nil?
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. 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 %>



338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
 
# File 'lib/action_view/helpers/text_helper.rb', line 338

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, *args) ⇒ Object

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



136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
 
# File 'lib/action_view/helpers/text_helper.rb', line 136

def excerpt(text, phrase, *args)
  options = args.extract_options!
  unless args.empty?
    options[:radius] = args[0] || 100
    options[:omission] = args[1] || "..."
  end
  options.reverse_merge!(:radius => 100, :omission => "...")

  if text && phrase
    phrase = Regexp.escape(phrase)

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

      prefix  = start_pos > 0 ? options[:omission] : ""
      postfix = end_pos < text.mb_chars.length - 1 ? options[:omission] : ""

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

#highlight(text, phrases, *args) ⇒ Object

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>



93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
 
# File 'lib/action_view/helpers/text_helper.rb', line 93

def highlight(text, phrases, *args)
  options = args.extract_options!
  unless args.empty?
    options[:highlighter] = args[0] || '<strong class="highlight">\1</strong>'
  end
  options.reverse_merge!(:highlighter => '<strong class="highlight">\1</strong>')

  text = sanitize(text) unless options[:sanitize] == false
  if text.blank? || phrases.blank?
    text
  else
    match = Array(phrases).map { |p| Regexp.escape(p) }.join('|')
    text.gsub(/(#{match})(?!(?:[^<]*?)(?:["'])[^<>]*>)/i, options[:highlighter])
  end.html_safe
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, 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



177
178
179
 
# File 'lib/action_view/helpers/text_helper.rb', line 177

def pluralize(count, singular, plural = nil)
  "#{count || 0} " + ((count == 1 || count =~ /^1(\.0+)?$/) ? singular : (plural || singular.pluralize))
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.

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>



390
391
392
393
 
# File 'lib/action_view/helpers/text_helper.rb', line 390

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

#safe_concat(string) ⇒ Object 



37
38
39
 
# File 'lib/action_view/helpers/text_helper.rb', line 37

def safe_concat(string)
  output_buffer.respond_to?(:safe_concat) ? output_buffer.safe_concat(string) : concat(string)
end

#simple_format(text, html_options = {}, options = {}) ⇒ 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.

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



235
236
237
238
239
240
241
242
243
244
 
# File 'lib/action_view/helpers/text_helper.rb', line 235

def simple_format(text, html_options={}, options={})
  text = ''.html_safe if text.nil?
  start_tag = tag('p', html_options, true)
  text = sanitize(text) unless options[:sanitize] == false
  text.gsub!(/\r\n?/, "\n")                    # \r\n and \r -> \n
  text.gsub!(/\n\n+/, "</p>\n\n#{start_tag}")  # 2+ newline  -> paragraph
  text.gsub!(/([^\n]\n)(?=[^\n])/, '\1<br />') # 1 newline   -> br
  text.insert 0, start_tag
  text.html_safe.safe_concat("</p>")
end

#truncate(text, options = {}) ⇒ Object

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



67
68
69
70
 
# File 'lib/action_view/helpers/text_helper.rb', line 67

def truncate(text, options = {})
  options.reverse_merge!(:length => 30)
  text.truncate(options.delete(:length), options) if text
end

#word_wrap(text, *args) ⇒ 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 (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



202
203
204
205
206
207
208
209
210
211
212
 
# File 'lib/action_view/helpers/text_helper.rb', line 202

def word_wrap(text, *args)
  options = args.extract_options!
  unless args.blank?
    options[:line_width] = args[0] || 80
  end
  options.reverse_merge!(:line_width => 80)

  text.split("\n").collect do |line|
    line.length > options[:line_width] ? line.gsub(/(.{1,#{options[:line_width]}})(\s+|$)/, "\\1\n").strip : line
  end * "\n"
end