Changeset 7106

Timestamp:

06/23/07 17:49:18 (2 years ago)

Author:

david

Message:

Massive documentation update for all helpers (closes #8223, #8177, #8175, #8108, #7977, #7972, #7971, #7969) [jeremymcanally]

Files:

• trunk/actionpack/lib/action_view/helpers/asset_tag_helper.rb (modified) (16 diffs)
• trunk/actionpack/lib/action_view/helpers/benchmark_helper.rb (modified) (1 diff)
• trunk/actionpack/lib/action_view/helpers/cache_helper.rb (modified) (1 diff)
• trunk/actionpack/lib/action_view/helpers/capture_helper.rb (modified) (2 diffs)
• trunk/actionpack/lib/action_view/helpers/date_helper.rb (modified) (14 diffs)
• trunk/actionpack/lib/action_view/helpers/form_tag_helper.rb (modified) (7 diffs)
• trunk/actionpack/lib/action_view/helpers/number_helper.rb (modified) (6 diffs)
• trunk/actionpack/lib/action_view/helpers/tag_helper.rb (modified) (5 diffs)
• trunk/actionpack/lib/action_view/helpers/text_helper.rb (modified) (17 diffs)

trunk/actionpack/lib/action_view/helpers/asset_tag_helper.rb

@@ -5 +5 @@
-module ActionView
-  module Helpers #:nodoc:
-
-
-
-
-
+
+
+
+
+
+
+
+
+
-    #
-    #   ActionController::Base.asset_host = "assets.example.com"
@@ -17 +21 @@
-    #     => <link href="http://assets.example.com/stylesheets/application.css" media="screen" rel="Stylesheet" type="text/css" />
-    #
-
-
-
-
-
-
-
-
-
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
-    # for server load balancing. See http://www.die.net/musings/page_load_time/
-    # for background.
@@ -38 +49 @@
-      # +url_options+. You can modify the LINK tag itself in +tag_options+.
-      #
-Tag
+====
-      # * <tt>:rel</tt>  - Specify the relation of this link, defaults to "alternate"
-      # * <tt>:type</tt>  - Override the auto-generated mime type
-      # * <tt>:title</tt>  - Specify the title of the link, defaults to the +type+
-      #
+      # ==== Examples
-      #  auto_discovery_link_tag # =>
-
+r
-      #  auto_discovery_link_tag(:atom) # =>
-
+r
-      #  auto_discovery_link_tag(:rss, {:action => "feed"}) # =>
-
+r
-      #  auto_discovery_link_tag(:rss, {:action => "feed"}, {:title => "My RSS"}) # =>
-
+
+
+
+
+
-      def auto_discovery_link_tag(type = :rss, url_options = {}, tag_options = {})
-        tag(
@@ -66 +82 @@
-      # Used internally by javascript_include_tag to build the script path.
-      #
+      # ==== Examples
-      #   javascript_path "xmlhr" # => /javascripts/xmlhr.js
-      #   javascript_path "dir/xmlhr.js" # => /javascripts/dir/xmlhr.js
-      #   javascript_path "/dir/xmlhr" # => /dir/xmlhr.js
+      #   javascript_path "http://www.railsapplication.com/js/xmlhr" # => http://www.railsapplication.com/js/xmlhr.js
+      #   javascript_path "http://www.railsapplication.com/js/xmlhr.js" # => http://www.railsapplication.com/js/xmlhr.js
-      def javascript_path(source)
-        compute_public_path(source, 'javascripts', 'js')
@@ -86 +105 @@
-      # html attributes of the script tag by passing a hash as the last argument.
-      #
+      # ==== Examples
-      #   javascript_include_tag "xmlhr" # =>
+      #     <script type="text/javascript" src="/javascripts/xmlhr.js"></script>
+      #
+      #   javascript_include_tag "xmlhr.js" # =>
-      #     <script type="text/javascript" src="/javascripts/xmlhr.js"></script>
-      #
@@ -92 +115 @@
-      #     <script type="text/javascript" src="/javascripts/common.javascript"></script>
-      #     <script type="text/javascript" src="/elsewhere/cools.js"></script>
+      #
+      #   javascript_include_tag "http://www.railsapplication.com/xmlhr" # =>
+      #     <script type="text/javascript" src="http://www.railsapplication.com/xmlhr.js"></script>
+      #
+      #   javascript_include_tag "http://www.railsapplication.com/xmlhr.js" # =>
+      #     <script type="text/javascript" src="http://www.railsapplication.com/xmlhr.js"></script>
-      #
-      #   javascript_include_tag :defaults # =>
@@ -97 +126 @@
-      #     <script type="text/javascript" src="/javascripts/effects.js"></script>
-      #     ...
-*see below
+<!-- * see below -->
-      #
-      # * = The application.js file is only referenced if it exists
-      #
-
+
+
+
+
-      #
-      #   javascript_include_tag :all # =>
@@ -111 +143 @@
-      #     <script type="text/javascript" src="/javascripts/checkout.js"></script>
-      #
-for
- They
+to
+
-      #
-      # == Caching multiple javascripts into one
-      #
-
+to download 
-      # compressed by gzip (leading to faster transfers). Caching will only happen if ActionController::Base.perform_caching
-
-
-
+
+
+
+
-      #   javascript_include_tag :all, :cache => true # when ActionController::Base.perform_caching is false =>
-      #     <script type="text/javascript" src="/javascripts/prototype.js"></script>
@@ -169 +202 @@
-      # Register one or more additional JavaScript files to be included when
-      # <tt>javascript_include_tag :defaults</tt> is called. This method is
-on
+typical
-      # .js files that the plugin installed in <tt>public/javascripts</tt>.
-      def self.register_javascript_include_default(*sources)
@@ -184 +217 @@
-      # Used internally by stylesheet_link_tag to build the stylesheet path.
-      #
+      # ==== Examples
-      #   stylesheet_path "style" # => /stylesheets/style.css
-      #   stylesheet_path "dir/style.css" # => /stylesheets/dir/style.css
-      #   stylesheet_path "/dir/style.css" # => /dir/style.css
+      #   stylesheet_path "http://www.railsapplication.com/css/style" # => http://www.railsapplication.com/css/style.css
+      #   stylesheet_path "http://www.railsapplication.com/css/style.js" # => http://www.railsapplication.com/css/style.css
-      def stylesheet_path(source)
-        compute_public_path(source, 'stylesheets', 'css')
@@ -195 +231 @@
-      # You can modify the link attributes by passing a hash as the last argument.
-      #
+      # ==== Examples
-      #   stylesheet_link_tag "style" # =>
-      #     <link href="/stylesheets/style.css" media="screen" rel="Stylesheet" type="text/css" />
-      #
+      #   stylesheet_link_tag "style.css" # =>
+      #     <link href="/stylesheets/style.css" media="screen" rel="Stylesheet" type="text/css" />
+      #
+      #   stylesheet_link_tag "http://www.railsapplication.com/style.css" # =>
+      #     <link href="http://www.railsapplication.com/style.css" media="screen" rel="Stylesheet" type="text/css" />
+      #
-      #   stylesheet_link_tag "style", :media => "all" # =>
-      #     <link href="/stylesheets/style.css" media="all" rel="Stylesheet" type="text/css" />
+      #
+      #   stylesheet_link_tag "style", :media => "print" # =>
+      #     <link href="/stylesheets/style.css" media="print" rel="Stylesheet" type="text/css" />
-      #
-      #   stylesheet_link_tag "random.styles", "/css/stylish" # =>
@@ -219 +265 @@
-      # environment). Examples:
-      #
+      # ==== Examples
-      #   stylesheet_link_tag :all, :cache => true # when ActionController::Base.perform_caching is false =>
-      #     <link href="/stylesheets/style1.css"  media="screen" rel="Stylesheet" type="text/css" />
@@ -272 +319 @@
-      # a filename without an extension is deprecated.
-      #
+      # ==== Examples
-      #   image_path("edit.png")  # => /images/edit.png
-      #   image_path("icons/edit.png")  # => /images/icons/edit.png
-      #   image_path("/icons/edit.png")  # => /icons/edit.png
+      #   image_path("http://www.railsapplication.com/img/edit.png") # => http://www.railsapplication.com/img/edit.png
-      def image_path(source)
-        unless (source.split("/").last || source).include?(".") || source.blank?
@@ -290 +339 @@
-      # path or a file that exists in your public images directory. Note that
-      # specifying a filename without the extension is now deprecated in Rails.
-
+
+
+
-      # two additional keys for convienence and conformance:
-      #
@@ -299 +350 @@
-      #   value is not in the correct format.
-      #
+      # ==== Examples
-      #  image_tag("icon.png")  # =>
-      #    <img src="/images/icon.png" alt="Icon" />
@@ -305 +357 @@
-      #  image_tag("/icons/icon.gif", :size => "16x16")  # =>
-      #    <img src="/icons/icon.gif" width="16" height="16" alt="Icon" />
+      #  image_tag("/icons/icon.gif", :height => '32', :width => '32') # =>
+      #    <img alt="Icon" height="32" src="/icons/icon.gif" width="32" />
+      #  image_tag("/icons/icon.gif", :class => "menu_icon") # =>
+      #    <img alt="Icon" class="menu_icon" src="/icons/icon.gif" />
-      def image_tag(source, options = {})
-        options.symbolize_keys!

trunk/actionpack/lib/action_view/helpers/benchmark_helper.rb

@@ -3 +3 @@
-module ActionView
-  module Helpers
+    # This helper offers a method to measure the execution time of a block 
+    # in a template.
-    module BenchmarkHelper
-
+
+
+
+
+
-      #
-Notes section
-not
+Process data files
+fil
-      #  <% end %>
-      #
-
+
+
-      #
-      # You may give an optional logger level as the second argument
-.  The default
+; the default value
-      def benchmark(message = "Benchmarking", level = :info)
-        if @logger

trunk/actionpack/lib/action_view/helpers/cache_helper.rb

@@ -1 +1 @@
-module ActionView
-  module Helpers
+    # This helper to exposes a method for caching of view fragments.
-    # See ActionController::Caching::Fragments for usage instructions.
-    module CacheHelper
+      # A method for caching fragments of a view rather than an entire
+      # action or page.  This technique is useful caching pieces like
+      # menus, lists of news topics, static HTML fragments, and so on.
+      # This method takes a block that contains the content you wish
+      # to cache.  See ActionController::Caching::Fragments for more
+      # information.
+      #
+      # ==== Examples
+      # If you wanted to cache a navigation menu, you could do the
+      # following.
+      #
+      #   <% cache do %>
+      #     <%= render :partial => "menu" %>
+      #   <% end %>
+      #
+      # You can also cache static content...
+      #
+      #   <% cache do %>
+      #      <p>Hello users!  Welcome to our website!</p>
+      #   <% end %>
+      #
+      # ...and static content mixed with RHTML content.
+      #
+      #    <% cache do %>
+      #      Topics:
+      #      <%= render :partial => "topics", :collection => @topic_list %>
+      #      <i>Topics listed alphabetically</i>
+      #    <% end %>
-      def cache(name = {}, &block)
-        @controller.cache_erb_fragment(block, name)

trunk/actionpack/lib/action_view/helpers/capture_helper.rb

@@ -1 +1 @@
-module ActionView
-  module Helpers
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
+
+
+
+
-    module CaptureHelper
-
-
-
+
+
-      # 
-
+
+
-      # 
-      #   <% @greeting = capture do %>
-
+
+
-      #   <% end %>
-      #
-Example of capture being used in a .builder page:
+...and Builder (RXML) templates.
-      # 
-greeting
-'Welcome To my shiny new web page!'
+timestamp
+"The current timestamp is #{Time.now}."
-      #   end
+      #
+      # You can then use the content as a variable anywhere else.  For
+      # example:
+      #
+      #   <html>
+      #   <head><title><%= @greeting %></title></head>
+      #   <body>
+      #   <b><%= @greeting %></b>
+      #   </body></html>
+      #
-      def capture(*args, &block)
-        # execute the block
@@ -69 +47 @@
-      end
-      
-
-Subsequently, you can make calls to it by name with <tt>yield</tt>
-in another template or in the layout. 
+in an identifier 
+You can make subsequent calls to the stored content in another template or in the layout
+by calling it by name with <tt>yield</tt>.
-      # 
-Example:
+==== Examples
-      # 
-header
-hello world
+authorized
+You are not authorized for that!
-      #   <% end %>
-      #
-use yield :header
+then use <tt>yield :authorized</tt>
-      #
-
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
-      #
-      # NOTE: Beware that content_for is ignored in caches. So you shouldn't use it

trunk/actionpack/lib/action_view/helpers/date_helper.rb

@@ -38 +38 @@
-      # 60-89 secs      # => 1 minute
-      #
-
-
+
-      #   from_time = Time.now
-
-
-
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
-      #
-      # Note: Rails calculates one year as 365.25 days.
@@ -77 +89 @@
-
-      # Like distance_of_time_in_words, but where <tt>to_time</tt> is fixed to <tt>Time.now</tt>.
+      #
+      # ==== Examples
+      #   time_ago_in_words(3.minutes.from_now)       # => 3 minutes
+      #   time_ago_in_words(Time.now - 15.hours)      # => 15 hours
+      #   time_ago_in_words(Time.now)                 # => less than a minute
+      #
+      #   from_time = Time.now - 3.days - 14.minutes - 25.seconds     # => 3 days
-      def time_ago_in_words(from_time, include_seconds = false)
-        distance_of_time_in_words(from_time, Time.now, include_seconds)
@@ -97 +116 @@
-      # NOTE: Discarded selects will default to 1. So if no month select is available, January will be assumed.
-      #
-Examples:
-
+==== Examples
+   # Generates a date select that when POSTed is stored in the post variable, in the written_on attribute
-      #   date_select("post", "written_on")
+      #
+      #   # Generates a date select that when POSTed is stored in the post variable, in the written_on attribute,
+      #   # with the year in the year drop down box starting at 1995.
-      #   date_select("post", "written_on", :start_year => 1995)
+      #
+      #   # Generates a date select that when POSTed is stored in the post variable, in the written_on attribute,
+      #   # with the year in the year drop down box starting at 1995, numbers used for months instead of words,
+      #   # and without a day select box. 
-      #   date_select("post", "written_on", :start_year => 1995, :use_month_numbers => true,
-      #                                     :discard_day => true, :include_blank => true)
+      #
+      #   # Generates a date select that when POSTed is stored in the post variable, in the written_on attribute
+      #   # with the fields ordered as day, month, year rather than month, day, year.
-      #   date_select("post", "written_on", :order => [:day, :month, :year])
-
-
+
+
+
+
+
+
+
-      #   date_select("post", "written_on", :default => 3.days.from_now)
+      #
+      #   # Generates a date select that when POSTed is stored in the credit_card variable, in the bill_due attribute
+      #   # that will have a default day of 20.
-      #   date_select("credit_card", "bill_due", :default => { :day => 20 })
-      #
@@ -120 +157 @@
-      # time-based attribute (identified by +method+) on an object assigned to the template (identified by +object+).
-      # You can include the seconds with <tt>:include_seconds</tt>.
-
-
+
+
+
-      #   time_select("post", "sunrise")
+      #
+      #   # Creates a time select tag that, when POSTed, will be stored in the order variable in the submitted attribute
+      #   time_select("order", "submitted")
+      #
+      #   # Creates a time select tag that, when POSTed, will be stored in the mail variable in the sent_at attribute
+      #   time_select("mail", "sent_at")
+      #
+      #   # Creates a time select tag with a seconds field that, when POSTed, will be stored in the post variables in 
+      #   # the sunrise attribute. 
-      #   time_select("post", "start_time", :include_seconds => true)
+      #
+      #   # Creates a time select tag with a seconds field that, when POSTed, will be stored in the entry variables in 
+      #   # the submission_time attribute. 
+      #   time_select("entry", "submission_time", :include_seconds => true)
-      #
-      # The selects are prepared for multi-parameter assignment to an Active Record object.
@@ -136 +187 @@
-      # attribute (identified by +method+) on an object assigned to the template (identified by +object+). Examples:
-      #
+      # ==== Examples
+      #   # Generates a datetime select that, when POSTed, will be stored in the post variable in the written_on attribute
-      #   datetime_select("post", "written_on")
+      #
+      #   # Generates a datetime select with a year select that starts at 1995 that, when POSTed, will be stored in the 
+      #   # post variable in the written_on attribute.
-      #   datetime_select("post", "written_on", :start_year => 1995)
+      #
+      #   # Generates a datetime select with a default value of 3 days from the current time that, when POSTed, will be stored in the 
+      #   # trip variable in the departing attribute.
+      #   datetime_select("trip", "departing", :default => 3.days.from_now)
+      #
+      #   # Generates a datetime select that discards the type that, when POSTed, will be stored in the post variable as the written_on
+      #   # attribute.
+      #   datetime_select("post", "written_on", :discard_type => true)
-      #
-      # The selects are prepared for multi-parameter assignment to an Active Record object.
@@ -149 +213 @@
-      # will be appened onto the <tt>:order</tt> passed in. You can also add <tt>:date_separator</tt> and <tt>:time_separator</tt>
-      # keys to the +options+ to control visual display of the elements.
-
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
-        separator = options[:datetime_separator] || ''
-        select_date(datetime, options) + separator + select_time(datetime, options)
@@ -158 +248 @@
-      # symbols <tt>:year</tt>, <tt>:month</tt> and <tt>:day</tt> in the desired order. If you do not supply a Symbol, it
-      # will be appened onto the <tt>:order</tt> passed in.
+      #
+      # ==== Examples
+      #   my_date = Time.today + 6.days
+      #
+      #   # Generates a date select that defaults to the date in my_date (six days after today)
+      #   select_date(my_date)
+      #
+      #   # Generates a date select that defaults to today (no specified date)
+      #   select_date()
+      #
+      #   # Generates a date select that defaults to the date in my_date (six days after today)
+      #   # with the fields ordered year, month, day rather then month, day, year.
+      #   select_date(my_date, :order => [:year, :month, :day])
+      #
+      #   # Generates a date select that discards the type of the field and defaults to the date in 
+      #   # my_date (six days after today)
+      #   select_datetime(my_date_time, :discard_type => true)
+      #
+      #   # Generates a date select that defaults to the datetime in my_date (six days after today)
+      #   # prefixed with 'payday' rather than 'date'
+      #   select_datetime(my_date_time, :prefix => 'payday')
+      #
-      def select_date(date = Date.today, options = {})
-        options[:order] ||= []
@@ -170 +282 @@
-
-      # Returns a set of html select-tags (one for hour and minute)
-
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
-      def select_time(datetime = Time.now, options = {})
-        separator = options[:time_separator] || ''
@@ -179 +314 @@
-      # The <tt>second</tt> can also be substituted for a second number.
-      # Override the field name using the <tt>:field_name</tt> option, 'second' by default.
+      #
+      # ==== Examples
+      #   my_time = Time.now + 16.minutes
+      #
+      #   # Generates a select field for seconds that defaults to the seconds for the time in my_time
+      #   select_second(my_time)
+      #
+      #   # Generates a select field for seconds that defaults to the number given
+      #   select_second(33)
+      # 
+      #   # Generates a select field for seconds that defaults to the seconds for the time in my_time
+      #   # that is named 'interval' rather than 'second'
+      #   select_second(my_time, :field_name => 'interval')
+      #
-      def select_second(datetime, options = {})
-        val = datetime ? (datetime.kind_of?(Fixnum) ? datetime : datetime.sec) : ''
@@ -199 +348 @@
-      # The <tt>minute</tt> can also be substituted for a minute number.
-      # Override the field name using the <tt>:field_name</tt> option, 'minute' by default.
+      #
+      # ==== Examples
+      #   my_time = Time.now + 6.hours
+      #
+      #   # Generates a select field for minutes that defaults to the minutes for the time in my_time
+      #   select_minute(my_time)
+      #
+      #   # Generates a select field for minutes that defaults to the number given
+      #   select_minute(14)
+      # 
+      #   # Generates a select field for minutes that defaults to the minutes for the time in my_time
+      #   # that is named 'stride' rather than 'second'
+      #   select_minute(my_time, :field_name => 'stride')
+      #
-      def select_minute(datetime, options = {})
-        val = datetime ? (datetime.kind_of?(Fixnum) ? datetime : datetime.min) : ''
@@ -218 +381 @@
-      # The <tt>hour</tt> can also be substituted for a hour number.
-      # Override the field name using the <tt>:field_name</tt> option, 'hour' by default.
+      #
+      # ==== Examples
+      #   my_time = Time.now + 6.hours
+      #
+      #   # Generates a select field for minutes that defaults to the minutes for the time in my_time
+      #   select_minute(my_time)
+      #
+      #   # Generates a select field for minutes that defaults to the number given
+      #   select_minute(14)
+      # 
+      #   # Generates a select field for minutes that defaults to the minutes for the time in my_time
+      #   # that is named 'stride' rather than 'second'
+      #   select_minute(my_time, :field_name => 'stride')
+      #
-      def select_hour(datetime, options = {})
-        val = datetime ? (datetime.kind_of?(Fixnum) ? datetime : datetime.hour) : ''
@@ -237 +414 @@
-      # The <tt>date</tt> can also be substituted for a hour number.
-      # Override the field name using the <tt>:field_name</tt> option, 'day' by default.
+      #
+      # ==== Examples
+      #   my_date = Time.today + 2.days
+      #
+      #   # Generates a select field for days that defaults to the day for the date in my_date
+      #   select_day(my_time)
+      #
+      #   # Generates a select field for days that defaults to the number given
+      #   select_day(5)
+      # 
+      #   # Generates a select field for days that defaults to the day for the date in my_date
+      #   # that is named 'due' rather than 'day'
+      #   select_day(my_time, :field_name => 'due')
+      #
-      def select_day(date, options = {})
-        val = date ? (date.kind_of?(Fixnum) ? date : date.day) : ''
@@ -259 +450 @@
-      # set the <tt>:add_month_numbers</tt> key in +options+ to true. If you would prefer to show month names as abbreviations,
-      # set the <tt>:use_short_month</tt> key in +options+ to true. If you want to use your own month names, set the
-
-
-
-
-
-
-
-
-
-
-
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
-      def select_month(date, options = {})
-        val = date ? (date.kind_of?(Fixnum) ? date : date.month) : ''
@@ -299 +507 @@
-      # can be changed using the <tt>:start_year</tt> and <tt>:end_year</tt> keys in the +options+. Both ascending and descending year
-      # lists are supported by making <tt>:start_year</tt> less than or greater than <tt>:end_year</tt>. The <tt>date</tt> can also be
-
-
-
-
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
-      #   select_year(2006, :start_year => 2000, :end_year => 2010)
-      #
-      # Override the field name using the <tt>:field_name</tt> option, 'year' by default.
-      def select_year(date, options = {})
-        val = date ? (date.kind_of?(Fixnum) ? date : date.year) : ''

trunk/actionpack/lib/action_view/helpers/form_tag_helper.rb

@@ -4 +4 @@
-module ActionView
-  module Helpers
-conventions with an
-With the FormTagHelper, you provide the names and values yourself
+an ActiveRecord
+Instead, you provide the names and values manually
-    #
-html options disabled, readonly, and multiple can all be treated as booleans. So specifying <tt>:disabled => true</tt>
-
+HTML options <tt>disabled</tt>, <tt>readonly</tt>, and <tt>multiple</tt> can all be treated as booleans. So specifying 
+<tt>:disabled => true</tt> 
-    module FormTagHelper
-      # Starts a form tag that points the action to an url configured with <tt>url_for_options</tt> just like
-      # ActionController::Base#url_for. The method for the form defaults to POST.
-      #
-
-
-
-
-
-
-
-
-
-
-
-
-
-
+
-      # * <tt>:multipart</tt> - If set to true, the enctype is set to "multipart/form-data".
-      # * <tt>:method</tt>    - The method to use when submitting the form, usually either "get" or "post".
-      #                         If "put", "delete", or another verb is used, a hidden input with name _method 
-      #                         is added to simulate the verb over post.
+      # * A list of parameters to feed to the URL the form will be posted to.
+      #
+      # ==== Examples
+      #   form_tag('/posts')                      
+      #   # => <form action="/posts" method="post">
+      #
+      #   form_tag('/posts/1', :method => :put)   
+      #   # => <form action="/posts/1" method="put">
+      #
+      #   form_tag('/upload', :multipart => true) 
+      #   # => <form action="/upload" method="post" enctype="multipart/form-data">
+      # 
+      #   <% form_tag '/posts' do -%>
+      #     <div><%= submit_tag 'Save' %></div>
+      #   <% end -%>
+      #   # => <form action="/posts" method="post"><div><input type="submit" name="submit" value="Save" /></div></form>
-      def form_tag(url_for_options = {}, options = {}, *parameters_for_url, &block)
-        html_options = html_options_for_form(url_for_options, options, *parameters_for_url)
@@ -40 +43 @@
-      end
-
-
-      # Creates a dropdown selection box, or if the <tt>:multiple</tt> option is set to true, a multiple
-      # choice selection box.
-      #
-      # Helpers::FormOptions can be used to create common select boxes such as countries, time zones, or
-
-
-
-
+
+
+
+
+
+
+
+
-      #   select_tag "people", "<option>David</option>"
-
-
-
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
-      def select_tag(name, option_tags = nil, options = {})
-        content_tag :select, option_tags, { "name" => name, "id" => name }.update(options.stringify_keys)
-      end
-
-
-
-
+
+
+
+
-      # * <tt>:disabled</tt> - If set to true, the user will not be able to use this input.
-      # * <tt>:size</tt> - The number of visible characters that will fit in the input.
-      # * <tt>:maxlength</tt> - The maximum number of characters that the browser will allow the user to enter.
+      # * Any other key creates standard HTML attributes for the tag.
-      # 
-
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
-      def text_field_tag(name, value = nil, options = {})
-        tag :input, { "type" => "text", "name" => name, "id" => name, "value" => value }.update(options.stringify_keys)
-      end
-
-
-
-
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
-      def hidden_field_tag(name, value = nil, options = {})
-        text_field_tag(name, value, options.stringify_keys.update("type" => "hidden"))
-      end
-
-
-
- If you are using file uploads then you will also need to set the multipart option for the form:
+  If you are using file uploads then you will also need 
+ to set the multipart option for the form tag:
+
-      #   <%= form_tag { :action => "post" }, { :multipart => true } %>
-      #     <label for="file">File to Upload</label> <%= file_field_tag "file" %>
@@ -86 +145 @@
-      # The specified URL will then be passed a File object containing the selected file, or if the field 
-      # was left blank, a StringIO object.
+      #
+      # ==== Options
+      # * Creates standard HTML attributes for the tag.
+      # * <tt>:disabled</tt> - If set to true, the user will not be able to use this input.
+      #
+      # ==== Examples
+      #   file_field_tag 'attachment'
+      #   # => <input id="attachment" name="attachment" type="file" />
+      #
+      #   file_field_tag 'avatar', :class => 'profile-input'
+      #   # => <input class="profile-input" id="avatar" name="avatar" type="file" />
+      #
+      #   file_field_tag 'picture', :disabled => true
+      #   # => <input disabled="disabled" id="picture" name="picture" type="file" />
+      #
+      #   file_field_tag 'resume', :value => '~/resume.doc'
+      #   # => <input id="resume" name="resume" type="file" value="~/resume.doc" />
+      #
+      #   file_field_tag 'user_pic', :accept => 'image/png,image/gif,image/jpeg'
+      #   # => <input accept="image/png,image/gif,image/jpeg" id="user_pic" name="user_pic" type="file" /> 
+      #
+      #   file_field_tag 'file', :accept => 'text/html', :class => 'upload', :value => 'index.html'
+      #   # => <input accept="text/html" class="upload" id="file" name="file" type="file" value="index.html" />
-      def file_field_tag(name, options = {})
-        text_field_tag(name, nil, options.update("type" => "file"))
-      end
-
-
-
-
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
-      def password_field_tag(name = "password", value = nil, options = {})
-        text_field_tag(name, value, options.update("type" => "password"))
-      end
-
-
-
-
-
-
-
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
-      def text_area_tag(name, content = nil, options = {})
-        options.stringify_keys!
@@ -113 +242 @@
-      end
-
-
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
-      def check_box_tag(name, value = "1", checked = false, options = {})
-        html_options = { "type" => "checkbox", "name" => name, "id" => name, "value" => value }.update(options.stringify_keys)
@@ -120 +269 @@
-      end
-
-
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
-      def radio_button_tag(name, value, checked = false, options = {})
-        pretty_tag_value = value.to_s.gsub(/\s/, "_").gsub(/(?!-)\W/, "").downcase
@@ -129 +296 @@
-      end
-
-
-
-
-
-
-
-
-
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
-      def submit_tag(value = "Save changes", options = {})
-        options.stringify_keys!
@@ -158 +344 @@
-      #
-      # <tt>source</tt> is passed to AssetTagHelper#image_path
+      #
+      # ==== Options
+      # * <tt>:disabled</tt> - If set to true, the user will not be able to use this input.
+      # * Any other key creates standard HTML options for the tag.
+      #
+      # ==== Examples
+      #   image_submit_tag("login.png")
+      #   # => <input src="/images/login.png" type="image" />
+      #
+      #   image_submit_tag("purchase.png"), :disabled => true
+      #   # => <input disabled="disabled" src="/images/purchase.png" type="image" />
+      #
+      #   image_submit_tag("search.png"), :class => 'search-button'
+      #   # => <input class="search-button" src="/images/search.png" type="image" />
+      #
+      #   image_submit_tag("agree.png"), :disabled => true, :class => "agree-disagree-button"
+      #   # => <input class="agree-disagree-button" disabled="disabled" src="/images/agree.png" type="image" />
-      def image_submit_tag(source, options = {})
-        tag :input, { "type" => "image", "src" => image_path(source) }.update(options.stringify_keys)

trunk/actionpack/lib/action_view/helpers/number_helper.rb

@@ -5 +5 @@
-    # precision, positional notation, and file size.
-    module NumberHelper
-
+ (e.g., (555) 123-9876)
-      # in the +options+ hash.
+      #
+      # ==== Options
-      # * <tt>:area_code</tt>  - Adds parentheses around the area code.
-, defaults to "-"
+ (defaults to "-")
-      # * <tt>:extension</tt>  - Specifies an extension to add to the end of the
-
+.
-      # * <tt>:country_code</tt>  - Sets the country code for the phone number.
-      #
-
-
-
-
-
+
+
+
+
+
+
+
+
+
-      def number_to_phone(number, options = {})
-        number       = number.to_s.strip unless number.nil?
@@ -41 +47 @@
-      end
-
-
+ (e.g., $13.65)
-      # in the +options+ hash.
-      # * <tt>:precision</tt>  -  Sets the level of precision, defaults to 2
-      # * <tt>:unit</tt>  - Sets the denomination of the currency, defaults to "$"
-      # * <tt>:separator</tt>  - Sets the separator between the units, defaults to "."
-      # * <tt>:delimiter</tt>  - Sets the thousands delimiter, defaults to ","
-      #
-
-
-
+
+
+
+
+
+
+
+
+
+
+
-      #  number_to_currency(1234567890.50, :unit => "&pound;", :separator => ",", :delimiter => "")
-  
+#
-      def number_to_currency(number, options = {})
-        options   = options.stringify_keys
@@ -68 +78 @@
-      end
-
-
+ (e.g., 65%)
-      # format in the +options+ hash.
-      # * <tt>:precision</tt>  - Sets the level of precision, defaults to 3
-      # * <tt>:separator</tt>  - Sets the separator between the units, defaults to "."
-      #
-
-
-
+
+
+
+
+
+
+
+
+
+
-      def number_to_percentage(number, options = {})
-        options   = options.stringify_keys
@@ -94 +109 @@
-      end
-
-
+ (e.g., 12,324)
-      # can customize the format using optional <em>delimiter</em> and <em>separator</em> parameters.
-      # * <tt>delimiter</tt>  - Sets the thousands delimiter, defaults to ","
-      # * <tt>separator</tt>  - Sets the separator between the units, defaults to "."
-      #
-
-
-
+
+
+
+
+
+
+
+
+
+
+
-      def number_with_delimiter(number, delimiter=",", separator=".")
-        begin
@@ -112 +133 @@
-      end
-
-
+ (e.g., 112.32 has a precision of 2)
-      # level of precision is 3.
-      #
-
-
+
+
+
+
+
-      def number_with_precision(number, precision=3)
-        "%01.#{precision}f" % number
@@ -123 +147 @@
-      end
-
-
-
+
+
+
-      # +size+ cannot be converted into a number. You can change the default
-in
+using the precision parameter
-      #
-
-
-
-
-
-
-
+
+
+
+
+
+
+
+
+
-      def number_to_human_size(size, precision=1)
-        size = Kernel.Float(size)

trunk/actionpack/lib/action_view/helpers/tag_helper.rb

@@ -4 +4 @@
-module ActionView
-  module Helpers #:nodoc:
-Use these
+Provides
-    # a Builder. By default, they output XHTML compliant tags.
-    module TagHelper
@@ -12 +12 @@
-      # compliant. Setting +open+ to true will create an open tag compatible 
-      # with HTML 4.0 and below. Add HTML attributes by passing an attributes 
-
-
+
+
+
+
+
-      # symbols or strings for the attribute names.
-      #
+      # ==== Examples
-      #   tag("br")
-
+
+
-      #   tag("br", nil, true)
-
+
+
-      #   tag("input", { :type => 'text', :disabled => true }) 
-
+
+
+
+
-      def tag(name, options = nil, open = false)
-        "<#{name}#{tag_options(options) if options}" + (open ? ">" : " />")
@@ -27 +36 @@
-
-      # Returns an HTML block tag of type +name+ surrounding the +content+. Add
-For attributes 
-with no value like (disabled and readonly), give it a value of true in 
-the +options+ hash. You can use symbols or strings for the attribute names
+
+Instead of passing the content as an argument, you can also use a block
+in which case, you pass your +options+ as the second parameter
-      #
+      # ==== Options
+      # The +options+ hash is used with attributes with no value like (<tt>disabled</tt> and 
+      # <tt>readonly</tt>), which you can give a value of true in the +options+ hash. You can use
+      # symbols or strings for the attribute names.
+      #
+      # ==== Examples
-      #   content_tag(:p, "Hello world!")
-      #    # => <p>Hello world!</p>
@@ -37 +52 @@
-      #   content_tag("select", options, :multiple => true)
-      #    # => <select multiple="multiple">...options...</select>
-      #
-      # Instead of passing the content as an argument, you can also use a block
-      # in which case, you pass your +options+ as the second parameter.
-      #
-      #   <% content_tag :div, :class => "strong" do -%>
@@ -62 +74 @@
-      # <tt><![CDATA[</tt> and end with (and may not contain) the string <tt>]]></tt>.
-      #
+      # ==== Examples
-      #   cdata_section("<hello world>")
-
+
+
+
+
-      def cdata_section(content)
-        "<![CDATA[#{content}]]>"
-      end
-
-the escaped
+an escaped version of
-      #
+      # ==== Examples
-      #   escape_once("1 > 2 &amp; 3")
-
+
+
+
+
-      def escape_once(html)
-        fix_double_escape(html_escape(html.to_s))

trunk/actionpack/lib/action_view/helpers/text_helper.rb

@@ -4 +4 @@
-module ActionView
-  module Helpers #:nodoc:
-M
- that
+m
+, which
-    # your views. These helper methods extend ActionView making them callable 
-
-
-
-
-
-
-
-
+
-    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 
-
-
-
-
-
+
+
+
+
+
+
+
+
+
+
+
+
+
+
-      def concat(string, binding)
-        eval(ActionView::Base.erb_variable, binding) << string
@@ -29 +31 @@
-
-      # If +text+ is longer than +length+, +text+ will be truncated to the length of 
-
-
+
+
+
+
-      #   truncate("Once upon a time in a world far far away", 14)  
-
+
+
+
+
+
+
+
+
+
+
-      def truncate(text, length = 30, truncate_string = "...")
-        if text.nil? then return end
@@ -41 +54 @@
-      # Highlights one or more +phrases+ everywhere in +text+ by inserting it into
-      # a +highlighter+ string. The highlighter can be specialized by passing +highlighter+ 
-
-
+
+
+
+
-      #   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>
-      def highlight(text, phrases, highlighter = '<strong class="highlight">\1</strong>')
-        if text.blank? || phrases.blank?
@@ -58 +79 @@
-
-      # Extracts an excerpt from +text+ that matches the first instance of +phrase+. 
-
-
+the first occurance of 
+ (which defaults to 100)
-      # 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) 
-
+#
-      #
-      #   excerpt('This is an example', 'is', 5) 
-
+
+
+
+
+
+
+
+
+
+
-      def excerpt(text, phrase, radius = 100, excerpt_string = "...")
-        if text.nil? || phrase.nil? then return end
@@ -90 +121 @@
-      # it will just add an 's' to the +singular+ word.
-      #
-
-
-
+
+
+
+
+
+
+
+
+
+
+
+
-      def pluralize(count, singular, plural = nil)
-         "#{count || 0} " + if count == 1 || count == '1'
@@ -106 +146 @@
-
-      # Wraps the +text+ into lines no longer than +line_width+ width. This method
-
-
+
+
+
+
-      #   word_wrap('Once upon a time', 4)
-
+
+
+
+
+
+
+
+
+
+
-      def word_wrap(text, line_width = 80)
-        text.gsub(/\n/, "\n\n").gsub(/(.{1,#{line_width}})(\s+|$)/, "\\1\n").strip
@@ -117 +168 @@
-        require_library_or_gem "redcloth" unless Object.const_defined?(:RedCloth)
-
-
+
+
+
-        # <i>This method is only available if RedCloth[http://whytheluckystiff.net/ruby/redcloth/]
-        # is available</i>.
+        #
+        # ==== Examples
+        #   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>"
-        def textilize(text)
-          if text.blank?
@@ -132 +198 @@
-        # 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[http://www.textism.com/tools/textile].
-        # <i>This method is only available if RedCloth[http://whytheluckystiff.net/ruby/redcloth/]
-        # is available</i>.
+        #
+        # ==== Examples
+        #   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>."
-        def textilize_without_paragraph(text)
-          textiled = textilize(text)
@@ -150 +231 @@
-        # <i>This method is only available if BlueCloth[http://www.deveiate.org/projects/BlueCloth]
-        # is available</i>.
+        #
+        # ==== Examples
+        #   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('![The ROR logo](http://rubyonrails.com/images/rails.png "Ruby on Rails")')
+        #   # => '<p><img src="http://rubyonrails.com/images/rails.png" alt="The ROR logo" title="Ruby on Rails" /></p>'     
-        def markdown(text)
-          text.blank? ? "" : BlueCloth.new(text).to_html
@@ -162 +257 @@
-      # considered as a linebreak and a <tt><br /></tt> 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)
+      #   # => "<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>"
-      def simple_format(text)
-        content_tag 'p', text.to_s.
@@ -169 +278 @@
-      end
-
-urls and e
-html
+URLs and e-
+HTML
-      # +href_options+. Options for +link+ are <tt>:all</tt> (default), 
-
-
-
-
-
-
-
-
-
-
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
-      #     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>."
+      #   
-      def auto_link(text, link = :all, href_options = {}, &block)
-        return '' if text.blank?
@@ -193 +312 @@
-      end
-
-
-
+
+
+
-      #   strip_links('<a href="http://www.rubyonrails.org">Ruby on Rails</a>')
-
+
+
+
+
+
+
+
-      def strip_links(text)
-        text.gsub(/<a\b.*?>(.*?)<\/a>/mi, '\1')
@@ -205 +331 @@
-
-      # Sanitizes the +html+ by converting <form> and <script> tags into regular
-xxx" attributes (
-). It also removes href= and src=
+*" (e.g., onClick) attributes 
+. It also removes <tt>href</tt> and <tt>src</tt>
-      # "javascript:". You can modify what gets sanitized by defining VERBOTEN_TAGS
-      # and VERBOTEN_ATTRS before this Module is loaded.
-      #
+      # ==== Examples
-      #   sanitize('<script> do_nasty_stuff() </script>')
-
+
+
-      #   sanitize('<a href="javascript: sucker();">Click here for $100</a>')
-
+
+
+
+
+
+
+
-      def sanitize(html)
-        # only do this if absolutely necessary
@@ -249 +383 @@
-      # html-scanner tokenizer and so its HTML parsing ability is limited by 
-      # that of html-scanner.
+      #
+      # ==== Examples
+      #   strip_tags("Strip <i>these</i> tags!")
+      #   # => Strip these tags!
+      #
+      #   strip_tags("<b>Bold</b> no more!  <a href='more.html'>See more here</a>...")
+      #   # => Bold no more!  See more here...
+      # 
+      #   strip_tags("<div id='top-bar'>Welcome to my website!</div>")
+      #   # => Welcome to my website!
-      def strip_tags(html)     
-        return html if html.blank?
@@ -270 +414 @@
-      # 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 
-
-
+
+
+
+
+
+
+
+
+
-      #   <% @items.each do |item| %>
-      #     <tr class="<%= cycle("even", "odd") -%>">
@@ -277 +428 @@
-      #     </tr>
-      #   <% end %>
-
-
-
-
-
-
+
+
+
+
+
+
+
-      #   <% @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
+<%= value %>
-      #           </span>
-      #         <% end %>
@@ -313 +466 @@
-      # 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]]
+      #   <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>
-      def reset_cycle(name = "default")
-        cycle = get_cycle(name)