Module | ActionView::Helpers::TextHelper |
In: |
vendor/rails/actionpack/lib/action_view/helpers/text_helper.rb
|
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 ActionView making them callable within your template files.
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 unless const_defined?(:AUTO_LINK_RE) |
Turns all URLs and e-mail 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. 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", :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", :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, :all, :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>."
# File vendor/rails/actionpack/lib/action_view/helpers/text_helper.rb, line 307 307: def auto_link(text, link = :all, href_options = {}, &block) 308: return '' if text.blank? 309: case link 310: when :all then auto_link_email_addresses(auto_link_urls(text, href_options, &block), &block) 311: when :email_addresses then auto_link_email_addresses(text, &block) 312: when :urls then auto_link_urls(text, href_options, &block) 313: end 314: 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", binding # is the equivalent of <%= "hello" %> if (logged_in == true): concat "Logged in!", binding else concat link_to('login', :action => login), binding end # will either display "Logged in!" or a login link %>
# File vendor/rails/actionpack/lib/action_view/helpers/text_helper.rb, line 28 28: def concat(string, binding) 29: eval(ActionView::Base.erb_variable, binding) << string 30: 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. You can manually reset a cycle by calling reset_cycle and passing the name of the cycle.
# 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("even", "odd", :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 vendor/rails/actionpack/lib/action_view/helpers/text_helper.rb, line 352 352: def cycle(first_value, *values) 353: if (values.last.instance_of? Hash) 354: params = values.pop 355: name = params[:name] 356: else 357: name = "default" 358: end 359: values.unshift(first_value) 360: 361: cycle = get_cycle(name) 362: if (cycle.nil? || cycle.values != values) 363: cycle = set_cycle(name, Cycle.new(*values)) 364: end 365: return cycle.to_s 366: end
Extracts an excerpt from text that matches the first instance of phrase. The radius 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 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..." excerpt('This is an example', 'is') # => "This is an example" excerpt('This next thing is an example', 'ex', 2) # => "...next t..." excerpt('This is also an example', 'an', 8, '<chop> ') # => "<chop> is also an example"
# File vendor/rails/actionpack/lib/action_view/helpers/text_helper.rb, line 101 101: def excerpt(text, phrase, radius = 100, excerpt_string = "...") 102: if text.nil? || phrase.nil? then return end 103: phrase = Regexp.escape(phrase) 104: 105: if found_pos = text.chars =~ /(#{phrase})/i 106: start_pos = [ found_pos - radius, 0 ].max 107: end_pos = [ found_pos + phrase.chars.length + radius, text.chars.length ].min 108: 109: prefix = start_pos > 0 ? excerpt_string : "" 110: postfix = end_pos < text.chars.length ? excerpt_string : "" 111: 112: prefix + text.chars[start_pos..end_pos].strip + postfix 113: else 114: nil 115: end 116: 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'], '<em>\1</em>') # => You searched <em>for</em>: <em>rails</em> highlight('You searched for: rails', 'rails', "<a href='search?q=\1'>\1</a>") # => You searched for: <a href='search?q=rails>rails</a>
# File vendor/rails/actionpack/lib/action_view/helpers/text_helper.rb, line 71 71: def highlight(text, phrases, highlighter = '<strong class="highlight">\1</strong>') 72: if text.blank? || phrases.blank? 73: text 74: else 75: match = Array(phrases).map { |p| Regexp.escape(p) }.join('|') 76: text.gsub(/(#{match})/i, highlighter) 77: end 78: end
Returns the text with all the Markdown codes turned into HTML tags. This method is only available if BlueCloth is available.
markdown("We are using __Markdown__ now!") # => "<p>We are using <strong>Markdown</strong> now!</p>" markdown("We like to _write_ `code`, not just _read_ it!") # => "<p>We like to <em>write</em> <code>code</code>, not just <em>read</em> it!</p>" markdown("The [Markdown website](http://daringfireball.net/projects/markdown/) has more information.") # => "<p>The <a href="http://daringfireball.net/projects/markdown/">Markdown website</a> # has more information.</p>" markdown('') # => '<p><img src="http://rubyonrails.com/images/rails.png" alt="The ROR logo" title="Ruby on Rails" /></p>'
# File vendor/rails/actionpack/lib/action_view/helpers/text_helper.rb, line 249 249: def markdown(text) 250: text.blank? ? "" : BlueCloth.new(text).to_html 251: 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 pluralize(0, 'person') # => 0 people
# File vendor/rails/actionpack/lib/action_view/helpers/text_helper.rb, line 135 135: def pluralize(count, singular, plural = nil) 136: "#{count || 0} " + if count == 1 || count == '1' 137: singular 138: elsif plural 139: plural 140: elsif Object.const_defined?("Inflector") 141: Inflector.pluralize(singular) 142: else 143: singular + "s" 144: end 145: 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 vendor/rails/actionpack/lib/action_view/helpers/text_helper.rb, line 387 387: def reset_cycle(name = "default") 388: cycle = get_cycle(name) 389: cycle.reset unless cycle.nil? 390: 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.
my_text = """Here is some basic text... ...with a line break.""" simple_format(my_text) # => "<p>Here is some basic text...<br />...with a line break.</p>" more_text = """We want to put a paragraph... ...right there.""" simple_format(more_text) # => "<p>We want to put a paragraph...</p><p>...right there.</p>"
# File vendor/rails/actionpack/lib/action_view/helpers/text_helper.rb, line 275 275: def simple_format(text) 276: content_tag 'p', text.to_s. 277: gsub(/\r\n?/, "\n"). # \r\n and \r -> \n 278: gsub(/\n\n+/, "</p>\n\n<p>"). # 2+ newline -> paragraph 279: gsub(/([^\n]\n)(?=[^\n])/, '\1<br />') # 1 newline -> br 280: end
Returns the text with all the Textile codes turned into HTML tags.
You can learn more about Textile‘s syntax at its website. This method is only available if RedCloth is available.
textilize("*This is Textile!* Rejoice!") # => "<p><strong>This is Textile!</strong> Rejoice!</p>" textilize("I _love_ ROR(Ruby on Rails)!") # => "<p>I <em>love</em> <acronym title="Ruby on Rails">ROR</acronym>!</p>" textilize("h2. Textile makes markup -easy- simple!") # => "<h2>Textile makes markup <del>easy</del> simple!</h2>" textilize("Visit the Rails website "here":http://www.rubyonrails.org/.) # => "<p>Visit the Rails website <a href="http://www.rubyonrails.org/">here</a>.</p>"
# File vendor/rails/actionpack/lib/action_view/helpers/text_helper.rb, line 190 190: def textilize(text) 191: if text.blank? 192: "" 193: else 194: textilized = RedCloth.new(text, [ :hard_breaks ]) 195: textilized.hard_breaks = true if textilized.respond_to?("hard_breaks=") 196: textilized.to_html 197: end 198: end
Returns the text with all the Textile codes turned into HTML tags, but without the bounding <p> tag that RedCloth adds.
You can learn more about Textile‘s syntax at its website. This method is only available if RedCloth is available.
textilize_without_paragraph("*This is Textile!* Rejoice!") # => "<strong>This is Textile!</strong> Rejoice!" textilize_without_paragraph("I _love_ ROR(Ruby on Rails)!") # => "I <em>love</em> <acronym title="Ruby on Rails">ROR</acronym>!" textilize_without_paragraph("h2. Textile makes markup -easy- simple!") # => "<h2>Textile makes markup <del>easy</del> simple!</h2>" textilize_without_paragraph("Visit the Rails website "here":http://www.rubyonrails.org/.) # => "Visit the Rails website <a href="http://www.rubyonrails.org/">here</a>."
# File vendor/rails/actionpack/lib/action_view/helpers/text_helper.rb, line 219 219: def textilize_without_paragraph(text) 220: textiled = textilize(text) 221: if textiled[0..2] == "<p>" then textiled = textiled[3..-1] end 222: if textiled[-4..-1] == "</p>" then textiled = textiled[0..-5] end 223: return textiled 224: end
If text is longer than length, text will be truncated to the length of length (defaults to 30) and the last characters will be replaced with the truncate_string (defaults to "…").
truncate("Once upon a time in a world far far away", 14) # => Once upon a... truncate("Once upon a time in a world far far away") # => Once upon a time in a world f... truncate("And they found that many people were sleeping better.", 25, "(clipped)") # => And they found that many (clipped) truncate("And they found that many people were sleeping better.", 15, "... (continued)") # => And they found... (continued)
# File vendor/rails/actionpack/lib/action_view/helpers/text_helper.rb, line 48 48: def truncate(text, length = 30, truncate_string = "...") 49: if text.nil? then return end 50: l = length - truncate_string.chars.length 51: (text.chars.length > length ? text.chars[0...l] + truncate_string : text).to_s 52: 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', 4) # => Once\nupon\na\ntime word_wrap('Once upon a time', 8) # => Once upon\na time word_wrap('Once upon a time') # => Once upon a time word_wrap('Once upon a time', 1) # => Once\nupon\na\ntime
# File vendor/rails/actionpack/lib/action_view/helpers/text_helper.rb, line 163 163: def word_wrap(text, line_width = 80) 164: text.split("\n").collect do |line| 165: line.length > line_width ? line.gsub(/(.{1,#{line_width}})(\s+|$)/, "\\1\n").strip : line 166: end * "\n" 167: end