f.semantic_fields_for is now just a wrapper around f.fields_for

Rails 3 will maintain the `:builder` option down through to the nested `fields_for` helper, so we no longer have to do that ourselves.

lib/formtastic/form_builder.rb

@@ -40,10 +40,13 @@ def self.configure(name, value = nil)
     include Formtastic::Helpers::ButtonsHelper
     include Formtastic::Helpers::ErrorsHelper
 
-    # A thin wrapper around `ActionView::Helpers::FormBuilder#fields_for` helper to set 
-    # `:builder => Formtastic::FormBuilder` for nesting forms inside the builder. Can be used in 
-    # the same way, but you'll also have access to the helpers in `Formtastic::FormBuilder` 
-    # (such as {#input}, etc) inside the block.
+    # This is a wrapper around Rails' `ActionView::Helpers::FormBuilder#fields_for`, originally 
+    # provided to ensure that the `:builder` from `semantic_form_for` was passed down into
+    # the nested `fields_for`. Rails 3 no longer requires us to do this, so this method is
+    # provided purely for backwards compatibility and DSL consistency.
+    #
+    # When constructing a `fields_for` form fragment *outside* of `semantic_form_for`, please use
+    # `Formtastic::Helpers::FormHelper#semantic_fields_for`.
     #
     # @see http://api.rubyonrails.org/classes/ActionView/Helpers/FormBuilder.html#method-i-fields_for ActionView::Helpers::FormBuilder#fields_for
     # @see http://api.rubyonrails.org/classes/ActionView/Helpers/FormHelper.html#method-i-fields_for ActionView::Helpers::FormHelper#fields_for
@@ -63,10 +66,9 @@ def self.configure(name, value = nil)
     #       </ol>
     #     </fieldset>
     #   </form>
+    #
+    # @todo is there a way to test the params structure of the Rails helper we wrap to ensure forward compatibility?
     def semantic_fields_for(record_or_name_or_array, *args, &block)
-      opts = args.extract_options!
-      opts[:builder] ||= self.class
-      args.push(opts)
       fields_for(record_or_name_or_array, *args, &block)
     end
 

lib/formtastic/helpers/inputs_helper.rb

@@ -111,7 +111,8 @@ module InputsHelper
       #     end
       #
       # Formtastic provides a helper called `semantic_fields_for`, which wraps around Rails' built-in
-      # `fields_for` helper, allowing you to combine Rails-style nested fields with Formtastic inputs:
+      # `fields_for` helper for backwards compatibility with previous versions of Formtastic, and for
+      # a consistent method naming API. The following examples are functionally equivalent:
       #
       #     <% semantic_form_for @user do |form| %>
       #       <%= f.inputs :name, :email %>
@@ -120,13 +121,23 @@ module InputsHelper
       #         <% profile.inputs do %>
       #           <%= profile.input :biography %>
       #           <%= profile.input :twitter_name %>
-      #           <%= profile.input :shoe_size %>
       #         <% end %>
       #       <% end %>
       #     <% end %>
       #
-      # {#inputs} also provides a DSL similar to `semantic_fields_for` to reduce the lines of code a
-      # little:
+      #     <% semantic_form_for @user do |form| %>
+      #       <%= f.inputs :name, :email %>
+      #
+      #       <% f.fields_for :profile do |profile| %>
+      #         <% profile.inputs do %>
+      #           <%= profile.input :biography %>
+      #           <%= profile.input :twitter_name %>
+      #         <% end %>
+      #       <% end %>
+      #     <% end %>
+      #
+      # {#inputs} also provides a DSL similar to `fields_for` / `semantic_fields_for` to reduce the 
+      # lines of code a little:
       #
       #     <% semantic_form_for @user do |f| %>
       #       <%= f.inputs :name, :email %>
@@ -359,7 +370,7 @@ def inputs_for_nested_attributes(*args, &block) #:nodoc:
         end
 
         fields_for_args = [options.delete(:for), options.delete(:for_options) || {}].flatten
-        semantic_fields_for(*fields_for_args, &fields_for_block)
+        fields_for(*fields_for_args, &fields_for_block)
       end
 
       def field_set_title_from_args(*args) #:nodoc:

spec/builder/custom_builder_spec.rb

@@ -72,11 +72,11 @@ def to_html
 
     end
 
-    describe "semantic_fields_for" do
+    describe "fields_for" do
 
       it "should yield an instance of the parent form builder" do
         semantic_form_for(@new_post) do |builder|
-          builder.semantic_fields_for(:author) do |nested_builder|
+          builder.fields_for(:author) do |nested_builder|
             nested_builder.class.should == MyCustomFormBuilder
           end
         end
@@ -88,11 +88,11 @@ def to_html
 
   describe "when using a builder passed to form options" do
 
-    describe "semantic_fields_for" do
+    describe "fields_for" do
 
       it "should yield an instance of the parent form builder" do
         semantic_form_for(@new_post, :builder => MyCustomFormBuilder) do |builder|
-          builder.semantic_fields_for(:author) do |nested_builder|
+          builder.fields_for(:author) do |nested_builder|
             nested_builder.class.should == MyCustomFormBuilder
           end
         end

spec/builder/semantic_fields_for_spec.rb

@@ -1,7 +1,7 @@
 # encoding: utf-8
 require 'spec_helper'
 
-describe 'Formtastic::FormBuilder#semantic_fields_for' do
+describe 'Formtastic::FormBuilder#fields_for' do
 
   include FormtasticSpecHelper
 
@@ -13,15 +13,15 @@
 
   it 'yields an instance of FormHelper.builder' do
     semantic_form_for(@new_post) do |builder|
-      builder.semantic_fields_for(:author) do |nested_builder|
+      builder.fields_for(:author) do |nested_builder|
         nested_builder.class.should == Formtastic::Helpers::FormHelper.builder
       end
     end
   end
 
   it 'nests the object name' do
     semantic_form_for(@new_post) do |builder|
-      builder.semantic_fields_for(@bob) do |nested_builder|
+      builder.fields_for(@bob) do |nested_builder|
         nested_builder.object_name.should == 'post[author]'
       end
     end
@@ -30,7 +30,7 @@
   it 'should sanitize html id for li tag' do
     @bob.stub!(:column_for_attribute).and_return(mock('column', :type => :string, :limit => 255))
     concat(semantic_form_for(@new_post) do |builder|
-      concat(builder.semantic_fields_for(@bob, :index => 1) do |nested_builder|
+      concat(builder.fields_for(@bob, :index => 1) do |nested_builder|
         concat(nested_builder.inputs(:login))
       end)
     end)
@@ -43,7 +43,7 @@
   it 'should use namespace provided in nested fields' do
     @bob.stub!(:column_for_attribute).and_return(mock('column', :type => :string, :limit => 255))
     concat(semantic_form_for(@new_post, :namespace => 'context2') do |builder|
-      concat(builder.semantic_fields_for(@bob, :index => 1) do |nested_builder|
+      concat(builder.fields_for(@bob, :index => 1) do |nested_builder|
         concat(nested_builder.inputs(:login))
       end)
     end)
@@ -60,7 +60,7 @@
       @fred.stub!(:posts_attributes=)
 
       concat(semantic_form_for(@fred) do |builder|
-        concat(builder.semantic_fields_for(:posts) do |nested_builder|
+        concat(builder.fields_for(:posts) do |nested_builder|
           concat(nested_builder.input(:id, :as => :hidden))
           concat(nested_builder.input(:title))
         end)

spec/i18n_spec.rb

@@ -133,7 +133,7 @@
     it 'should be able to translate nested objects with nested translations' do
       with_config :i18n_lookups_by_default, true do
         concat(semantic_form_for(:project, :url => 'http://test.host') do |builder|
-          builder.semantic_fields_for(:task) do |f|
+          builder.fields_for(:task) do |f|
             concat(f.input(:name))
           end
         end)
@@ -144,7 +144,7 @@
     it 'should be able to translate nested objects with top level translations' do
       with_config :i18n_lookups_by_default, true do
         concat(semantic_form_for(:order, :url => 'http://test.host') do |builder|
-          builder.semantic_fields_for(:line_item) do |f|
+          builder.fields_for(:line_item) do |f|
             concat(f.input(:name))
           end
         end)