Rails 5.1〜7.1: 'form_with' APIドキュメント（翻訳）

こんにちは、hachi8833です。Rails 6.1の#form_withのAPIドキュメント変更を反映しました。form_withはRailsのビューでフォームを送信するためのヘルパーメソッドです。

5.1より前のform_forやform_tagはその後非推奨になりました。5.1以降はこのform_withだけを使いましょう。

参考: Provide form_with as a new alternative to form_for/form_tag · Issue #25197 · rails/rails

原文の更新や訳文の誤りにお気づきの方は、@hachi8833までお知らせください。

Rails 5.1〜7.0: 'form_with' APIドキュメント（翻訳）

# API呼び出し
form_with(model: nil, scope: nil, url: nil, format: nil, **options)

URL、スコープ、モデルの組み合わせを元にformタグを作成します。

⚓ URLのみを指定する

<%= form_with url: posts_path do |form| %>
<%= form.text_field :title %>
<% end %>

# =>
<form action="/posts" method="post">
  <input type="text" name="title">
</form>

<!-- Rails 6.1まで -->
<form action="/posts" method="post" data-remote="true">

<!-- Rails 7 -->
<form action="/posts" method="post">

意図的に空URLを渡す（Rails 7）

<%= form_with url: false do |form| %>
  <%= form.text_field :title %>
<% end %>

# =>
<form method="post">
  <input type="text" name="title">
</form>

⚓ inputフィールド名にスコープのプレフィックスを追加する

<%= form_with scope: :post, url: posts_path do |form| %>
  <%= form.text_field :title %>
<% end %>

# =>
<form action="/posts" method="post">
  <input type="text" name="post[title]">
</form>

⚓ 渡されたモデルからURLとスコープを自動推測する

<%= form_with model: Post.new do |form| %>
  <%= form.text_field :title %>
<% end %>

# =>
<form action="/posts" method="post">
  <input type="text" name="post[title]">
</form>

⚓ 既存のモデルを更新するフォームで、モデルの値をフィールドに表示する

<%= form_with model: Post.first do |form| %>
  <%= form.text_field :title %>
<% end %>

# =>
<form action="/posts/1" method="post">
  <input type="hidden" name="_method" value="patch">
  <input type="text" name="post[title]" value="<postのtitle>">
</form>

⚓ フォームのフィールドは、必ずしもモデルの属性と対応してなくてもよい

<%= form_with model: Cat.new do |form| %>
  <%= form.text_field :cats_dont_have_gills %>
  <%= form.text_field :but_in_forms_they_can %>
<% end %>

# =>
<form action="/cats" method="post">
  <input type="text" name="cat[cats_dont_have_gills]">
  <input type="text" name="cat[but_in_forms_they_can]">
</form>

フォームのパラメータは、コントローラでパラメータのネストに沿ってアクセスできます。つまり、inputフィールドにtitleとpost[title]というフィールド名がある場合、コントローラではそれぞれparams[:title]とparams[:post][:title]としてアクセスできます。

上述のコード例では、比較しやすさのため送信ボタンを省略しています。また、UTF-8サポートを有効にする自動生成のhiddenフィールドや、CSRF（Cross Site Request Forgery）保護に必要な認証トークンも省略しています。

⚓ リソース指向のスタイル

上述のコード例の多くでは、単にform_withに:modelを渡しています。これはRESTfulなルーティングのセットに対応しており、そのほとんどはconfig/routes.rbのresourcesで定義されます。

したがって、そうしたモデルのレコードを1件渡せば、RailsがURLやメソッドを推測します。

<%= form_with model: @post do |form| %>
  ...
<% end %>

上のコードは以下のようなコードと同等になります。

<%= form_with scope: :post, url: post_path(@post), method: :patch do |form| %>
  ...
<% end %>

新規レコードについても同様です。

<%= form_with model: Post.new do |form| %>
  ...
<% end %>

上のコードは以下のようなコードと同等になります。

<%= form_with scope: :post, url: posts_path do |form| %>
  ...
<% end %>

⚓ #form_withで利用できるオプション

:url

フォームの送信先URLを指定します。
渡せる値は、url_forやlink_toで渡せる値と似ています。たとえば、名前付きルートを直接渡すこともできますし、:urlなしで:scopeを渡すと、現在のURLにフォームを送信することもできます。

:method

フォーム送信時のHTTPメソッド（verb）を指定します。
通常は:getや:postを指定します。
:patch、:put、:deleteを指定すると、隠しinput名の後ろに_methodが追加され、POST verb上でこれらのHTTP verbをシミュレートします。

:format

フォーム送信先であるルーティングのフォーマットを指定します。
:jsonなど通常と異なるリソースタイプを送信するのに便利です。
:urlがオプションに渡されている場合、このオプションはスキップされます。

:scope

inputフィールド名のプレフィックスにスコープを追加します。これにより、送信されたパラメータをコントローラでグループ化できます。

:namespace

フォームの要素でid属性を一意にする名前空間です。namespace属性で指定した名前にアンダースコアを追加したものが、生成されたHTML idの前に追加されます。

:model

:urlや:scopeの自動推測に使うモデルオブジェクトを指定し、inputフィールドにモデルの値を表示します。
たとえば、title属性の値が"Ahoy!"ならtitleの入力フィールドの値に"Ahoy!"と表示されます。
モデルが新しいレコードの場合は作成用フォームが生成され、モデルが既存のレコードの場合は更新用フォームが生成されます。
デフォルトの動作を上書きするには、:scopeか:urlを渡します（params[:post]をparams[:article]に変更するなど）。

:authenticity_token

フォームで使う認証トークンを指定します。
カスタムの認証トークンを指定して上書きすることも、falseを渡して認証トークンのフィールドをスキップすることもできます。
有効なフィールドのみに制限されている支払用ゲートウェイへのような外部リソースにフォームを送信する場合に便利です。

config.action_view.embed_authenticity_token_in_remote_forms = falseを指定すると、埋め込み認証トークンがremoteフォームで省略されることがあります。この指定はフォームでフラグメントキャッシュを使う場合に便利です（remoteフォームがmetaタグから認証トークンを取得するようになるので、JavaScriptがオフになっているブラウザをサポートする場合を除けば認証トークンをフォームに埋め込む必要がなくなります）。

:local

（Rails 7）標準のHTTPフォームを送信するかどうかを指定します。trueを指定すると、フォームは標準のHTTPで送信されます。falseを指定すると、フォームは「リモートフォーム」として送信され、Rails UJSによってXHRとして処理されます。

指定のない場合の振る舞いは、config.action_view.form_with_generates_remote_forms設定から導出されますが、この設定の値は実際にはlocalの値と逆です。
Rails 6.1では、この設定オプションはデフォルトでfalseになります（local: trueを渡すのと同等）。
それより前のバージョンのRailsでは、この設定オプションはデフォルトでtrueになります（local: falseを渡すのと同等）。

:skip_enforcing_utf8

trueを指定すると、送信時にutf8という名前の隠しフィールドが出力されなくなります。

:builder

フォームのビルドに使うオブジェクトをオーバーライドします。

:id

HTMLのid属性を指定します（オプション）。

:class

HTMLのclass属性を指定します（オプション）。

:data

HTMLのdata属性を指定します（オプション）。

:html

上以外のHTML属性を使う場合に指定します（オプション）。

⚓ 例

#form_withにブロックを渡さない場合は、開始formタグを生成します。

# 名前付きパスを指定する場合
<%= form_with(model: @post, url: super_posts_path) %>

# スコープを追加する場合
<%= form_with(model: @post, scope: :article) %>

# フォーマットを指定する場合
<%= form_with(model: @post, format: :json) %>

# トークンを無効にする場合
<%= form_with(model: @post, authenticity_token: false) %> 

ルーティングをadmin_post_urlのように名前空間化する場合は以下のようにします。

<%= form_with(model: [ :admin, @post ]) do |form| %>
  ...
<% end %>

たとえばリソースに関連付けが定義されているとします。ルーティングが正しく設定されているdocumentにcommentを追加したい場合は次のようにします。

<%= form_with(model: [ @document, Comment.new ]) do |form| %>
  ...
<% end %>

上のdocumentには@document = Document.find(params[:id])が既に与えられているとします。

更新（2020/03/09）以下はRails 6.0で削除されました。

⚓ 他のフォームヘルパーと組み合わせる

#form_withではFormBuilderオブジェクトが使われていますが、単独のFormHelperのメソッドやFormTagHelperのメソッドと共存させることもできます。

<%= form_with scope: :person do |form| %>
  <%= form.text_field :first_name %>
  <%= form.text_field :last_name %>

  <%= text_area :person, :biography %>
  <%= check_box_tag "person[admin]", "1", @person.company.admin? %>

  <%= form.submit %>
<% end %>

同様に、FormOptionsHelperのメソッド（FormOptionsHelper#collection_selectなど）と共存させたり、DateHelperのメソッド（ActionView::Helpers::DateHelper#datetime_selectなど）と共存させることもできます。

⚓ HTTPメソッド（verb）の指定方法

以下のHTTP verbの完全な配列をoptionsハッシュに渡すことができます。

method: (:get|:post|:patch|:put|:delete)

verbがGETやPOST以外の場合（この2つはHTMLフォームでネイティブでサポートされます）、フォームそのものにはPOST verbが設定され、_methodという名前の隠しinputフィールドには指定の verbが設定され、後者がサーバーで解釈されます。

⚓ HTMLオプションの設定方法

HTMLのdata-*属性はdata:ハッシュで直接渡せますが、id:やclass:を含む他のすべてのHTMLオプションについては次のようにhtml:ハッシュの中に置く必要があります。

<%= form_with(model: @post,
              data: { behavior: "autosave" },
              html: { name: "go" }) do |form| %>
  ...
<% end %>

上のコードから以下のHTMLが生成されます。

<form action="/posts/123" method="post" data-behavior="autosave" name="go">
  <input name="_method" type="hidden" value="patch" />
  ...
</form>

⚓ 非表示のモデルidを出力しないようにする

#form_withメソッドを使うと、自動的にモデルidが隠しフィールドとしてフォームに含まれます。このモデルidは、フォームデータとそれに関連付けられているモデルとの関連を保つために使われます。

ORMシステムによってはネストしたモデルでこうしたidを使わないものもあるので、その場合は次のようにinclude_id: falseを指定することで隠しフィールドのモデルidを出力しないようにできます。

<%= form_with(model: @post) do |form| %>
  <%= form.fields(:comments, skip_id: true) do |fields| %>
    ...
  <% end %>
<% end %>

上の例では、NoSQLデータベースにPostというモデルがひとつと、それに一対多で関連付けられるCommentというモデルが保存されています。:commentsには主キーはありません。

⚓ フォームビルダをカスタマイズする

FormBuilderクラスをカスタマイズしてフォームをビルドすることもできます。カスタマイズするには、FormBuilderを継承してサブクラスを作り、必要なヘルパーメソッドを定義またはオーバーライドします。

次のコード例では、フォームのinputにラベルを自動追加するヘルパーを作成済みであることが前提です。

<%= form_with model: @person, url: { action: "create" }, builder: LabellingFormBuilder do |form| %>
  <%= form.text_field :first_name %>
  <%= form.text_field :last_name %>
  <%= form.text_area :biography %>
  <%= form.check_box :admin %>
  <%= form.submit %>
<% end %>

上のようにコードを書いてから、次のコードを書きます。

<%= render form %>

これにより、people/_labelling_formというテンプレートを使ってレンダリング（=HTML生成）され、フォームビルダを参照するローカル変数の名前はlabelling_formになります。

特に指定しない限り、カスタムのFormBuilderクラスは、ネストした#fields_for呼び出しのオプションと自動的にマージされます。

上のようなコードを別のヘルパーにも含めておきたい場合、多くは以下のように書くこともできます。

def labelled_form_with(**options, &block)
  form_with(**options.merge(builder: LabellingFormBuilder), &block)
end

関連記事

Rails 6.1で form_withのデフォルトが「remoteなし」になった（翻訳）