actionpack 2.2.3 → 2.3.2

data/lib/action_view/helpers/atom_feed_helper.rb

@@ -30,7 +30,7 @@ module ActionView
       #   app/views/posts/index.atom.builder:
       #     atom_feed do |feed|
       #       feed.title("My great blog!")
-      #       feed.updated((@posts.first.created_at))
+      #       feed.updated(@posts.first.created_at)
       #
       #       for post in @posts
       #         feed.entry(post) do |entry|

data/lib/action_view/helpers/benchmark_helper.rb

@@ -18,16 +18,37 @@ module ActionView
       # That would add something like "Process data files (345.2ms)" to the log,
       # which you can then use to compare timings when optimizing your code.
       #
-      # You may give an optional logger level as the second argument
+      # You may give an optional logger level as the :level option.
       # (:debug, :info, :warn, :error); the default value is :info.
-      def benchmark(message = "Benchmarking", level = :info)
+      #
+      #  <% benchmark "Low-level files", :level => :debug do %>
+      #    <%= lowlevel_files_operation %>
+      #  <% end %>
+      #
+      # Finally, you can pass true as the third argument to silence all log activity 
+      # inside the block. This is great for boiling down a noisy block to just a single statement:
+      #
+      #  <% benchmark "Process data files", :level => :info, :silence => true do %>
+      #    <%= expensive_and_chatty_files_operation %>
+      #  <% end %>
+      def benchmark(message = "Benchmarking", options = {})
         if controller.logger
-          seconds = Benchmark.realtime { yield }
-          controller.logger.send(level, "#{message} (#{'%.1f' % (seconds * 1000)}ms)")
+          if options.is_a?(Symbol)
+            ActiveSupport::Deprecation.warn("use benchmark('#{message}', :level => :#{options}) instead", caller)
+            options = { :level => options, :silence => false }
+          else
+            options.assert_valid_keys(:level, :silence)
+            options[:level] ||= :info
+          end
+          
+          result = nil
+          ms = Benchmark.ms { result = options[:silence] ? controller.logger.silence { yield } : yield }
+          controller.logger.send(options[:level], '%s (%.1fms)' % [ message, ms ])
+          result
         else
           yield
         end
       end
     end
   end
-end
+end

data/lib/action_view/helpers/date_helper.rb

@@ -111,7 +111,7 @@ module ActionView
       #
       # ==== Options
       # * <tt>:use_month_numbers</tt> - Set to true if you want to use month numbers rather than month names (e.g.
-      #    "2" instead of "February").
+      #   "2" instead of "February").
       # * <tt>:use_short_month</tt>   - Set to true if you want to use the abbreviated month name instead of the full
       #   name (e.g. "Feb" instead of "February").
       # * <tt>:add_month_number</tt>  - Set to true if you want to show both, the month's number and name (e.g.
@@ -136,6 +136,10 @@ module ActionView
       #   dates.
       # * <tt>:default</tt>           - Set a default date if the affected date isn't set or is nil.
       # * <tt>:disabled</tt>          - Set to true if you want show the select fields as disabled.
+      # * <tt>:prompt</tt>            - Set to true (for a generic prompt), a prompt string or a hash of prompt strings
+      #   for <tt>:year</tt>, <tt>:month</tt>, <tt>:day</tt>, <tt>:hour</tt>, <tt>:minute</tt> and <tt>:second</tt>.
+      #   Setting this option prepends a select option with a generic prompt  (Day, Month, Year, Hour, Minute, Seconds)
+      #   or the given prompt string.
       #
       # If anything is passed in the +html_options+ hash it will be applied to every select tag in the set.
       #
@@ -171,6 +175,9 @@ module ActionView
       #   # that will have a default day of 20.
       #   date_select("credit_card", "bill_due", :default => { :day => 20 })
       #
+      #   # Generates a date select with custom prompts
+      #   date_select("post", "written_on", :prompt => { :day => 'Select day', :month => 'Select month', :year => 'Select year' })
+      #
       # The selects are prepared for multi-parameter assignment to an Active Record object.
       #
       # Note: If the day is not included as an option but the month is, the day will be set to the 1st to ensure that
@@ -210,6 +217,11 @@ module ActionView
       #   # You can set the :minute_step to 15 which will give you: 00, 15, 30 and 45.
       #   time_select 'game', 'game_time', {:minute_step => 15}
       #
+      #   # Creates a time select tag with a custom prompt. Use :prompt => true for generic prompts.
+      #   time_select("post", "written_on", :prompt => {:hour => 'Choose hour', :minute => 'Choose minute', :second => 'Choose seconds'})
+      #   time_select("post", "written_on", :prompt => {:hour => true}) # generic prompt for hours
+      #   time_select("post", "written_on", :prompt => true) # generic prompts for all
+      #
       # The selects are prepared for multi-parameter assignment to an Active Record object.
       #
       # Note: If the day is not included as an option but the month is, the day will be set to the 1st to ensure that
@@ -241,6 +253,11 @@ module ActionView
       #   # as the written_on attribute.
       #   datetime_select("post", "written_on", :discard_type => true)
       #
+      #   # Generates a datetime select with a custom prompt. Use :prompt=>true for generic prompts.
+      #   datetime_select("post", "written_on", :prompt => {:day => 'Choose day', :month => 'Choose month', :year => 'Choose year'})
+      #   datetime_select("post", "written_on", :prompt => {:hour => true}) # generic prompt for hours
+      #   datetime_select("post", "written_on", :prompt => true) # generic prompts for all
+      #
       # The selects are prepared for multi-parameter assignment to an Active Record object.
       def datetime_select(object_name, method, options = {}, html_options = {})
         InstanceTag.new(object_name, method, self, options.delete(:object)).to_datetime_select_tag(options, html_options)
@@ -285,6 +302,11 @@ module ActionView
       #   # prefixed with 'payday' rather than 'date'
       #   select_datetime(my_date_time, :prefix => 'payday')
       #
+      #   # Generates a datetime select with a custom prompt. Use :prompt=>true for generic prompts.
+      #   select_datetime(my_date_time, :prompt => {:day => 'Choose day', :month => 'Choose month', :year => 'Choose year'})
+      #   select_datetime(my_date_time, :prompt => {:hour => true}) # generic prompt for hours
+      #   select_datetime(my_date_time, :prompt => true) # generic prompts for all
+      #
       def select_datetime(datetime = Time.current, options = {}, html_options = {})
         DateTimeSelector.new(datetime, options, html_options).select_datetime
       end
@@ -321,6 +343,11 @@ module ActionView
       #   # prefixed with 'payday' rather than 'date'
       #   select_date(my_date, :prefix => 'payday')
       #
+      #   # Generates a date select with a custom prompt. Use :prompt=>true for generic prompts.
+      #   select_date(my_date, :prompt => {:day => 'Choose day', :month => 'Choose month', :year => 'Choose year'})
+      #   select_date(my_date, :prompt => {:hour => true}) # generic prompt for hours
+      #   select_date(my_date, :prompt => true) # generic prompts for all
+      #
       def select_date(date = Date.current, options = {}, html_options = {})
         DateTimeSelector.new(date, options, html_options).select_date
       end
@@ -352,6 +379,11 @@ module ActionView
       #   # separated by ':' and includes an input for seconds
       #   select_time(my_time, :time_separator => ':', :include_seconds => true)
       #
+      #   # Generates a time select with a custom prompt. Use :prompt=>true for generic prompts.
+      #   select_time(my_time, :prompt => {:day => 'Choose day', :month => 'Choose month', :year => 'Choose year'})
+      #   select_time(my_time, :prompt => {:hour => true}) # generic prompt for hours
+      #   select_time(my_time, :prompt => true) # generic prompts for all
+      #
       def select_time(datetime = Time.current, options = {}, html_options = {})
         DateTimeSelector.new(datetime, options, html_options).select_time
       end
@@ -373,6 +405,10 @@ module ActionView
       #   # that is named 'interval' rather than 'second'
       #   select_second(my_time, :field_name => 'interval')
       #
+      #   # Generates a select field for seconds with a custom prompt.  Use :prompt=>true for a
+      #   # generic prompt.
+      #   select_minute(14, :prompt => 'Choose seconds')
+      #
       def select_second(datetime, options = {}, html_options = {})
         DateTimeSelector.new(datetime, options, html_options).select_second
       end
@@ -395,6 +431,10 @@ module ActionView
       #   # that is named 'stride' rather than 'second'
       #   select_minute(my_time, :field_name => 'stride')
       #
+      #   # Generates a select field for minutes with a custom prompt.  Use :prompt=>true for a
+      #   # generic prompt.
+      #   select_minute(14, :prompt => 'Choose minutes')
+      #
       def select_minute(datetime, options = {}, html_options = {})
         DateTimeSelector.new(datetime, options, html_options).select_minute
       end
@@ -416,6 +456,10 @@ module ActionView
       #   # that is named 'stride' rather than 'second'
       #   select_hour(my_time, :field_name => 'stride')
       #
+      #   # Generates a select field for hours with a custom prompt.  Use :prompt => true for a
+      #   # generic prompt.
+      #   select_hour(13, :prompt =>'Choose hour')
+      #
       def select_hour(datetime, options = {}, html_options = {})
         DateTimeSelector.new(datetime, options, html_options).select_hour
       end
@@ -437,6 +481,10 @@ module ActionView
       #   # that is named 'due' rather than 'day'
       #   select_day(my_time, :field_name => 'due')
       #
+      #   # Generates a select field for days with a custom prompt.  Use :prompt => true for a
+      #   # generic prompt.
+      #   select_day(5, :prompt => 'Choose day')
+      #
       def select_day(date, options = {}, html_options = {})
         DateTimeSelector.new(date, options, html_options).select_day
       end
@@ -475,6 +523,10 @@ module ActionView
       #   # will use keys like "Januar", "Marts."
       #   select_month(Date.today, :use_month_names => %w(Januar Februar Marts ...))
       #
+      #   # Generates a select field for months with a custom prompt.  Use :prompt => true for a
+      #   # generic prompt.
+      #   select_month(14, :prompt => 'Choose month')
+      #
       def select_month(date, options = {}, html_options = {})
         DateTimeSelector.new(date, options, html_options).select_month
       end
@@ -502,6 +554,10 @@ module ActionView
       #   # has ascending year values
       #   select_year(2006, :start_year => 2000, :end_year => 2010)
       #
+      #   # Generates a select field for years with a custom prompt.  Use :prompt => true for a
+      #   # generic prompt.
+      #   select_year(14, :prompt => 'Choose year')
+      #
       def select_year(date, options = {}, html_options = {})
         DateTimeSelector.new(date, options, html_options).select_year
       end
@@ -764,11 +820,30 @@ module ActionView
 
           select_html = "\n"
           select_html << content_tag(:option, '', :value => '') + "\n" if @options[:include_blank]
+          select_html << prompt_option_tag(type, @options[:prompt]) + "\n" if @options[:prompt]
           select_html << select_options_as_html.to_s
 
           content_tag(:select, select_html, select_options) + "\n"
         end
 
+        # Builds a prompt option tag with supplied options or from default options
+        #  prompt_option_tag(:month, :prompt => 'Select month')
+        #  => "<option value="">Select month</option>"
+        def prompt_option_tag(type, options)
+          default_options = {:year => false, :month => false, :day => false, :hour => false, :minute => false, :second => false}
+
+          case options
+          when Hash
+            prompt = default_options.merge(options)[type.to_sym]
+          when String
+            prompt = options
+          else
+            prompt = I18n.translate(('datetime.prompts.' + type.to_s).to_sym, :locale => @options[:locale])
+          end
+
+          prompt ? content_tag(:option, prompt, :value => '') : ''
+        end
+
         # Builds hidden input tag for date part and value
         #  build_hidden(:year, 2008)
         #  => "<input id="post_written_on_1i" name="post[written_on(1i)]" type="hidden" value="2008" />"
@@ -785,7 +860,7 @@ module ActionView
         #  => post[written_on(1i)]
         def input_name_from_type(type)
           prefix = @options[:prefix] || ActionView::Helpers::DateTimeSelector::DEFAULT_PREFIX
-          prefix += "[#{@options[:index]}]" if @options[:index]
+          prefix += "[#{@options[:index]}]" if @options.has_key?(:index)
 
           field_name = @options[:field_name] || type
           if @options[:include_position]
@@ -848,7 +923,7 @@ module ActionView
           options[:field_name]           = @method_name
           options[:include_position]     = true
           options[:prefix]             ||= @object_name
-          options[:index]              ||= @auto_index
+          options[:index]                = @auto_index if @auto_index && !options.has_key?(:index)
           options[:datetime_separator] ||= ' &mdash; '
           options[:time_separator]     ||= ' : '
 
@@ -856,7 +931,7 @@ module ActionView
         end
 
         def default_datetime(options)
-          return if options[:include_blank]
+          return if options[:include_blank] || options[:prompt]
 
           case options[:default]
             when nil
@@ -886,15 +961,15 @@ module ActionView
 
     class FormBuilder
       def date_select(method, options = {}, html_options = {})
-        @template.date_select(@object_name, method, options.merge(:object => @object), html_options)
+        @template.date_select(@object_name, method, objectify_options(options), html_options)
       end
 
       def time_select(method, options = {}, html_options = {})
-        @template.time_select(@object_name, method, options.merge(:object => @object), html_options)
+        @template.time_select(@object_name, method, objectify_options(options), html_options)
       end
 
       def datetime_select(method, options = {}, html_options = {})
-        @template.datetime_select(@object_name, method, options.merge(:object => @object), html_options)
+        @template.datetime_select(@object_name, method, objectify_options(options), html_options)
       end
     end
   end

data/lib/action_view/helpers/form_helper.rb

@@ -5,17 +5,24 @@ require 'action_view/helpers/form_tag_helper'
 
 module ActionView
   module Helpers
-    # Form helpers are designed to make working with models much easier compared to using just standard HTML
-    # elements by providing a set of methods for creating forms based on your models. This helper generates the HTML
-    # for forms, providing a method for each sort of input (e.g., text, password, select, and so on). When the form
-    # is submitted (i.e., when the user hits the submit button or <tt>form.submit</tt> is called via JavaScript), the form inputs will be bundled into the <tt>params</tt> object and passed back to the controller.
+    # Form helpers are designed to make working with models much easier
+    # compared to using just standard HTML elements by providing a set of
+    # methods for creating forms based on your models. This helper generates
+    # the HTML for forms, providing a method for each sort of input
+    # (e.g., text, password, select, and so on). When the form is submitted
+    # (i.e., when the user hits the submit button or <tt>form.submit</tt> is
+    # called via JavaScript), the form inputs will be bundled into the
+    # <tt>params</tt> object and passed back to the controller.
     #
-    # There are two types of form helpers: those that specifically work with model attributes and those that don't.
-    # This helper deals with those that work with model attributes; to see an example of form helpers that don't work
-    # with model attributes, check the ActionView::Helpers::FormTagHelper documentation.
+    # There are two types of form helpers: those that specifically work with
+    # model attributes and those that don't. This helper deals with those that
+    # work with model attributes; to see an example of form helpers that don't
+    # work with model attributes, check the ActionView::Helpers::FormTagHelper
+    # documentation.
     #
-    # The core method of this helper, form_for, gives you the ability to create a form for a model instance;
-    # for example, let's say that you have a model <tt>Person</tt> and want to create a new instance of it:
+    # The core method of this helper, form_for, gives you the ability to create
+    # a form for a model instance; for example, let's say that you have a model
+    # <tt>Person</tt> and want to create a new instance of it:
     #
     #     # Note: a @person variable will have been created in the controller.
     #     # For example: @person = Person.new
@@ -40,17 +47,22 @@ module ActionView
     #       <%= submit_tag 'Create' %>
     #     <% end %>
     #
-    # This example will render the <tt>people/_form</tt> partial, setting a local variable called <tt>form</tt> which references the yielded FormBuilder.
-    #
-    # The <tt>params</tt> object created when this form is submitted would look like:
+    # This example will render the <tt>people/_form</tt> partial, setting a
+    # local variable called <tt>form</tt> which references the yielded
+    # FormBuilder. The <tt>params</tt> object created when this form is
+    # submitted would look like:
     #
     #     {"action"=>"create", "controller"=>"persons", "person"=>{"first_name"=>"William", "last_name"=>"Smith"}}
     #
-    # The params hash has a nested <tt>person</tt> value, which can therefore be accessed with <tt>params[:person]</tt> in the controller.
-    # If were editing/updating an instance (e.g., <tt>Person.find(1)</tt> rather than <tt>Person.new</tt> in the controller), the objects
-    # attribute values are filled into the form (e.g., the <tt>person_first_name</tt> field would have that person's first name in it).
+    # The params hash has a nested <tt>person</tt> value, which can therefore
+    # be accessed with <tt>params[:person]</tt> in the controller. If were
+    # editing/updating an instance (e.g., <tt>Person.find(1)</tt> rather than
+    # <tt>Person.new</tt> in the controller), the objects attribute values are
+    # filled into the form (e.g., the <tt>person_first_name</tt> field would
+    # have that person's first name in it).
     #
-    # If the object name contains square brackets the id for the object will be inserted. For example:
+    # If the object name contains square brackets the id for the object will be
+    # inserted. For example:
     #
     #   <%= text_field "person[]", "name" %>
     #
@@ -58,8 +70,10 @@ module ActionView
     #
     #   <input type="text" id="person_<%= @person.id %>_name" name="person[<%= @person.id %>][name]" value="<%= @person.name %>" />
     #
-    # If the helper is being used to generate a repetitive sequence of similar form elements, for example in a partial
-    # used by <tt>render_collection_of_partials</tt>, the <tt>index</tt> option may come in handy. Example:
+    # If the helper is being used to generate a repetitive sequence of similar
+    # form elements, for example in a partial used by
+    # <tt>render_collection_of_partials</tt>, the <tt>index</tt> option may
+    # come in handy. Example:
     #
     #   <%= text_field "person", "name", "index" => 1 %>
     #
@@ -67,14 +81,17 @@ module ActionView
     #
     #   <input type="text" id="person_1_name" name="person[1][name]" value="<%= @person.name %>" />
     #
-    # An <tt>index</tt> option may also be passed to <tt>form_for</tt> and <tt>fields_for</tt>.  This automatically applies
-    # the <tt>index</tt> to all the nested fields.
+    # An <tt>index</tt> option may also be passed to <tt>form_for</tt> and
+    # <tt>fields_for</tt>.  This automatically applies the <tt>index</tt> to
+    # all the nested fields.
     #
-    # There are also methods for helping to build form tags in link:classes/ActionView/Helpers/FormOptionsHelper.html,
-    # link:classes/ActionView/Helpers/DateHelper.html, and link:classes/ActionView/Helpers/ActiveRecordHelper.html
+    # There are also methods for helping to build form tags in
+    # link:classes/ActionView/Helpers/FormOptionsHelper.html,
+    # link:classes/ActionView/Helpers/DateHelper.html, and
+    # link:classes/ActionView/Helpers/ActiveRecordHelper.html
     module FormHelper
-      # Creates a form and a scope around a specific model object that is used as
-      # a base for questioning about values for the fields.
+      # Creates a form and a scope around a specific model object that is used
+      # as a base for questioning about values for the fields.
       #
       # Rails provides succinct resource-oriented form generation with +form_for+
       # like this:
@@ -86,13 +103,15 @@ module ActionView
       #     <%= f.text_field :author %><br />
       #   <% end %>
       #
-      # There, +form_for+ is able to generate the rest of RESTful form parameters
-      # based on introspection on the record, but to understand what it does we
-      # need to dig first into the alternative generic usage it is based upon.
+      # There, +form_for+ is able to generate the rest of RESTful form
+      # parameters based on introspection on the record, but to understand what
+      # it does we need to dig first into the alternative generic usage it is
+      # based upon.
       #
       # === Generic form_for
       #
-      # The generic way to call +form_for+ yields a form builder around a model:
+      # The generic way to call +form_for+ yields a form builder around a
+      # model:
       #
       #   <% form_for :person, :url => { :action => "update" } do |f| %>
       #     <%= f.error_messages %>
@@ -103,8 +122,8 @@ module ActionView
       #   <% end %>
       #
       # There, the first argument is a symbol or string with the name of the
-      # object the form is about, and also the name of the instance variable the
-      # object is stored in.
+      # object the form is about, and also the name of the instance variable
+      # the object is stored in.
       #
       # The form builder acts as a regular form helper that somehow carries the
       # model. Thus, the idea is that
@@ -137,17 +156,18 @@ module ActionView
       # In any of its variants, the rightmost argument to +form_for+ is an
       # optional hash of options:
       #
-      # * <tt>:url</tt> - The URL the form is submitted to. It takes the same fields
-      #   you pass to +url_for+ or +link_to+. In particular you may pass here a
-      #   named route directly as well. Defaults to the current action.
+      # * <tt>:url</tt> - The URL the form is submitted to. It takes the same
+      #   fields you pass to +url_for+ or +link_to+. In particular you may pass
+      #   here a named route directly as well. Defaults to the current action.
       # * <tt>:html</tt> - Optional HTML attributes for the form tag.
       #
-      # Worth noting is that the +form_for+ tag is called in a ERb evaluation block,
-      # not an ERb output block. So that's <tt><% %></tt>, not <tt><%= %></tt>.
+      # Worth noting is that the +form_for+ tag is called in a ERb evaluation
+      # block, not an ERb output block. So that's <tt><% %></tt>, not
+      # <tt><%= %></tt>.
       #
       # Also note that +form_for+ doesn't create an exclusive scope. It's still
-      # possible to use both the stand-alone FormHelper methods and methods from
-      # FormTagHelper. For example:
+      # possible to use both the stand-alone FormHelper methods and methods
+      # from FormTagHelper. For example:
       #
       #   <% form_for :person, @person, :url => { :action => "update" } do |f| %>
       #     First name: <%= f.text_field :first_name %>
@@ -156,16 +176,16 @@ module ActionView
       #     Admin?    : <%= check_box_tag "person[admin]", @person.company.admin? %>
       #   <% end %>
       #
-      # This also works for the methods in FormOptionHelper and DateHelper that are
-      # designed to work with an object as base, like FormOptionHelper#collection_select
-      # and DateHelper#datetime_select.
+      # This also works for the methods in FormOptionHelper and DateHelper that
+      # are designed to work with an object as base, like
+      # FormOptionHelper#collection_select and DateHelper#datetime_select.
       #
       # === Resource-oriented style
       #
-      # As we said above, in addition to manually configuring the +form_for+ call,
-      # you can rely on automated resource identification, which will use the conventions
-      # and named routes of that approach. This is the preferred way to use +form_for+
-      # nowadays.
+      # As we said above, in addition to manually configuring the +form_for+
+      # call, you can rely on automated resource identification, which will use
+      # the conventions and named routes of that approach. This is the
+      # preferred way to use +form_for+ nowadays.
       #
       # For example, if <tt>@post</tt> is an existing record you want to edit
       #
@@ -205,8 +225,10 @@ module ActionView
       #
       # === Customized form builders
       #
-      # You can also build forms using a customized FormBuilder class. Subclass FormBuilder and override or define some more helpers,
-      # then use your custom builder. For example, let's say you made a helper to automatically add labels to form inputs.
+      # You can also build forms using a customized FormBuilder class. Subclass
+      # FormBuilder and override or define some more helpers, then use your
+      # custom builder. For example, let's say you made a helper to
+      # automatically add labels to form inputs.
       #
       #   <% form_for :person, @person, :url => { :action => "update" }, :builder => LabellingFormBuilder do |f| %>
       #     <%= f.text_field :first_name %>
@@ -219,16 +241,23 @@ module ActionView
       #
       #   <%= render :partial => f %>
       #
-      # The rendered template is <tt>people/_labelling_form</tt> and the local variable referencing the form builder is called <tt>labelling_form</tt>.
+      # The rendered template is <tt>people/_labelling_form</tt> and the local
+      # variable referencing the form builder is called
+      # <tt>labelling_form</tt>.
+      #
+      # The custom FormBuilder class is automatically merged with the options
+      # of a nested fields_for call, unless it's explicitely set.
       #
-      # In many cases you will want to wrap the above in another helper, so you could do something like the following:
+      # In many cases you will want to wrap the above in another helper, so you
+      # could do something like the following:
       #
       #   def labelled_form_for(record_or_name_or_array, *args, &proc)
       #     options = args.extract_options!
       #     form_for(record_or_name_or_array, *(args << options.merge(:builder => LabellingFormBuilder)), &proc)
       #   end
       #
-      # If you don't need to attach a form to a model instance, then check out FormTagHelper#form_tag.
+      # If you don't need to attach a form to a model instance, then check out
+      # FormTagHelper#form_tag.
       def form_for(record_or_name_or_array, *args, &proc)
         raise ArgumentError, "Missing block" unless block_given?
 
@@ -269,10 +298,12 @@ module ActionView
         options[:url] ||= polymorphic_path(object_or_array)
       end
 
-      # Creates a scope around a specific model object like form_for, but doesn't create the form tags themselves. This makes
-      # fields_for suitable for specifying additional model objects in the same form:
+      # Creates a scope around a specific model object like form_for, but
+      # doesn't create the form tags themselves. This makes fields_for suitable
+      # for specifying additional model objects in the same form.
+      #
+      # === Generic Examples
       #
-      # ==== Examples
       #   <% form_for @person, :url => { :action => "update" } do |person_form| %>
       #     First name: <%= person_form.text_field :first_name %>
       #     Last name : <%= person_form.text_field :last_name %>
@@ -282,20 +313,166 @@ module ActionView
       #     <% end %>
       #   <% end %>
       #
-      # ...or if you have an object that needs to be represented as a different parameter, like a Client that acts as a Person:
+      # ...or if you have an object that needs to be represented as a different
+      # parameter, like a Client that acts as a Person:
       #
       #   <% fields_for :person, @client do |permission_fields| %>
       #     Admin?: <%= permission_fields.check_box :admin %>
       #   <% end %>
       #
-      # ...or if you don't have an object, just a name of the parameter
+      # ...or if you don't have an object, just a name of the parameter:
       #
       #   <% fields_for :person do |permission_fields| %>
       #     Admin?: <%= permission_fields.check_box :admin %>
       #   <% end %>
       #
-      # Note: This also works for the methods in FormOptionHelper and DateHelper that are designed to work with an object as base,
-      # like FormOptionHelper#collection_select and DateHelper#datetime_select.
+      # Note: This also works for the methods in FormOptionHelper and
+      # DateHelper that are designed to work with an object as base, like
+      # FormOptionHelper#collection_select and DateHelper#datetime_select.
+      #
+      # === Nested Attributes Examples
+      #
+      # When the object belonging to the current scope has a nested attribute
+      # writer for a certain attribute, fields_for will yield a new scope
+      # for that attribute. This allows you to create forms that set or change
+      # the attributes of a parent object and its associations in one go.
+      #
+      # Nested attribute writers are normal setter methods named after an
+      # association. The most common way of defining these writers is either
+      # with +accepts_nested_attributes_for+ in a model definition or by
+      # defining a method with the proper name. For example: the attribute
+      # writer for the association <tt>:address</tt> is called
+      # <tt>address_attributes=</tt>.
+      #
+      # Whether a one-to-one or one-to-many style form builder will be yielded
+      # depends on whether the normal reader method returns a _single_ object
+      # or an _array_ of objects.
+      #
+      # ==== One-to-one
+      #
+      # Consider a Person class which returns a _single_ Address from the
+      # <tt>address</tt> reader method and responds to the
+      # <tt>address_attributes=</tt> writer method:
+      #
+      #   class Person
+      #     def address
+      #       @address
+      #     end
+      #
+      #     def address_attributes=(attributes)
+      #       # Process the attributes hash
+      #     end
+      #   end
+      #
+      # This model can now be used with a nested fields_for, like so:
+      #
+      #   <% form_for @person, :url => { :action => "update" } do |person_form| %>
+      #     ...
+      #     <% person_form.fields_for :address do |address_fields| %>
+      #       Street  : <%= address_fields.text_field :street %>
+      #       Zip code: <%= address_fields.text_field :zip_code %>
+      #     <% end %>
+      #   <% end %>
+      #
+      # When address is already an association on a Person you can use
+      # +accepts_nested_attributes_for+ to define the writer method for you:
+      #
+      #   class Person < ActiveRecord::Base
+      #     has_one :address
+      #     accepts_nested_attributes_for :address
+      #   end
+      #
+      # If you want to destroy the associated model through the form, you have
+      # to enable it first using the <tt>:allow_destroy</tt> option for
+      # +accepts_nested_attributes_for+:
+      #
+      #   class Person < ActiveRecord::Base
+      #     has_one :address
+      #     accepts_nested_attributes_for :address, :allow_destroy => true
+      #   end
+      #
+      # Now, when you use a form element with the <tt>_delete</tt> parameter,
+      # with a value that evaluates to +true+, you will destroy the associated
+      # model (eg. 1, '1', true, or 'true'):
+      #
+      #   <% form_for @person, :url => { :action => "update" } do |person_form| %>
+      #     ...
+      #     <% person_form.fields_for :address do |address_fields| %>
+      #       ...
+      #       Delete: <%= address_fields.check_box :_delete %>
+      #     <% end %>
+      #   <% end %>
+      #
+      # ==== One-to-many
+      #
+      # Consider a Person class which returns an _array_ of Project instances
+      # from the <tt>projects</tt> reader method and responds to the
+      # <tt>projects_attributes=</tt> writer method:
+      #
+      #   class Person
+      #     def projects
+      #       [@project1, @project2]
+      #     end
+      #
+      #     def projects_attributes=(attributes)
+      #       # Process the attributes hash
+      #     end
+      #   end
+      #
+      # This model can now be used with a nested fields_for. The block given to
+      # the nested fields_for call will be repeated for each instance in the
+      # collection:
+      #
+      #   <% form_for @person, :url => { :action => "update" } do |person_form| %>
+      #     ...
+      #     <% person_form.fields_for :projects do |project_fields| %>
+      #       <% if project_fields.object.active? %>
+      #         Name: <%= project_fields.text_field :name %>
+      #       <% end %>
+      #     <% end %>
+      #   <% end %>
+      #
+      # It's also possible to specify the instance to be used:
+      #
+      #   <% form_for @person, :url => { :action => "update" } do |person_form| %>
+      #     ...
+      #     <% @person.projects.each do |project| %>
+      #       <% if project.active? %>
+      #         <% person_form.fields_for :projects, project do |project_fields| %>
+      #           Name: <%= project_fields.text_field :name %>
+      #         <% end %>
+      #       <% end %>
+      #     <% end %>
+      #   <% end %>
+      #
+      # When projects is already an association on Person you can use
+      # +accepts_nested_attributes_for+ to define the writer method for you:
+      #
+      #   class Person < ActiveRecord::Base
+      #     has_many :projects
+      #     accepts_nested_attributes_for :projects
+      #   end
+      #
+      # If you want to destroy any of the associated models through the
+      # form, you have to enable it first using the <tt>:allow_destroy</tt>
+      # option for +accepts_nested_attributes_for+:
+      #
+      #   class Person < ActiveRecord::Base
+      #     has_many :projects
+      #     accepts_nested_attributes_for :projects, :allow_destroy => true
+      #   end
+      #
+      # This will allow you to specify which models to destroy in the
+      # attributes hash by adding a form element for the <tt>_delete</tt>
+      # parameter with a value that evaluates to +true+
+      # (eg. 1, '1', true, or 'true'):
+      #
+      #   <% form_for @person, :url => { :action => "update" } do |person_form| %>
+      #     ...
+      #     <% person_form.fields_for :projects do |project_fields| %>
+      #       Delete: <%= project_fields.check_box :_delete %>
+      #     <% end %>
+      #   <% end %>
       def fields_for(record_or_name_or_array, *args, &block)
         raise ArgumentError, "Missing block" unless block_given?
         options = args.extract_options!
@@ -498,8 +675,10 @@ module ActionView
 
       # Returns a radio button tag for accessing a specified attribute (identified by +method+) on an object
       # assigned to the template (identified by +object+). If the current value of +method+ is +tag_value+ the
-      # radio button will be checked. Additional options on the input tag can be passed as a
-      # hash with +options+.
+      # radio button will be checked.
+      #
+      # To force the radio button to be checked pass <tt>:checked => true</tt> in the
+      # +options+ hash. You may pass HTML options there as well.
       #
       # ==== Examples
       #   # Let's say that @post.category returns "rails":
@@ -605,7 +784,9 @@ module ActionView
         end
         options["checked"] = "checked" if checked
         add_default_name_and_id(options)
-        tag("input", options) << tag("input", "name" => options["name"], "type" => "hidden", "value" => options['disabled'] && checked ? checked_value : unchecked_value)
+        hidden = tag("input", "name" => options["name"], "type" => "hidden", "value" => options['disabled'] && checked ? checked_value : unchecked_value)
+        checkbox = tag("input", options)
+        hidden + checkbox
       end
 
       def to_boolean_select_tag(options = {})
@@ -737,9 +918,13 @@ module ActionView
 
       (field_helpers - %w(label check_box radio_button fields_for)).each do |selector|
         src = <<-end_src
-          def #{selector}(method, options = {})
-            @template.send(#{selector.inspect}, @object_name, method, objectify_options(options))
-          end
+          def #{selector}(method, options = {})  # def text_field(method, options = {})
+            @template.send(                      #   @template.send(
+              #{selector.inspect},               #     "text_field",
+              @object_name,                      #     @object_name,
+              method,                            #     method,
+              objectify_options(options))        #     objectify_options(options))
+          end                                    # end
         end_src
         class_eval src, __FILE__, __LINE__
       end
@@ -754,9 +939,18 @@ module ActionView
           index = ""
         end
 
+        if options[:builder]
+          args << {} unless args.last.is_a?(Hash)
+          args.last[:builder] ||= options[:builder]
+        end
+
         case record_or_name_or_array
         when String, Symbol
-          name = "#{object_name}#{index}[#{record_or_name_or_array}]"
+          if nested_attributes_association?(record_or_name_or_array)
+            return fields_for_with_nested_attributes(record_or_name_or_array, args, block)
+          else
+            name = "#{object_name}#{index}[#{record_or_name_or_array}]"
+          end
         when Array
           object = record_or_name_or_array.last
           name = "#{object_name}#{index}[#{ActionController::RecordIdentifier.singular_class_name(object)}]"
@@ -798,6 +992,43 @@ module ActionView
         def objectify_options(options)
           @default_options.merge(options.merge(:object => @object))
         end
+
+        def nested_attributes_association?(association_name)
+          @object.respond_to?("#{association_name}_attributes=")
+        end
+
+        def fields_for_with_nested_attributes(association_name, args, block)
+          name = "#{object_name}[#{association_name}_attributes]"
+          association = @object.send(association_name)
+          explicit_object = args.first if args.first.respond_to?(:new_record?)
+
+          if association.is_a?(Array)
+            children = explicit_object ? [explicit_object] : association
+            explicit_child_index = args.last[:child_index] if args.last.is_a?(Hash)
+
+            children.map do |child|
+              fields_for_nested_model("#{name}[#{explicit_child_index || nested_child_index}]", child, args, block)
+            end.join
+          else
+            fields_for_nested_model(name, explicit_object || association, args, block)
+          end
+        end
+
+        def fields_for_nested_model(name, object, args, block)
+          if object.new_record?
+            @template.fields_for(name, object, *args, &block)
+          else
+            @template.fields_for(name, object, *args) do |builder|
+              @template.concat builder.hidden_field(:id)
+              block.call(builder)
+            end
+          end
+        end
+
+        def nested_child_index
+          @nested_child_index ||= -1
+          @nested_child_index += 1
+        end
     end
   end
 
@@ -805,4 +1036,4 @@ module ActionView
     cattr_accessor :default_form_builder
     self.default_form_builder = ::ActionView::Helpers::FormBuilder
   end
-end
+end