From b00e6a984df51a2f891c2a4c819ac2ab08359eed Mon Sep 17 00:00:00 2001 From: David Heinemeier Hansson Date: Sat, 23 Jun 2007 17:49:18 +0000 Subject: Massive documentation update for all helpers (closes #8223, #8177, #8175, #8108, #7977, #7972, #7971, #7969) [jeremymcanally] git-svn-id: http://svn-commit.rubyonrails.org/rails/trunk@7106 5ecf4fe2-1ee6-0310-87b1-e25e094e27de --- actionpack/lib/action_view/helpers/text_helper.rb | 266 ++++++++++++++++++---- 1 file changed, 218 insertions(+), 48 deletions(-) (limited to 'actionpack/lib/action_view/helpers/text_helper.rb') diff --git a/actionpack/lib/action_view/helpers/text_helper.rb b/actionpack/lib/action_view/helpers/text_helper.rb index d986233796..8db8ce7009 100644 --- a/actionpack/lib/action_view/helpers/text_helper.rb +++ b/actionpack/lib/action_view/helpers/text_helper.rb @@ -3,35 +3,48 @@ require 'html/document' module ActionView module Helpers #:nodoc: - # The TextHelper Module provides a set of methods for filtering, formatting - # and transforming strings that can reduce the amount of inline Ruby code in + # 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 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... + # within your template files. module TextHelper # 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. + # output text within a non-output code block (i.e., <% %>), you can use the concat method. # - # <% concat "hello", binding %> - # is equivalent to using: - # <%= "hello" %> + # ==== Examples + # <% + # 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 + # %> def concat(string, binding) eval(ActionView::Base.erb_variable, binding) << string 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+. + # +length+ (defaults to 30) and the last three characters will be replaced with the +truncate_string+ + # (defaults to "..."). # + # ==== Examples # truncate("Once upon a time in a world far far away", 14) - # => Once upon a... + # # => 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) def truncate(text, length = 30, truncate_string = "...") if text.nil? then return end l = length - truncate_string.chars.length @@ -40,13 +53,21 @@ module ActionView # 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. + # as a single-quoted string with \1 where the phrase is to be inserted (defaults to + # '\1') # + # ==== Examples # highlight('You searched for: rails', 'rails') # # => You searched for: rails # + # highlight('You searched for: ruby, rails, dhh', 'actionpack') + # # => You searched for: ruby, rails, dhh + # # highlight('You searched for: rails', ['for', 'rails'], '\1') # # => You searched for: rails + # + # highlight('You searched for: rails', 'rails', "\1") + # # => You searched for: \1') if text.blank? || phrases.blank? text @@ -57,16 +78,26 @@ module ActionView 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+, + # The +radius+ expands the excerpt on each side of the first occurance 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. # + # ==== Examples # excerpt('This is an example', 'an', 5) - # => "...s is an examp..." + # # => "...s is an examp..." # # excerpt('This is an example', 'is', 5) - # => "This is an..." + # # => "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, ' ') + # # => " is also an example" def excerpt(text, phrase, radius = 100, excerpt_string = "...") if text.nil? || phrase.nil? then return end phrase = Regexp.escape(phrase) @@ -89,9 +120,18 @@ module ActionView # 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 + # ==== Examples + # pluralize(1, 'person') + # # => 1 person + # + # pluralize(2, 'person') + # # => 2 people + # + # pluralize(3, 'person', 'users') + # # => 3 users + # + # pluralize(0, 'person') + # # => 0 people def pluralize(count, singular, plural = nil) "#{count || 0} " + if count == 1 || count == '1' singular @@ -105,10 +145,21 @@ module ActionView 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+. + # breaks on the first whitespace character that does not exceed +line_width+ + # (which is 80 by default). # + # ==== Examples # word_wrap('Once upon a time', 4) - # => Once\nupon\na\ntime + # # => 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 def word_wrap(text, line_width = 80) text.gsub(/\n/, "\n\n").gsub(/(.{1,#{line_width}})(\s+|$)/, "\\1\n").strip end @@ -116,9 +167,24 @@ module ActionView begin require_library_or_gem "redcloth" unless Object.const_defined?(:RedCloth) - # Returns the text with all the Textile codes turned into HTML tags. + # Returns the text with all the Textile[http://www.textism.com/tools/textile] codes turned into HTML tags. + # + # You can learn more about Textile's syntax at its website[http://www.textism.com/tools/textile]. # This method is only available if RedCloth[http://whytheluckystiff.net/ruby/redcloth/] # is available. + # + # ==== Examples + # textilize("*This is Textile!* Rejoice!") + # # => "

This is Textile! Rejoice!

" + # + # textilize("I _love_ ROR(Ruby on Rails)!") + # # => "

I love ROR!

" + # + # textilize("h2. Textile makes markup -easy- simple!") + # # => "

Textile makes markup easy simple!

" + # + # textilize("Visit the Rails website "here":http://www.rubyonrails.org/.) + # # => "

Visit the Rails website here.

" def textilize(text) if text.blank? "" @@ -131,8 +197,23 @@ module ActionView # Returns the text with all the Textile codes turned into HTML tags, # but without the bounding

tag that RedCloth adds. + # + # You can learn more about Textile's syntax at its website[http://www.textism.com/tools/textile]. # This method is only available if RedCloth[http://whytheluckystiff.net/ruby/redcloth/] # is available. + # + # ==== Examples + # textilize_without_paragraph("*This is Textile!* Rejoice!") + # # => "This is Textile! Rejoice!" + # + # textilize_without_paragraph("I _love_ ROR(Ruby on Rails)!") + # # => "I love ROR!" + # + # textilize_without_paragraph("h2. Textile makes markup -easy- simple!") + # # => "

Textile makes markup easy simple!

" + # + # textilize_without_paragraph("Visit the Rails website "here":http://www.rubyonrails.org/.) + # # => "Visit the Rails website here." def textilize_without_paragraph(text) textiled = textilize(text) if textiled[0..2] == "

" then textiled = textiled[3..-1] end @@ -149,6 +230,20 @@ module ActionView # Returns the text with all the Markdown codes turned into HTML tags. # This method is only available if BlueCloth[http://www.deveiate.org/projects/BlueCloth] # is available. + # + # ==== Examples + # markdown("We are using __Markdown__ now!") + # # => "

We are using Markdown now!

" + # + # markdown("We like to _write_ `code`, not just _read_ it!") + # # => "

We like to write code, not just read it!

" + # + # markdown("The [Markdown website](http://daringfireball.net/projects/markdown/) has more information.") + # # => "

The Markdown website + # # has more information.

" + # + # markdown('![The ROR logo](http://rubyonrails.com/images/rails.png "Ruby on Rails")') + # # => '

The ROR logo

' def markdown(text) text.blank? ? "" : BlueCloth.new(text).to_html end @@ -161,6 +256,20 @@ module ActionView # paragraph and wrapped in

tags. One newline (\n) is # considered as a linebreak and a
tag is appended. This # method does not remove the newlines from the +text+. + # + # ==== Examples + # my_text = """Here is some basic text... + # ...with a line break.""" + # + # simple_format(my_text) + # # => "

Here is some basic text...
...with a line break.

" + # + # more_text = """We want to put a paragraph... + # + # ...right there.""" + # + # simple_format(more_text) + # # => "

We want to put a paragraph...

...right there.

" def simple_format(text) content_tag 'p', text.to_s. gsub(/\r\n?/, "\n"). # \r\n and \r -> \n @@ -168,21 +277,31 @@ module ActionView gsub(/([^\n]\n)(?=[^\n])/, '\1
') # 1 newline -> br end - # 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 + # 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. + # :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. + # + # ==== Examples + # auto_link("Go to http://www.rubyonrails.org and say hello to david@loudthinking.com") + # # => "Go to http://www.rubyonrails.org and + # # say hello to david@loudthinking.com" # - # auto_link("Go to http://www.rubyonrails.org and say hello to david@loudthinking.com") => - # Go to http://www.rubyonrails.org and - # say hello to david@loudthinking.com + # auto_link("Visit http://www.loudthinking.com/ or e-mail david@loudthinking.com", :urls) + # # => "Visit http://www.loudthinking.com/ + # # or e-mail david@loudthinking.com" # - # If a block is given, each url and email address is yielded and the - # result is used as the link text. + # auto_link("Visit http://www.loudthinking.com/ or e-mail david@loudthinking.com", :email_addresses) + # # => "Visit http://www.loudthinking.com/ or e-mail david@loudthinking.com" # - # auto_link(post.body, :all, :target => '_blank') do |text| + # 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 http://www.m.... + # Please e-mail me at me@email.com." + # def auto_link(text, link = :all, href_options = {}, &block) return '' if text.blank? case link @@ -192,10 +311,17 @@ module ActionView end end - # Strips link tags from +text+ leaving just the link label. + # Strips all link tags from +text+ leaving just the link text. # + # ==== Examples # strip_links('Ruby on Rails') - # => Ruby on Rails + # # => Ruby on Rails + # + # strip_links('Please e-mail me at me@email.com.') + # # => Please e-mail me at me@email.com. + # + # strip_links('Blog: Visit.') + # # => Blog: Visit def strip_links(text) text.gsub(/(.*?)<\/a>/mi, '\1') end @@ -204,15 +330,23 @@ module ActionView VERBOTEN_ATTRS = /^on/i unless defined?(VERBOTEN_ATTRS) # Sanitizes the +html+ by converting
and ') - # => <script> do_nasty_stuff() </script> + # # => <script> do_nasty_stuff() </script> + # # sanitize('Click here for $100') - # => Click here for $100 + # # => Click here for $100 + # + # sanitize('Click here!!!') + # # => Click here!!! + # + # sanitize('') + # # => def sanitize(html) # only do this if absolutely necessary if html.index("<") @@ -248,6 +382,16 @@ module ActionView # 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. + # + # ==== Examples + # strip_tags("Strip these tags!") + # # => Strip these tags! + # + # strip_tags("Bold no more! See more here...") + # # => Bold no more! See more here... + # + # strip_tags("
Welcome to my website!
") + # # => Welcome to my website! def strip_tags(html) return html if html.blank? if html.index("<") @@ -269,25 +413,34 @@ module ActionView # 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: + # 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. # + # ==== Examples + # # Alternate CSS classes for even and odd numbers... + # @items = [1,2,3,4] + # # <% @items.each do |item| %> # "> # # # <% end %> + #
item
# - # 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. # + # # 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| %> # "row_class") # # <% item.values.each do |value| %> + # # "colors") -%>"> - # value + # <%= value %> # # <% end %> # <% reset_cycle("colors") %> @@ -312,6 +465,23 @@ module ActionView # 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. + # + # ==== Example + # # Alternate CSS classes for even and odd numbers... + # @items = [[1,2,3,4], [5,6,3], [3,4,5,6,7,4]] + # + # <% @items.each do |item| %> + # "> + # <% item.each do |value| %> + # "colors") -%>"> + # <%= value %> + # + # <% end %> + # + # <% reset_cycle("colors") %> + # + # <% end %> + #
def reset_cycle(name = "default") cycle = get_cycle(name) cycle.reset unless cycle.nil? -- cgit v1.2.3