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
- AUTO_LINK_RE =
%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
-
#auto_link(text, link = :all, href_options = {}, &block) ⇒ Object
Turns all urls and email addresses into clickable links.
-
#concat(string, binding) ⇒ Object
The preferred method of outputting text in your views is to use the <%= “text” %> eRuby syntax.
-
#cycle(first_value, *values) ⇒ Object
Creates a Cycle object whose to_s method cycles through elements of an array every time it is called.
-
#excerpt(text, phrase, radius = 100, excerpt_string = "...") ⇒ Object
Extracts an excerpt from
text
that matches the first instance ofphrase
. -
#highlight(text, phrase, highlighter = '<strong class="highlight">\1</strong>') ⇒ Object
Highlights
phrase
everywhere it is found intext
by inserting it into ahighlighter
string. -
#pluralize(count, singular, plural = nil) ⇒ Object
Attempts to pluralize the
singular
word unlesscount
is 1. -
#reset_cycle(name = "default") ⇒ Object
Resets a cycle so that it starts from the first element the next time it is called.
-
#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). -
#simple_format(text) ⇒ Object
Returns
text
transformed into HTML using simple formatting rules. -
#strip_links(text) ⇒ Object
Strips link tags from
text
leaving just the link label. -
#strip_tags(html) ⇒ Object
Strips all HTML tags from the
html
, including comments. -
#truncate(text, length = 30, truncate_string = "...") ⇒ Object
If
text
is longer thanlength
,text
will be truncated to the length oflength
and the last three characters will be replaced with thetruncate_string
. -
#word_wrap(text, line_width = 80) ⇒ Object
Wraps the
text
into lines no longer thanline_width
width.
Instance Method Details
#auto_link(text, link = :all, href_options = {}, &block) ⇒ Object
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, = {}, &block) return '' if text.blank? case link when :all then auto_link_urls(auto_link_email_addresses(text, &block), , &block) when :email_addresses then auto_link_email_addresses(text, &block) when :urls then auto_link_urls(text, , &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>')
=> <script> do_nasty_stuff() </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(/</, "<") 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(/</, "<") 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 (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 |