Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

[ci skip]Docs highlight form_with over form_for #51704

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

[ci skip]Docs highlight form_with over form_for #51704

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
6 changes: 3 additions & 3 deletions actionpack/lib/action_controller/form_builder.rb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
6 changes: 3 additions & 3 deletions actionpack/lib/action_dispatch/routing/mapper.rb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2199,8 +2199,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
#
Expand All @@ -2209,7 +2209,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:
Expand Down
4 changes: 2 additions & 2 deletions actionpack/lib/action_dispatch/routing/polymorphic_routes.rb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down Expand Up @@ -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
Expand Down
6 changes: 3 additions & 3 deletions actionview/lib/action_view/helpers/date_helper.rb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 %>
Expand All @@ -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 %>
Expand All @@ -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 %>
Expand Down
91 changes: 46 additions & 45 deletions actionview/lib/action_view/helpers/form_helper.rb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,20 +30,20 @@ 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
# 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.
# In \Rails, this is usually achieved by creating the form using either +form_with+
# or +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 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.
#
# 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 />
#
Expand Down Expand Up @@ -783,13 +783,14 @@ 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
# 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 or
# form_for, 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
# a FormBuilder object associated with a particular model object to a block,
# The usage and purpose of +fields_for+ is similar to +form_with+ or
# +form_for+. Like +form_with+ and +form_for+, 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
# a model object in two ways - how they are named (hence how submitted
Expand All @@ -799,7 +800,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 %>
#
Expand Down Expand Up @@ -880,7 +881,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 %>
Expand Down Expand Up @@ -910,7 +911,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| %>
# ...
Expand Down Expand Up @@ -951,7 +952,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? %>
Expand All @@ -963,7 +964,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? %>
Expand All @@ -977,7 +978,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 %>
Expand All @@ -999,7 +1000,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 %>
Expand All @@ -1011,7 +1012,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 %>
Expand Down Expand Up @@ -1220,7 +1221,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+ or +form_for+ block will set the enclosing form's encoding to <tt>multipart/form-data</tt>.
#
# ==== Options
# * Creates standard HTML attributes for the tag.
Expand Down Expand Up @@ -1629,10 +1630,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+, +form_for+ 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 %>
Expand Down Expand Up @@ -1738,7 +1739,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 %>
Expand All @@ -1760,7 +1761,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) %>
Expand All @@ -1781,12 +1782,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 %>
Expand Down Expand Up @@ -2038,9 +2039,9 @@ def #{selector}(method, options = {}) # def text_field(method, options = {})
# 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
# a FormBuilder object associated with a particular model object to a block,
# The usage and purpose of +fields_for+ is similar to +form_with+ or
# +form_for+. Like +form_with+ and +form_for+, 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
# a model object in two ways - how they are named (hence how submitted
Expand All @@ -2050,7 +2051,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 %>
#
Expand Down Expand Up @@ -2099,7 +2100,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] %>
Expand Down Expand Up @@ -2143,7 +2144,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 %>
Expand Down Expand Up @@ -2173,7 +2174,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| %>
# ...
Expand Down Expand Up @@ -2214,7 +2215,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? %>
Expand All @@ -2226,7 +2227,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? %>
Expand All @@ -2240,7 +2241,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 %>
Expand All @@ -2262,7 +2263,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 %>
Expand All @@ -2274,7 +2275,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 %>
Expand Down Expand Up @@ -2562,7 +2563,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 %>
#
Expand Down Expand Up @@ -2595,7 +2596,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
Expand Down