Merge pull request rails#50744 from takatea/fix-docs-form_for-to-form_with-in-form_helper

skipkayhil · web-flow · commit cf64895067e2 · 2024-05-01T12:57:11.000-04:00
docs: Update FormHelper comments to use `form_with` instead of `form_for` [ci skip]
diff --git a/actionview/lib/action_view/helpers/form_helper.rb b/actionview/lib/action_view/helpers/form_helper.rb
@@ -783,12 +783,12 @@ 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_for, but
+      # 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_for+'s,
-      # its method signature is slightly different. Like +form_for+, it yields
+      # 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
       # a FormBuilder object associated with a particular model object to a block,
       # and within the block allows methods to be called on the builder to
       # generate fields associated with the model object. Fields may reflect
@@ -799,7 +799,7 @@ def form_with(model: false, scope: nil, url: nil, format: nil, **options, &block
       # both an object name (represented by either a symbol or string) and the
       # object itself can be passed to the method separately -
       #
-      #   <%= form_for @person do |person_form| %>
+      #   <%= form_with model: @person do |person_form| %>
       #     First name: <%= person_form.text_field :first_name %>
       #     Last name : <%= person_form.text_field :last_name %>
       #
@@ -880,7 +880,7 @@ def form_with(model: false, scope: nil, url: nil, format: nil, **options, &block
       #
       # This model can now be used with a nested fields_for, like so:
       #
-      #   <%= form_for @person do |person_form| %>
+      #   <%= form_with model: @person do |person_form| %>
       #     ...
       #     <%= person_form.fields_for :address do |address_fields| %>
       #       Street  : <%= address_fields.text_field :street %>
@@ -910,7 +910,7 @@ def form_with(model: false, scope: nil, url: nil, format: nil, **options, &block
       # with a value that evaluates to +true+, you will destroy the associated
       # model (e.g. 1, '1', true, or 'true'):
       #
-      #   <%= form_for @person do |person_form| %>
+      #   <%= form_with model: @person do |person_form| %>
       #     ...
       #     <%= person_form.fields_for :address do |address_fields| %>
       #       ...
@@ -951,7 +951,7 @@ def form_with(model: false, scope: nil, url: nil, format: nil, **options, &block
       # the nested fields_for call will be repeated for each instance in the
       # collection:
       #
-      #   <%= form_for @person do |person_form| %>
+      #   <%= form_with model: @person do |person_form| %>
       #     ...
       #     <%= person_form.fields_for :projects do |project_fields| %>
       #       <% if project_fields.object.active? %>
@@ -963,7 +963,7 @@ def form_with(model: false, scope: nil, url: nil, format: nil, **options, &block
       #
       # It's also possible to specify the instance to be used:
       #
-      #   <%= form_for @person do |person_form| %>
+      #   <%= form_with model: @person do |person_form| %>
       #     ...
       #     <% @person.projects.each do |project| %>
       #       <% if project.active? %>
@@ -977,7 +977,7 @@ def form_with(model: false, scope: nil, url: nil, format: nil, **options, &block
       #
       # Or a collection to be used:
       #
-      #   <%= form_for @person do |person_form| %>
+      #   <%= form_with model: @person do |person_form| %>
       #     ...
       #     <%= person_form.fields_for :projects, @active_projects do |project_fields| %>
       #       Name: <%= project_fields.text_field :name %>
@@ -999,7 +999,7 @@ def form_with(model: false, scope: nil, url: nil, format: nil, **options, &block
       # parameter with a value that evaluates to +true+
       # (e.g. 1, '1', true, or 'true'):
       #
-      #   <%= form_for @person do |person_form| %>
+      #   <%= form_with model: @person do |person_form| %>
       #     ...
       #     <%= person_form.fields_for :projects do |project_fields| %>
       #       Delete: <%= project_fields.check_box :_destroy %>
@@ -1011,7 +1011,7 @@ def form_with(model: false, scope: nil, url: nil, format: nil, **options, &block
       # object in the array. For this purpose, the <tt>index</tt> method is
       # available in the FormBuilder object.
       #
-      #   <%= form_for @person do |person_form| %>
+      #   <%= form_with model: @person do |person_form| %>
       #     ...
       #     <%= person_form.fields_for :projects do |project_fields| %>
       #       Project #<%= project_fields.index %>
@@ -1220,7 +1220,7 @@ def hidden_field(object_name, method, options = {})
       # hash with +options+. These options will be tagged onto the HTML as an HTML element attribute as in the example
       # shown.
       #
-      # Using this method inside a +form_for+ block will set the enclosing form's encoding to <tt>multipart/form-data</tt>.
+      # Using this method inside a +form_with+ block will set the enclosing form's encoding to <tt>multipart/form-data</tt>.
       #
       # ==== Options
       # * Creates standard HTML attributes for the tag.
@@ -1629,10 +1629,10 @@ def default_form_builder_class
     #
     # A +FormBuilder+ object is associated with a particular model object and
     # allows you to generate fields associated with the model object. The
-    # +FormBuilder+ object is yielded when using +form_for+ or +fields_for+.
+    # +FormBuilder+ object is yielded when using +form_with+ or +fields_for+.
     # For example:
     #
-    #   <%= form_for @person do |person_form| %>
+    #   <%= form_with model: @person do |person_form| %>
     #     Name: <%= person_form.text_field :name %>
     #     Admin: <%= person_form.check_box :admin %>
     #   <% end %>
@@ -1668,7 +1668,7 @@ def default_form_builder_class
     #
     # The +div_radio_button+ code from above can now be used as follows:
     #
-    #   <%= form_for @person, :builder => MyFormBuilder do |f| %>
+    #   <%= form_with model: @person, :builder => MyFormBuilder do |f| %>
     #     I am a child: <%= f.div_radio_button(:admin, "child") %>
     #     I am an adult: <%= f.div_radio_button(:admin, "adult") %>
     #   <% end -%>
@@ -1738,7 +1738,7 @@ def initialize(object_name, object, template, options)
       #
       # return the <tt><form></tt> element's <tt>id</tt> attribute.
       #
-      #   <%= form_for @article do |f| %>
+      #   <%= form_with model: @article do |f| %>
       #     <%# ... %>
       #
       #     <% content_for :sticky_footer do %>
@@ -1760,7 +1760,7 @@ def id
       # Return the value generated by the <tt>FormBuilder</tt> for the given
       # attribute name.
       #
-      #   <%= form_for @article do |f| %>
+      #   <%= form_with model: @article do |f| %>
       #     <%= f.label :title %>
       #     <%= f.text_field :title, aria: { describedby: f.field_id(:title, :error) } %>
       #     <%= tag.span("is blank", id: f.field_id(:title, :error) %>
@@ -1781,12 +1781,12 @@ def field_id(method, *suffixes, namespace: @options[:namespace], index: @options
       # Return the value generated by the <tt>FormBuilder</tt> for the given
       # attribute name.
       #
-      #   <%= form_for @article do |f| %>
+      #   <%= form_with model: @article do |f| %>
       #     <%= f.text_field :title, name: f.field_name(:title, :subtitle) %>
       #     <%# => <input type="text" name="article[title][subtitle]"> %>
       #   <% end %>
       #
-      #   <%= form_for @article do |f| %>
+      #   <%= form_with model: @article do |f| %>
       #     <%= f.text_field :tag, name: f.field_name(:tag, multiple: true) %>
       #     <%# => <input type="text" name="article[tag][]"> %>
       #   <% end %>
@@ -2034,12 +2034,12 @@ def #{selector}(method, options = {})  # def text_field(method, options = {})
         end
       end
 
-      # Creates a scope around a specific model object like form_for, but
+      # 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_for+'s,
-      # its method signature is slightly different. Like +form_for+, it yields
+      # 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
       # a FormBuilder object associated with a particular model object to a block,
       # and within the block allows methods to be called on the builder to
       # generate fields associated with the model object. Fields may reflect
@@ -2050,7 +2050,7 @@ def #{selector}(method, options = {})  # def text_field(method, options = {})
       # both an object name (represented by either a symbol or string) and the
       # object itself can be passed to the method separately -
       #
-      #   <%= form_for @person do |person_form| %>
+      #   <%= form_with model: @person do |person_form| %>
       #     First name: <%= person_form.text_field :first_name %>
       #     Last name : <%= person_form.text_field :last_name %>
       #
@@ -2099,7 +2099,7 @@ def #{selector}(method, options = {})  # def text_field(method, options = {})
       # name and value parameters are provided and the provided value has the shape of an
       # option Hash. To remove the ambiguity, explicitly pass an option Hash, even if empty.
       #
-      #   <%= form_for @person do |person_form| %>
+      #   <%= form_with model: @person do |person_form| %>
       #     ...
       #     <%= fields_for :permission, @person.permission, {} do |permission_fields| %>
       #       Admin?: <%= check_box_tag permission_fields.field_name(:admin), @person.permission[:admin] %>
@@ -2143,7 +2143,7 @@ def #{selector}(method, options = {})  # def text_field(method, options = {})
       #
       # This model can now be used with a nested fields_for, like so:
       #
-      #   <%= form_for @person do |person_form| %>
+      #   <%= form_with model: @person do |person_form| %>
       #     ...
       #     <%= person_form.fields_for :address do |address_fields| %>
       #       Street  : <%= address_fields.text_field :street %>
@@ -2173,7 +2173,7 @@ def #{selector}(method, options = {})  # def text_field(method, options = {})
       # with a value that evaluates to +true+, you will destroy the associated
       # model (e.g. 1, '1', true, or 'true'):
       #
-      #   <%= form_for @person do |person_form| %>
+      #   <%= form_with model: @person do |person_form| %>
       #     ...
       #     <%= person_form.fields_for :address do |address_fields| %>
       #       ...
@@ -2214,7 +2214,7 @@ def #{selector}(method, options = {})  # def text_field(method, options = {})
       # the nested fields_for call will be repeated for each instance in the
       # collection:
       #
-      #   <%= form_for @person do |person_form| %>
+      #   <%= form_with model: @person do |person_form| %>
       #     ...
       #     <%= person_form.fields_for :projects do |project_fields| %>
       #       <% if project_fields.object.active? %>
@@ -2226,7 +2226,7 @@ def #{selector}(method, options = {})  # def text_field(method, options = {})
       #
       # It's also possible to specify the instance to be used:
       #
-      #   <%= form_for @person do |person_form| %>
+      #   <%= form_with model: @person do |person_form| %>
       #     ...
       #     <% @person.projects.each do |project| %>
       #       <% if project.active? %>
@@ -2240,7 +2240,7 @@ def #{selector}(method, options = {})  # def text_field(method, options = {})
       #
       # Or a collection to be used:
       #
-      #   <%= form_for @person do |person_form| %>
+      #   <%= form_with model: @person do |person_form| %>
       #     ...
       #     <%= person_form.fields_for :projects, @active_projects do |project_fields| %>
       #       Name: <%= project_fields.text_field :name %>
@@ -2262,7 +2262,7 @@ def #{selector}(method, options = {})  # def text_field(method, options = {})
       # parameter with a value that evaluates to +true+
       # (e.g. 1, '1', true, or 'true'):
       #
-      #   <%= form_for @person do |person_form| %>
+      #   <%= form_with model: @person do |person_form| %>
       #     ...
       #     <%= person_form.fields_for :projects do |project_fields| %>
       #       Delete: <%= project_fields.check_box :_destroy %>
@@ -2274,7 +2274,7 @@ def #{selector}(method, options = {})  # def text_field(method, options = {})
       # object in the array. For this purpose, the <tt>index</tt> method
       # is available in the FormBuilder object.
       #
-      #   <%= form_for @person do |person_form| %>
+      #   <%= form_with model: @person do |person_form| %>
       #     ...
       #     <%= person_form.fields_for :projects do |project_fields| %>
       #       Project #<%= project_fields.index %>
@@ -2562,7 +2562,7 @@ def file_field(method, options = {})
       # Add the submit button for the given form. When no value is given, it checks
       # if the object is a new resource or not to create the proper label:
       #
-      #   <%= form_for @article do |f| %>
+      #   <%= form_with model: @article do |f| %>
       #     <%= f.submit %>
       #   <% end %>
       #
@@ -2595,7 +2595,7 @@ def submit(value = nil, options = {})
       # Add the submit button for the given form. When no value is given, it checks
       # if the object is a new resource or not to create the proper label:
       #
-      #   <%= form_for @article do |f| %>
+      #   <%= form_with model: @article do |f| %>
       #     <%= f.button %>
       #   <% end %>
       # In the example above, if <tt>@article</tt> is a new record, it will use "Create Article" as
