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...
- auto_link
- concat
- cycle
- excerpt
- highlight
- markdown
- pluralize
- reset_cycle
- sanitize
- simple_format
- strip_links
- strip_tags
- textilize
- textilize_without_paragraph
- truncate
- word_wrap
VERBOTEN_TAGS | = | %w(form script plaintext) unless defined?(VERBOTEN_TAGS) |
VERBOTEN_ATTRS | = | /^on/i unless defined?(VERBOTEN_ATTRS) |
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%.;-]+)?)* # path (?:\?[\w%&=.;-]+)? # query string (?:\#\w*)? # trailing anchor ) ([[:punct:]]|\s|<|$) # trailing text }x unless const_defined?(:AUTO_LINK_RE) |
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 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>
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
[ show source ]
# File vendor/rails/actionpack/lib/action_view/helpers/text_helper.rb, line 178 178: def auto_link(text, link = :all, href_options = {}, &block) 179: return '' if text.blank? 180: case link 181: when :all then auto_link_urls(auto_link_email_addresses(text, &block), href_options, &block) 182: when :email_addresses then auto_link_email_addresses(text, &block) 183: when :urls then auto_link_urls(text, href_options, &block) 184: end 185: 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 code block, you can use the concat method.
<% concat "hello", binding %>
is equivalent to using:
<%= "hello" %>
[ show source ]
# File vendor/rails/actionpack/lib/action_view/helpers/text_helper.rb, line 25 25: def concat(string, binding) 26: eval("_erbout", binding).concat(string) 27: 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:
<% @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 %>
[ show source ]
# File vendor/rails/actionpack/lib/action_view/helpers/text_helper.rb, line 302 302: def cycle(first_value, *values) 303: if (values.last.instance_of? Hash) 304: params = values.pop 305: name = params[:name] 306: else 307: name = "default" 308: end 309: values.unshift(first_value) 310: 311: cycle = get_cycle(name) 312: if (cycle.nil? || cycle.values != values) 313: cycle = set_cycle(name, Cycle.new(*values)) 314: end 315: return cycle.to_s 316: end
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..."
[ show source ]
# File vendor/rails/actionpack/lib/action_view/helpers/text_helper.rb, line 62 62: def excerpt(text, phrase, radius = 100, excerpt_string = "...") 63: if text.nil? || phrase.nil? then return end 64: phrase = Regexp.escape(phrase) 65: 66: if found_pos = text.chars =~ /(#{phrase})/i 67: start_pos = [ found_pos - radius, 0 ].max 68: end_pos = [ found_pos + phrase.chars.length + radius, text.chars.length ].min 69: 70: prefix = start_pos > 0 ? excerpt_string : "" 71: postfix = end_pos < text.chars.length ? excerpt_string : "" 72: 73: prefix + text.chars[start_pos..end_pos].strip + postfix 74: else 75: nil 76: end 77: end
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>
[ show source ]
# File vendor/rails/actionpack/lib/action_view/helpers/text_helper.rb, line 46 46: def highlight(text, phrase, highlighter = '<strong class="highlight">\1</strong>') 47: if phrase.blank? then return text end 48: text.gsub(/(#{Regexp.escape(phrase)})/i, highlighter) unless text.nil? 49: end
Returns the text with all the Markdown codes turned into HTML tags. This method is only available if BlueCloth is available.
[ show source ]
# File vendor/rails/actionpack/lib/action_view/helpers/text_helper.rb, line 144 144: def markdown(text) 145: text.blank? ? "" : BlueCloth.new(text).to_html 146: end
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
[ show source ]
# File vendor/rails/actionpack/lib/action_view/helpers/text_helper.rb, line 87 87: def pluralize(count, singular, plural = nil) 88: "#{count} " + if count == 1 || count == '1' 89: singular 90: elsif plural 91: plural 92: elsif Object.const_defined?("Inflector") 93: Inflector.pluralize(singular) 94: else 95: singular + "s" 96: end 97: 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.
[ show source ]
# File vendor/rails/actionpack/lib/action_view/helpers/text_helper.rb, line 320 320: def reset_cycle(name = "default") 321: cycle = get_cycle(name) 322: cycle.reset unless cycle.nil? 323: end
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>
[ show source ]
# File vendor/rails/actionpack/lib/action_view/helpers/text_helper.rb, line 221 221: def sanitize(html) 222: # only do this if absolutely necessary 223: if html.index("<") 224: tokenizer = HTML::Tokenizer.new(html) 225: new_text = "" 226: 227: while token = tokenizer.next 228: node = HTML::Node.parse(nil, 0, 0, token, false) 229: new_text << case node 230: when HTML::Tag 231: if VERBOTEN_TAGS.include?(node.name) 232: node.to_s.gsub(/</, "<") 233: else 234: if node.closing != :close 235: node.attributes.delete_if { |attr,v| attr =~ VERBOTEN_ATTRS } 236: %w(href src).each do |attr| 237: node.attributes.delete attr if node.attributes[attr] =~ /^javascript:/i 238: end 239: end 240: node.to_s 241: end 242: else 243: node.to_s.gsub(/</, "<") 244: end 245: end 246: 247: html = new_text 248: end 249: 250: html 251: 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.
[ show source ]
# File vendor/rails/actionpack/lib/action_view/helpers/text_helper.rb, line 156 156: def simple_format(text) 157: content_tag 'p', text.to_s. 158: gsub(/\r\n?/, "\n"). # \r\n and \r -> \n 159: gsub(/\n\n+/, "</p>\n\n<p>"). # 2+ newline -> paragraph 160: gsub(/([^\n]\n)(?=[^\n])/, '\1<br />') # 1 newline -> br 161: end
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
[ show source ]
# File vendor/rails/actionpack/lib/action_view/helpers/text_helper.rb, line 191 191: def strip_links(text) 192: text.gsub(/<a\b.*?>(.*?)<\/a>/mi, '\1') 193: end
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.
[ show source ]
# File vendor/rails/actionpack/lib/action_view/helpers/text_helper.rb, line 256 256: def strip_tags(html) 257: return html if html.blank? 258: if html.index("<") 259: text = "" 260: tokenizer = HTML::Tokenizer.new(html) 261: 262: while token = tokenizer.next 263: node = HTML::Node.parse(nil, 0, 0, token, false) 264: # result is only the content of any Text nodes 265: text << node.to_s if node.class == HTML::Text 266: end 267: # strip any comments, and if they have a newline at the end (ie. line with 268: # only a comment) strip that too 269: text.gsub(/<!--(.*?)-->[\n]?/m, "") 270: else 271: html # already plain text 272: end 273: end
Returns the text with all the Textile codes turned into HTML tags. This method is only available if RedCloth is available.
[ show source ]
# File vendor/rails/actionpack/lib/action_view/helpers/text_helper.rb, line 114 114: def textilize(text) 115: if text.blank? 116: "" 117: else 118: textilized = RedCloth.new(text, [ :hard_breaks ]) 119: textilized.hard_breaks = true if textilized.respond_to?("hard_breaks=") 120: textilized.to_html 121: end 122: end
Returns the text with all the Textile codes turned into HTML tags, but without the bounding <p> tag that RedCloth adds. This method is only available if RedCloth is available.
[ show source ]
# File vendor/rails/actionpack/lib/action_view/helpers/text_helper.rb, line 128 128: def textilize_without_paragraph(text) 129: textiled = textilize(text) 130: if textiled[0..2] == "<p>" then textiled = textiled[3..-1] end 131: if textiled[-4..-1] == "</p>" then textiled = textiled[0..-5] end 132: return textiled 133: end
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...
[ show source ]
# File vendor/rails/actionpack/lib/action_view/helpers/text_helper.rb, line 34 34: def truncate(text, length = 30, truncate_string = "...") 35: if text.nil? then return end 36: l = length - truncate_string.chars.length 37: text.chars.length > length ? text.chars[0...l] + truncate_string : text 38: 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.
word_wrap('Once upon a time', 4) => Once\nupon\na\ntime
[ show source ]
# File vendor/rails/actionpack/lib/action_view/helpers/text_helper.rb, line 104 104: def word_wrap(text, line_width = 80) 105: text.gsub(/\n/, "\n\n").gsub(/(.{1,#{line_width}})(\s+|$)/, "\\1\n").strip 106: end