[Rails 5][Rails 4] 'link_to' APIドキュメント完全翻訳

こんにちは、hachi8833です。Rails 4と5の#link_toメソッドのAPIドキュメントを翻訳いたしました。

概要

Rails 3、4、5のform_forメソッドを最新の公式APIドキュメントでチェックしてみたところ、現時点でのRails 4とRails 5向けform_forメソッドのAPIドキュメントは完全に一致していました。

また、Rails 3のAPIオプション数はRails 4/5よりも少なくなっています。

• 原文APIドキュメント: link_to: Rails 4.2.8
• 原文APIドキュメント: link_to: Rails 5.0.2

Rails 3の#link_toAPIドキュメントについては以下をご覧ください。

• [Rails 3] 'link_to' APIドキュメント完全翻訳

link_to APIドキュメント

# API呼び出し（Rails 4、Rails 5共通）
link_to(name = nil, options = nil, html_options = nil, &block)

一連のオプションで作成されたURLと、指定のリンク名を使って、アンカー要素を作成します。正しいオプションについては、url_forのドキュメントを参照してください。

optionsハッシュの代わりにStringも渡せます。その場合は、Stringの値をリンクのhrefとしてanchor要素を生成します。

optionsハッシュの代わりに:backというシンボルを渡すと、リファラへのリンクを生成します。該当のリンク先がない場合は、JavaScriptによってリファラの代わりにバック用リンクが使われます。

nameにnilを渡すと、リンク自身の値がリンク名として使われます。

シグネチャ

link_to(body, url, html_options = {})
  # url はString（posts_pathなどのURLヘルパーメソッドも使える）

link_to(body, url_options = {}, html_options = {})
  # url_options（ただし:methodは除く）はurl_forに渡される

link_to(options = {}, html_options = {}) do
  # name
end

link_to(url, html_options = {}) do
  # name
end

オプション

data:

カスタムのdata-属性を渡すのに使います。

method:

HTTP verbをシンボルで渡します。この修飾子はHTMLフォームを動的に生成し、指定のHTTP verbで即座にフォームを処理のために送信します。
このオプションは、リンクをクリックしたときにレコード削除などの危険なアクション（検索ボットがサイトからこうしたリンクを探り当てることがあります）をPOST操作で行わせたいときに便利です。
サポートされている操作は:post、:delete、:patch、:putです。ただし、ユーザーがJavaScriptを無効にしている場合は動作がフォールバックし、リクエストはGETで行われます。
href: '#'を指定すると、ユーザーがJavaScriptを無効にしている場合のリンクは無効になります。
アプリがPOSTの動作に依存している場合は、コントローラのアクションで#post?、#delete?、#patch?、#put?を使ってリクエストオブジェクトのメソッドがどれであるかを確認する必要があります。

remote:

trueを指定すると、リクエストをURLに送信する際にリンクをたどるのではなく、Unobtrusive JavaScript（控えめなJavaScript）ドライバを使ってAjaxリクエストを送信します。ドライバはAjaxリクエストの完了をリッスンし、完了後にJavaScript操作を実行しますが、そのメカニズムはドライバの実装に依存します。

data属性に与えられるオプション

confirm: '質問文'

このオプションを指定すると、ユーザーへの問い合わせメッセージ（この場合は「質問文」）をUnobtrusive JavaScriptドライバで表示できるようになります。ユーザーがこれを了承するとリンクは通常どおりに実行され、了承しない場合は何も実行されません。

:disable_with

このパラメータの値は、フォーム送信時の送信ボタンが無効になっているときの送信ボタン名として使われます。この機能はUnobtrusive JavaScriptドライバによって提供されます。

例

#link_toの動作は#url_forに依存しています。これにより、#link_toでは従来の「コントローラ/アクション/id」スタイルの引数と、新しいRESTfulルーティングのどちらも利用できます。現在のRailsでは可能な限りRESTfulルーティングスタイルを使うことが推奨されていますので、アプリのルーティングをリソースベースで行っている場合は、次のように書けます。

link_to "Profile", profile_path(@profile)
# => <a href="/profiles/1">Profile</a>

次のようにもっと簡潔に書くこともできます。

link_to "Profile", @profile
# => <a href="/profiles/1">Profile</a>

冗長になりますが、以下のようにリソース指向でない従来の方法で書くこともできます。

link_to "Profile", controller: "profiles", action: "show", id: @profile
# => <a href="/profiles/show/1">Profile</a>

同様に、以下の書き方もおすすめです。

link_to "Profiles", profiles_path
# => <a href="/profiles">Profiles</a>

以下は上よりも冗長であり、おすすめしません。

link_to "Profiles", controller: "profiles"
# => <a href="/profiles">Profiles</a>

リンク先がnameパラメータに合わせにくい場合は、次のようにブロックも使えます。ERBの例を示します。

<%= link_to(@profile) do %>
  <strong><%= @profile.name %></strong> -- <span>Check it out!</span>
<% end %>
# => <a href="/profiles/1">
       <strong>David</strong> -- <span>Check it out!</span>
     </a>

CSSのidやclassも以下のように簡単に生成できます。

link_to "Articles", articles_path, id: "news", class: "article"
# => <a href="/articles" class="article" id="news">Articles</a>

RESTfulでない従来のスタイルの場合は、以下のようにリテラルハッシュが必要です。

link_to "Articles", { controller: "articles" }, id: "news", class: "article"
# => <a href="/articles" class="article" id="news">Articles</a>

リテラルハッシュがないと、次のような誤ったリンクが生成されます。

link_to "WRONG!", controller: "articles", id: "news", class: "article"
# => <a href="/articles/index/news?class=article">WRONG!</a>

#link_toでは、anchor:でリンクにアンカーを追加したり、query:でリンクにクエリ文字列を追加することもできます。

link_to "Comment wall", profile_path(@profile, anchor: "wall")
# => <a href="/profiles/1#wall">Comment wall</a>

link_to "Ruby on Rails search", controller: "searches", query: "ruby on rails"
# => <a href="/searches?query=ruby+on+rails">Ruby on Rails search</a>

link_to "Nonsense search", searches_path(foo: "bar", baz: "quux")
# => <a href="/searches?foo=bar&baz=quux">Nonsense search</a>

link_to (:method)固有のオプション（:post、:delete、:patch、:put）は以下のような方法でのみ使えます。

link_to("Destroy", "http://www.example.com", method: :delete)
# => <a href='http://www.example.com' rel="nofollow" data-method="delete">Destroy</a>

data:オプションを使って、カスタムのデータ属性を渡すこともできます。

link_to "Visit Other Site", "http://www.rubyonrails.org/", data: { confirm: "Are you sure?" }
# => <a href="http://www.rubyonrails.org/" data-confirm="Are you sure?">Visit Other Site</a>

他にも、target:、rel:、type:などで任意のリンク属性を指定することもできます。

link_to "External link", "http://www.rubyonrails.org/", target: "_blank", rel: "nofollow"
# => <a href="http://www.rubyonrails.org/" target="_blank" rel="nofollow">External link</a>

関連記事

Rails: ビューのHTMLエスケープは#link_toなどのヘルパーメソッドで解除されることがある

Rails 4、Rails 5

[Rails 4][Rails 5] ‘form_for’ APIドキュメント完全翻訳

Rails 3

[Rails 3] ‘form_for’ APIドキュメント完全翻訳

https://techracho.bpsinc.jp/hachi8833/2017_04_24/39128

[Rails 3] link_toのmethodが効かない！？