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.
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><a href=\"http://example.com/\">Example</a></p>"
regexps for determining context, used high-volume
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.
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", :link => :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", :link => :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, :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:me@email.com\">me@email.com</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 me@email.com." 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 me@email.com." 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:me@email.com\">me@email.com</a>."
# File lib/action_view/helpers/text_helper.rb, line 302 def auto_link(text, *args, &block)#link = :all, html = {}, &block) return '' 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
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 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 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 %>
# File lib/action_view/helpers/text_helper.rb, line 385 def current_cycle(name = "default") cycle = get_cycle(name) cycle.current_value unless cycle.nil? 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("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 357 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
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.
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 153 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 =~ %r(#{phrase})/ 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
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>')
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 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>') if text.present? && phrases.present? match = Array(phrases).map { |p| Regexp.escape(p) }.join('|') text = text.to_str.gsub(%r(#{match})(?!(?:[^<]*?)(?:["'])[^<>]*>)/, options[:highlighter]) end text = sanitize(text) unless options[:sanitize] == false text 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
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 194 def pluralize(count, singular, plural = nil) "#{count || 0} " + ((count == 1 || count =~ %r^1(\.0+)?$/) ? singular : (plural || singular.pluralize)) 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>
# File lib/action_view/helpers/text_helper.rb, line 409 def reset_cycle(name = "default") cycle = get_cycle(name) cycle.reset unless cycle.nil? end
# File lib/action_view/helpers/text_helper.rb, line 55 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
) 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.
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 252 def simple_format(text, html_options={}, options={}) text = text ? text.to_str : '' text = text.dup if text.frozen? start_tag = tag('p', html_options, true) text.gsub!(%r\r\n?/, "\n") # \r\n and \r -> \n text.gsub!(%r\n\n+/, "</p>\n\n#{start_tag}") # 2+ newline -> paragraph text.gsub!(%r([^\n]\n)(?=[^\n])/, '\1<br />') # 1 newline -> br text.insert 0, start_tag text.concat("</p>") text = sanitize(text) unless options[:sanitize] == false text end
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).
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 def truncate(text, options = {}) options.reverse_merge!(:length => 30) text.truncate(options.delete(:length), options) if text 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\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 219 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(%r(.{1,#{options[:line_width]}})(\s+|$)/, "\\1\n").strip : line end * "\n" end