Merge pull request rails#51704 from notapatch/pr-prefer-form-with

[ci skip]Docs highlight form_with over form_for

Author: skipkayhil

actionpack/lib/action_controller/form_builder.rb

@@ -22,10 +22,10 @@ module ActionController
   #       default_form_builder AdminFormBuilder
   #     end
   #
-  # Then in the view any form using `form_for` will be an instance of the
-  # specified form builder:
+  # Then in the view any form using `form_with` or `form_for` will be an
+  # instance of the specified form builder:
   #
-  #     <%= form_for(@instance) do |builder| %>
+  #     <%= form_with(model: @instance) do |builder| %>
   #       <%= builder.special_field(:name) %>
   #     <% end %>
   module FormBuilder

actionpack/lib/action_dispatch/routing/mapper.rb

@@ -2229,8 +2229,8 @@ def direct(name, options = {}, &block)
         end
 
         # Define custom polymorphic mappings of models to URLs. This alters the behavior
-        # of `polymorphic_url` and consequently the behavior of `link_to` and `form_for`
-        # when passed a model instance, e.g:
+        # of `polymorphic_url` and consequently the behavior of `link_to`, `form_with`
+        # and `form_for` when passed a model instance, e.g:
         #
         #     resource :basket
         #
@@ -2239,7 +2239,7 @@ def direct(name, options = {}, &block)
         #     end
         #
         # This will now generate "/basket" when a `Basket` instance is passed to
-        # `link_to` or `form_for` instead of the standard "/baskets/:id".
+        # `link_to`, `form_with` or `form_for` instead of the standard "/baskets/:id".
         #
         # NOTE: This custom behavior only applies to simple polymorphic URLs where a
         # single model instance is passed and not more complicated forms, e.g:

actionpack/lib/action_dispatch/routing/polymorphic_routes.rb

@@ -31,7 +31,7 @@ module Routing
     # *   `url_for`, so you can use it with a record as the argument, e.g.
     #     `url_for(@article)`;
     # *   ActionView::Helpers::FormHelper uses `polymorphic_path`, so you can write
-    #     `form_for(@article)` without having to specify `:url` parameter for the
+    #     `form_with(model: @article)` without having to specify `:url` parameter for the
     #     form action;
     # *   `redirect_to` (which, in fact, uses `url_for`) so you can write
     #     `redirect_to(post)` in your controllers;
@@ -61,7 +61,7 @@ module Routing
     # argument to the method. For example:
     #
     #     polymorphic_url([blog, @post])  # calls blog.post_path(@post)
-    #     form_for([blog, @post])         # => "/blog/posts/1"
+    #     form_with(model: [blog, @post]) # => "/blog/posts/1"
     #
     module PolymorphicRoutes
       # Constructs a call to a named RESTful route for the given record and returns

actionview/lib/action_view/helpers/date_helper.rb

@@ -1228,7 +1228,7 @@ def separator(type)
     class FormBuilder
       # Wraps ActionView::Helpers::DateHelper#date_select for form builders:
       #
-      #   <%= form_for @person do |f| %>
+      #   <%= form_with model: @person do |f| %>
       #     <%= f.date_select :birth_date %>
       #     <%= f.submit %>
       #   <% end %>
@@ -1240,7 +1240,7 @@ def date_select(method, options = {}, html_options = {})
 
       # Wraps ActionView::Helpers::DateHelper#time_select for form builders:
       #
-      #   <%= form_for @race do |f| %>
+      #   <%= form_with model: @race do |f| %>
       #     <%= f.time_select :average_lap %>
       #     <%= f.submit %>
       #   <% end %>
@@ -1252,7 +1252,7 @@ def time_select(method, options = {}, html_options = {})
 
       # Wraps ActionView::Helpers::DateHelper#datetime_select for form builders:
       #
-      #   <%= form_for @person do |f| %>
+      #   <%= form_with model: @person do |f| %>
       #     <%= f.datetime_select :last_request_at %>
       #     <%= f.submit %>
       #   <% end %>

actionview/lib/action_view/helpers/form_helper.rb

@@ -30,20 +30,21 @@ module Helpers # :nodoc:
     # when the form is initially displayed, input fields corresponding to attributes
     # of the resource should show the current values of those attributes.
     #
-    # In \Rails, this is usually achieved by creating the form using +form_for+ and
-    # a number of related helper methods. +form_for+ generates an appropriate <tt>form</tt>
-    # tag and yields a form builder object that knows the model the form is about.
-    # Input fields are created by calling methods defined on the form builder, which
-    # means they are able to generate the appropriate names and default values
+    # In \Rails, this is usually achieved by creating the form using either
+    # +form_with+ or +form_for+ and a number of related helper methods. These
+    # methods generate an appropriate <tt>form</tt> tag and yield a form
+    # builder object that knows the model the form is about. Input fields are
+    # created by calling methods defined on the form builder, which means they
+    # are able to generate the appropriate names and default values
     # corresponding to the model attributes, as well as convenient IDs, etc.
-    # Conventions in the generated field names allow controllers to receive form data
-    # nicely structured in +params+ with no effort on your side.
+    # Conventions in the generated field names allow controllers to receive form
+    # data nicely structured in +params+ with no effort on your side.
     #
     # For example, to create a new person you typically set up a new instance of
     # +Person+ in the <tt>PeopleController#new</tt> action, <tt>@person</tt>, and
-    # in the view template pass that object to +form_for+:
+    # in the view template pass that object to +form_with+ or +form_for+:
     #
-    #   <%= form_for @person do |f| %>
+    #   <%= form_with model: @person do |f| %>
     #     <%= f.label :first_name %>:
     #     <%= f.text_field :first_name %><br />
     #
@@ -783,9 +784,9 @@ def form_with(model: false, scope: nil, url: nil, format: nil, **options, &block
         end
       end
 
-      # Creates a scope around a specific model object like form_with, 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_with+, but
+      # doesn't create the form tags themselves. This makes +fields_for+
+      # suitable for specifying additional model objects in the same form.
       #
       # Although the usage and purpose of +fields_for+ is similar to +form_with+'s,
       # its method signature is slightly different. Like +form_with+, it yields
@@ -2032,9 +2033,9 @@ def field_name(method, *methods, multiple: false, index: @options[:index])
       end
       alias_method :text_area, :textarea
 
-      # Creates a scope around a specific model object like form_with, 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_with+, but
+      # doesn't create the form tags themselves. This makes +fields_for+
+      # suitable for specifying additional model objects in the same form.
       #
       # Although the usage and purpose of +fields_for+ is similar to +form_with+'s,
       # its method signature is slightly different. Like +form_with+, it yields

actionview/lib/action_view/helpers/form_options_helper.rb

@@ -840,7 +840,7 @@ def prompt_text(prompt)
     class FormBuilder
       # Wraps ActionView::Helpers::FormOptionsHelper#select for form builders:
       #
-      #   <%= form_for @post do |f| %>
+      #   <%= form_with model: @post do |f| %>
       #     <%= f.select :person_id, Person.all.collect { |p| [ p.name, p.id ] }, include_blank: true %>
       #     <%= f.submit %>
       #   <% end %>
@@ -852,7 +852,7 @@ def select(method, choices = nil, options = {}, html_options = {}, &block)
 
       # Wraps ActionView::Helpers::FormOptionsHelper#collection_select for form builders:
       #
-      #   <%= form_for @post do |f| %>
+      #   <%= form_with model: @post do |f| %>
       #     <%= f.collection_select :person_id, Author.all, :id, :name_with_initial, prompt: true %>
       #     <%= f.submit %>
       #   <% end %>
@@ -864,7 +864,7 @@ def collection_select(method, collection, value_method, text_method, options = {
 
       # Wraps ActionView::Helpers::FormOptionsHelper#grouped_collection_select for form builders:
       #
-      #   <%= form_for @city do |f| %>
+      #   <%= form_with model: @city do |f| %>
       #     <%= f.grouped_collection_select :country_id, @continents, :countries, :name, :id, :name %>
       #     <%= f.submit %>
       #   <% end %>
@@ -876,7 +876,7 @@ def grouped_collection_select(method, collection, group_method, group_label_meth
 
       # Wraps ActionView::Helpers::FormOptionsHelper#time_zone_select for form builders:
       #
-      #   <%= form_for @user do |f| %>
+      #   <%= form_with model: @user do |f| %>
       #     <%= f.time_zone_select :time_zone, nil, include_blank: true %>
       #     <%= f.submit %>
       #   <% end %>
@@ -888,7 +888,7 @@ def time_zone_select(method, priority_zones = nil, options = {}, html_options =
 
       # Wraps ActionView::Helpers::FormOptionsHelper#weekday_select for form builders:
       #
-      #   <%= form_for @user do |f| %>
+      #   <%= form_with model: @user do |f| %>
       #     <%= f.weekday_select :weekday, include_blank: true %>
       #     <%= f.submit %>
       #   <% end %>
@@ -900,7 +900,7 @@ def weekday_select(method, options = {}, html_options = {})
 
       # Wraps ActionView::Helpers::FormOptionsHelper#collection_checkboxes for form builders:
       #
-      #   <%= form_for @post do |f| %>
+      #   <%= form_with model: @post do |f| %>
       #     <%= f.collection_checkboxes :author_ids, Author.all, :id, :name_with_initial %>
       #     <%= f.submit %>
       #   <% end %>
@@ -913,7 +913,7 @@ def collection_checkboxes(method, collection, value_method, text_method, options
 
       # Wraps ActionView::Helpers::FormOptionsHelper#collection_radio_buttons for form builders:
       #
-      #   <%= form_for @post do |f| %>
+      #   <%= form_with model: @post do |f| %>
       #     <%= f.collection_radio_buttons :author_id, Author.all, :id, :name_with_initial %>
       #     <%= f.submit %>
       #   <% end %>

actionview/lib/action_view/record_identifier.rb

@@ -11,7 +11,7 @@ module ActionView
   #
   # Consider for example the following code that form of post:
   #
-  #   <%= form_for(post) do |f| %>
+  #   <%= form_with(model: post) do |f| %>
   #     <%= f.text_field :body %>
   #   <% end %>
   #

railties/lib/rails/engine.rb

@@ -245,7 +245,7 @@ module Rails
   #   polymorphic_url(MyEngine::Article.new)
   #   # => "articles_path" # not "my_engine_articles_path"
   #
-  #   form_for(MyEngine::Article.new) do
+  #   form_with(model: MyEngine::Article.new) do
   #     text_field :title # => <input type="text" name="article[title]" id="article_title" />
   #   end
   #
@@ -294,7 +294,7 @@ module Rails
   # All you need to do is pass the helper as the first element in array with
   # attributes for URL:
   #
-  #   form_for([my_engine, @user])
+  #   form_with(model: [my_engine, @user])
   #
   # This code will use <tt>my_engine.user_path(@user)</tt> to generate the proper route.
   #