48bf4717ad3b40331087f1c06ef90854b9a9a931
1 require 'action_view/helpers/tag_helper'
4 module Helpers
#:nodoc:
5 # The TextHelper module provides a set of methods for filtering, formatting
6 # and transforming strings, which can reduce the amount of inline Ruby code in
7 # your views. These helper methods extend ActionView making them callable
8 # within your template files.
10 # The preferred method of outputting text in your views is to use the
11 # <%= "text" %> eRuby syntax. The regular _puts_ and _print_ methods
12 # do not operate as expected in an eRuby code block. If you absolutely must
13 # output text within a non-output code block (i.e., <% %>), you can use the concat method.
18 # # is the equivalent of <%= "hello" %>
20 # if (logged_in == true):
23 # concat link_to('login', :action => login)
25 # # will either display "Logged in!" or a login link
27 def concat(string
, unused_binding
= nil)
29 ActiveSupport
::Deprecation.warn("The binding argument of #concat is no longer needed. Please remove it from your views and helpers.", caller
)
32 output_buffer
<< string
35 # Truncates a given +text+ after a given <tt>:length</tt> if +text+ is longer than <tt>:length</tt>
36 # (defaults to 30). The last characters will be replaced with the <tt>:omission</tt> (defaults to "...").
40 # truncate("Once upon a time in a world far far away")
41 # # => Once upon a time in a world f...
43 # truncate("Once upon a time in a world far far away", :length => 14)
46 # truncate("And they found that many people were sleeping better.", :length => 25, "(clipped)")
47 # # => And they found that many (clipped)
49 # truncate("And they found that many people were sleeping better.", :omission => "... (continued)", :length => 15)
50 # # => And they found... (continued)
52 # You can still use <tt>truncate</tt> with the old API that accepts the
53 # +length+ as its optional second and the +ellipsis+ as its
54 # optional third parameter:
55 # truncate("Once upon a time in a world far far away", 14)
56 # # => Once upon a time in a world f...
58 # truncate("And they found that many people were sleeping better.", 15, "... (continued)")
59 # # => And they found... (continued)
60 def truncate(text
, *args
)
61 options
= args
.extract_options
!
63 ActiveSupport
::Deprecation.warn('truncate takes an option hash instead of separate ' +
64 'length and omission arguments', caller
)
66 options
[:length] = args
[0] || 30
67 options
[:omission] = args
[1] || "..."
69 options
.reverse_merge
!(:length => 30, :omission => "...")
72 l
= options
[:length] - options
[:omission].mb_chars
.length
74 (chars
.length
> options
[:length] ? chars
[0...l
] + options
[:omission] : text
).to_s
78 # Highlights one or more +phrases+ everywhere in +text+ by inserting it into
79 # a <tt>:highlighter</tt> string. The highlighter can be specialized by passing <tt>:highlighter</tt>
80 # as a single-quoted string with \1 where the phrase is to be inserted (defaults to
81 # '<strong class="highlight">\1</strong>')
84 # highlight('You searched for: rails', 'rails')
85 # # => You searched for: <strong class="highlight">rails</strong>
87 # highlight('You searched for: ruby, rails, dhh', 'actionpack')
88 # # => You searched for: ruby, rails, dhh
90 # highlight('You searched for: rails', ['for', 'rails'], :highlighter => '<em>\1</em>')
91 # # => You searched <em>for</em>: <em>rails</em>
93 # highlight('You searched for: rails', 'rails', :highlighter => '<a href="search?q=\1">\1</a>')
94 # # => You searched for: <a href="search?q=rails">rails</a>
96 # You can still use <tt>highlight</tt> with the old API that accepts the
97 # +highlighter+ as its optional third parameter:
98 # highlight('You searched for: rails', 'rails', '<a href="search?q=\1">\1</a>') # => You searched for: <a href="search?q=rails">rails</a>
99 def highlight(text
, phrases
, *args
)
100 options
= args
.extract_options
!
102 options
[:highlighter] = args
[0] || '<strong class="highlight">\1</strong>'
104 options
.reverse_merge
!(:highlighter => '<strong class="highlight">\1</strong>')
106 if text
.blank
? || phrases
.blank
?
109 match
= Array(phrases
).map
{ |p
| Regexp
.escape(p
) }.join('|')
110 text
.gsub(/(#{match})(?!(?:[^<]*?)(?:["'])[^<>]*>)/i
, options
[:highlighter])
114 # Extracts an excerpt from +text+ that matches the first instance of +phrase+.
115 # The <tt>:radius</tt> option expands the excerpt on each side of the first occurrence of +phrase+ by the number of characters
116 # defined in <tt>:radius</tt> (which defaults to 100). If the excerpt radius overflows the beginning or end of the +text+,
117 # then the <tt>:omission</tt> option (which defaults to "...") will be prepended/appended accordingly. The resulting string
118 # will be stripped in any case. If the +phrase+ isn't found, nil is returned.
121 # excerpt('This is an example', 'an', :radius => 5)
122 # # => ...s is an exam...
124 # excerpt('This is an example', 'is', :radius => 5)
127 # excerpt('This is an example', 'is')
128 # # => This is an example
130 # excerpt('This next thing is an example', 'ex', :radius => 2)
133 # excerpt('This is also an example', 'an', :radius => 8, :omission => '<chop> ')
134 # # => <chop> is also an example
136 # You can still use <tt>excerpt</tt> with the old API that accepts the
137 # +radius+ as its optional third and the +ellipsis+ as its
138 # optional forth parameter:
139 # excerpt('This is an example', 'an', 5) # => ...s is an exam...
140 # excerpt('This is also an example', 'an', 8, '<chop> ') # => <chop> is also an example
141 def excerpt(text
, phrase
, *args
)
142 options
= args
.extract_options
!
144 options
[:radius] = args
[0] || 100
145 options
[:omission] = args
[1] || "..."
147 options
.reverse_merge
!(:radius => 100, :omission => "...")
150 phrase
= Regexp
.escape(phrase
)
152 if found_pos
= text
.mb_chars
=~
/(#{phrase})/i
153 start_pos
= [ found_pos
- options
[:radius], 0 ].max
154 end_pos
= [ [ found_pos
+ phrase
.mb_chars
.length
+ options
[:radius] - 1, 0].max
, text
.mb_chars
.length
].min
156 prefix
= start_pos
> 0 ? options
[:omission] : ""
157 postfix
= end_pos
< text
.mb_chars
.length
- 1 ? options
[:omission] : ""
159 prefix
+ text
.mb_chars
[start_pos
..end_pos
].strip
+ postfix
166 # Attempts to pluralize the +singular+ word unless +count+ is 1. If
167 # +plural+ is supplied, it will use that when count is > 1, otherwise
168 # it will use the Inflector to determine the plural form
171 # pluralize(1, 'person')
174 # pluralize(2, 'person')
177 # pluralize(3, 'person', 'users')
180 # pluralize(0, 'person')
182 def pluralize(count
, singular
, plural
= nil)
183 "#{count || 0} " + ((count
== 1 || count
== '1') ? singular
: (plural
|| singular
.pluralize
))
186 # Wraps the +text+ into lines no longer than +line_width+ width. This method
187 # breaks on the first whitespace character that does not exceed +line_width+
188 # (which is 80 by default).
192 # word_wrap('Once upon a time')
193 # # => Once upon a time
195 # 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...')
196 # # => 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...
198 # word_wrap('Once upon a time', :line_width => 8)
199 # # => Once upon\na time
201 # word_wrap('Once upon a time', :line_width => 1)
202 # # => Once\nupon\na\ntime
204 # You can still use <tt>word_wrap</tt> with the old API that accepts the
205 # +line_width+ as its optional second parameter:
206 # word_wrap('Once upon a time', 8) # => Once upon\na time
207 def word_wrap(text
, *args
)
208 options
= args
.extract_options
!
210 options
[:line_width] = args
[0] || 80
212 options
.reverse_merge
!(:line_width => 80)
214 text
.split("\n").collect
do |line
|
215 line
.length
> options
[:line_width] ? line
.gsub(/(.{1,#{options[:line_width]}})(\s+|$)/, "\\1\n").strip
: line
219 # Returns the text with all the Textile[http://www.textism.com/tools/textile] codes turned into HTML tags.
221 # You can learn more about Textile's syntax at its website[http://www.textism.com/tools/textile].
222 # <i>This method is only available if RedCloth[http://whytheluckystiff.net/ruby/redcloth/]
226 # textilize("*This is Textile!* Rejoice!")
227 # # => "<p><strong>This is Textile!</strong> Rejoice!</p>"
229 # textilize("I _love_ ROR(Ruby on Rails)!")
230 # # => "<p>I <em>love</em> <acronym title="Ruby on Rails">ROR</acronym>!</p>"
232 # textilize("h2. Textile makes markup -easy- simple!")
233 # # => "<h2>Textile makes markup <del>easy</del> simple!</h2>"
235 # textilize("Visit the Rails website "here":http://www.rubyonrails.org/.)
236 # # => "<p>Visit the Rails website <a href="http://www.rubyonrails.org/">here</a>.</p>"
241 textilized
= RedCloth
.new(text
, [ :hard_breaks ])
242 textilized
.hard_breaks
= true if textilized
.respond_to
?(:hard_breaks=)
247 # Returns the text with all the Textile codes turned into HTML tags,
248 # but without the bounding <p> tag that RedCloth adds.
250 # You can learn more about Textile's syntax at its website[http://www.textism.com/tools/textile].
251 # <i>This method is requires RedCloth[http://whytheluckystiff.net/ruby/redcloth/]
252 # to be available</i>.
255 # textilize_without_paragraph("*This is Textile!* Rejoice!")
256 # # => "<strong>This is Textile!</strong> Rejoice!"
258 # textilize_without_paragraph("I _love_ ROR(Ruby on Rails)!")
259 # # => "I <em>love</em> <acronym title="Ruby on Rails">ROR</acronym>!"
261 # textilize_without_paragraph("h2. Textile makes markup -easy- simple!")
262 # # => "<h2>Textile makes markup <del>easy</del> simple!</h2>"
264 # textilize_without_paragraph("Visit the Rails website "here":http://www.rubyonrails.org/.)
265 # # => "Visit the Rails website <a href="http://www.rubyonrails.org/">here</a>."
266 def textilize_without_paragraph(text
)
267 textiled
= textilize(text
)
268 if textiled
[0..2] == "<p>" then textiled
= textiled
[3..-1] end
269 if textiled
[-4..-1] == "</p>" then textiled
= textiled
[0..-5] end
273 # Returns the text with all the Markdown codes turned into HTML tags.
274 # <i>This method requires BlueCloth[http://www.deveiate.org/projects/BlueCloth]
275 # to be available</i>.
278 # markdown("We are using __Markdown__ now!")
279 # # => "<p>We are using <strong>Markdown</strong> now!</p>"
281 # markdown("We like to _write_ `code`, not just _read_ it!")
282 # # => "<p>We like to <em>write</em> <code>code</code>, not just <em>read</em> it!</p>"
284 # markdown("The [Markdown website](http://daringfireball.net/projects/markdown/) has more information.")
285 # # => "<p>The <a href="http://daringfireball.net/projects/markdown/">Markdown website</a>
286 # # has more information.</p>"
288 # markdown('![The ROR logo](http://rubyonrails.com/images/rails.png "Ruby on Rails")')
289 # # => '<p><img src="http://rubyonrails.com/images/rails.png" alt="The ROR logo" title="Ruby on Rails" /></p>'
291 text
.blank
? ? "" : BlueCloth
.new(text
).to_html
294 # Returns +text+ transformed into HTML using simple formatting rules.
295 # Two or more consecutive newlines(<tt>\n\n</tt>) are considered as a
296 # paragraph and wrapped in <tt><p></tt> tags. One newline (<tt>\n</tt>) is
297 # considered as a linebreak and a <tt><br /></tt> tag is appended. This
298 # method does not remove the newlines from the +text+.
300 # You can pass any HTML attributes into <tt>html_options</tt>. These
301 # will be added to all created paragraphs.
303 # my_text = "Here is some basic text...\n...with a line break."
305 # simple_format(my_text)
306 # # => "<p>Here is some basic text...\n<br />...with a line break.</p>"
308 # more_text = "We want to put a paragraph...\n\n...right there."
310 # simple_format(more_text)
311 # # => "<p>We want to put a paragraph...</p>\n\n<p>...right there.</p>"
313 # simple_format("Look ma! A class!", :class => 'description')
314 # # => "<p class='description'>Look ma! A class!</p>"
315 def simple_format(text
, html_options
={})
316 start_tag
= tag('p', html_options
, true)
318 text
.gsub
!(/\r\n?/, "\n") # \r\n and \r -> \n
319 text
.gsub
!(/\n\n+/, "</p>\n\n#{start_tag}") # 2+ newline -> paragraph
320 text
.gsub
!(/([^\n]\n)(?=[^\n])/, '\1<br />') # 1 newline -> br
321 text
.insert
0, start_tag
325 # Turns all URLs and e-mail addresses into clickable links. The <tt>:link</tt> option
326 # will limit what should be linked. You can add HTML attributes to the links using
327 # <tt>:href_options</tt>. Possible values for <tt>:link</tt> are <tt>:all</tt> (default),
328 # <tt>:email_addresses</tt>, and <tt>:urls</tt>. If a block is given, each URL and
329 # e-mail address is yielded and the result is used as the link text.
332 # auto_link("Go to http://www.rubyonrails.org and say hello to david@loudthinking.com")
333 # # => "Go to <a href=\"http://www.rubyonrails.org\">http://www.rubyonrails.org</a> and
334 # # say hello to <a href=\"mailto:david@loudthinking.com\">david@loudthinking.com</a>"
336 # auto_link("Visit http://www.loudthinking.com/ or e-mail david@loudthinking.com", :link => :urls)
337 # # => "Visit <a href=\"http://www.loudthinking.com/\">http://www.loudthinking.com/</a>
338 # # or e-mail david@loudthinking.com"
340 # auto_link("Visit http://www.loudthinking.com/ or e-mail david@loudthinking.com", :link => :email_addresses)
341 # # => "Visit http://www.loudthinking.com/ or e-mail <a href=\"mailto:david@loudthinking.com\">david@loudthinking.com</a>"
343 # post_body = "Welcome to my new blog at http://www.myblog.com/. Please e-mail me at me@email.com."
344 # auto_link(post_body, :href_options => { :target => '_blank' }) do |text|
347 # # => "Welcome to my new blog at <a href=\"http://www.myblog.com/\" target=\"_blank\">http://www.m...</a>.
348 # Please e-mail me at <a href=\"mailto:me@email.com\">me@email.com</a>."
351 # You can still use <tt>auto_link</tt> with the old API that accepts the
352 # +link+ as its optional second parameter and the +html_options+ hash
353 # as its optional third parameter:
354 # post_body = "Welcome to my new blog at http://www.myblog.com/. Please e-mail me at me@email.com."
355 # auto_link(post_body, :urls) # => Once upon\na time
356 # # => "Welcome to my new blog at <a href=\"http://www.myblog.com/\">http://www.myblog.com</a>.
357 # Please e-mail me at me@email.com."
359 # auto_link(post_body, :all, :target => "_blank") # => Once upon\na time
360 # # => "Welcome to my new blog at <a href=\"http://www.myblog.com/\" target=\"_blank\">http://www.myblog.com</a>.
361 # Please e-mail me at <a href=\"mailto:me@email.com\">me@email.com</a>."
362 def auto_link(text
, *args
, &block
)#link = :all, href_options = {}, &block)
363 return '' if text
.blank
?
365 options
= args
.size
== 2 ? {} : args
.extract_options
! # this is necessary because the old auto_link API has a Hash as its last parameter
367 options
[:link] = args
[0] || :all
368 options
[:html] = args
[1] || {}
370 options
.reverse_merge
!(:link => :all, :html => {})
372 case options
[:link].to_sym
373 when :all then auto_link_email_addresses(auto_link_urls(text
, options
[:html], &block
), options
[:html], &block
)
374 when :email_addresses then auto_link_email_addresses(text
, options
[:html], &block
)
375 when :urls then auto_link_urls(text
, options
[:html], &block
)
379 # Creates a Cycle object whose _to_s_ method cycles through elements of an
380 # array every time it is called. This can be used for example, to alternate
381 # classes for table rows. You can use named cycles to allow nesting in loops.
382 # Passing a Hash as the last parameter with a <tt>:name</tt> key will create a
383 # named cycle. The default name for a cycle without a +:name+ key is
384 # <tt>"default"</tt>. You can manually reset a cycle by calling reset_cycle
385 # and passing the name of the cycle. The current cycle string can be obtained
386 # anytime using the current_cycle method.
389 # # Alternate CSS classes for even and odd numbers...
392 # <% @items.each do |item| %>
393 # <tr class="<%= cycle("even", "odd") -%>">
400 # # Cycle CSS classes for rows, and text colors for values within each row
401 # @items = x = [{:first => 'Robert', :middle => 'Daniel', :last => 'James'},
402 # {:first => 'Emily', :middle => 'Shannon', :maiden => 'Pike', :last => 'Hicks'},
403 # {:first => 'June', :middle => 'Dae', :last => 'Jones'}]
404 # <% @items.each do |item| %>
405 # <tr class="<%= cycle("even", "odd", :name => "row_class") -%>">
407 # <% item.values.each do |value| %>
408 # <%# Create a named cycle "colors" %>
409 # <span style="color:<%= cycle("red", "green", "blue", :name => "colors") -%>">
413 # <% reset_cycle("colors") %>
417 def cycle(first_value
, *values
)
418 if (values
.last
.instance_of
? Hash
)
424 values
.unshift(first_value
)
426 cycle
= get_cycle(name
)
427 if (cycle
.nil? || cycle
.values
!= values
)
428 cycle
= set_cycle(name
, Cycle
.new(*values
))
433 # Returns the current cycle string after a cycle has been started. Useful
434 # for complex table highlighing or any other design need which requires
435 # the current cycle string in more than one place.
438 # # Alternate background colors
440 # <% @items.each do |item| %>
441 # <div style="background-color:<%= cycle("red","white","blue") %>">
442 # <span style="background-color:<%= current_cycle %>"><%= item %></span>
445 def current_cycle(name
= "default")
446 cycle
= get_cycle(name
)
447 cycle
.current_value
unless cycle
.nil?
450 # Resets a cycle so that it starts from the first element the next time
451 # it is called. Pass in +name+ to reset a named cycle.
454 # # Alternate CSS classes for even and odd numbers...
455 # @items = [[1,2,3,4], [5,6,3], [3,4,5,6,7,4]]
457 # <% @items.each do |item| %>
458 # <tr class="<%= cycle("even", "odd") -%>">
459 # <% item.each do |value| %>
460 # <span style="color:<%= cycle("#333", "#666", "#999", :name => "colors") -%>">
465 # <% reset_cycle("colors") %>
469 def reset_cycle(name
= "default")
470 cycle
= get_cycle(name
)
471 cycle
.reset
unless cycle
.nil?
477 def initialize(first_value
, *values
)
478 @values = values
.unshift(first_value
)
487 @values[previous_index
].to_s
491 value
= @values[@index].to_s
507 (@index + n
) % @values.size
512 # The cycle helpers need to store the cycles in a place that is
513 # guaranteed to be reset every time a page is rendered, so it
514 # uses an instance variable of ActionView::Base.
516 @_cycles = Hash
.new
unless defined?(@_cycles)
517 return @_cycles[name
]
520 def set_cycle(name
, cycle_object
)
521 @_cycles = Hash
.new
unless defined?(@_cycles)
522 @_cycles[name
] = cycle_object
526 ( https
?:// | www\
. )
528 }x
unless const_defined
?(:AUTO_LINK_RE)
530 BRACKETS
= { ']' => '[', ')' => '(', '}' => '{' }
532 # Turns all urls into clickable links. If a block is given, each url
533 # is yielded and the result is used as the link text.
534 def auto_link_urls(text
, html_options
= {})
535 link_attributes
= html_options
.stringify_keys
536 text
.gsub(AUTO_LINK_RE
) do
540 # detect already linked URLs and URLs in the middle of a tag
541 if left =~ /<[^>]+$/ && right =~ /^[^>]*>/
542 # do not change string; URL is alreay linked
545 # don't include trailing punctuation character as part of the URL
546 if href.sub!(/[^\w\/-]$/, '') and punctuation = $& and opening = BRACKETS[punctuation]
547 if href.scan(opening).size > href.scan(punctuation).size
553 link_text = block_given?? yield(href) : href
554 href = 'http://' + href unless href.index('http') == 0
556 content_tag(:a, h(link_text), link_attributes.merge('href' => href)) + punctuation
561 # Turns all email addresses into clickable links. If a block is given,
562 # each email is yielded and the result is used as the link text.
563 def auto_link_email_addresses(text, html_options = {})
565 text.gsub(/([\w\.!#\$%\-+.]+@[A-Za-z0-9\-]+(\.[A-Za-z0-9\-]+)+)/) do
568 if body.match(/<a\b[^>]*>(.*)(#{Regexp.escape(text)})(.*)<\/a>/)
571 display_text = (block_given?) ? yield(text) : text
572 mail_to text, display_text, html_options