こんにちは、hachi8833です。Rails 3の#link_toメソッドのAPIドキュメントを翻訳いたしました。
概要
- 原文APIドキュメント:
link_to: Rails 3.2.22.5
Rails 4とRails 5の#link_toAPIドキュメントについては以下をご覧ください。
link_to APIドキュメント（Rails 3）
# API呼び出し（Rails 3）
link_to(*args, &block)
一連のオプションで作成されたURLと、指定のリンク名を使ってlinkタグを作成します。正しいオプションについては、url_forのドキュメントを参照してください。
optionsハッシュの代わりにStringも渡せます。その場合は、Stringの値をリンクのhrefとしてlinkタグを生成します。
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（ただし:confirmと:methodは除く）はurl_forに渡される
link_to(options = {}, html_options = {}) do
# name
end
link_to(url, html_options = {}) do
# name
end
オプション
confirm: '質問文'- このオプションを指定すると、ユーザーへの問い合わせメッセージ（この場合は「質問文」）をUnobtrusive JavaScriptドライバで表示できるようになります。ユーザーがこれを了承するとリンクは通常どおりに実行され、了承しない場合は何も実行されません。
method:- HTTP verbをシンボルで渡します。この修飾子はHTMLフォームを動的に生成し、指定のHTTP verbで即座にフォームを処理のために送信します。
このオプションは、リンクをクリックしたときにレコード削除などの危険なアクション（検索ボットがサイトからこうしたリンクを探り当てることがあります）をPOST操作で行わせたいときに便利です。
サポートされている操作は:post、:delete、:putです。ただし、ユーザーがJavaScriptを無効にしている場合は動作がフォールバックし、リクエストはGETで行われます。
href: '#'を指定すると、ユーザーがJavaScriptを無効にしている場合のリンクは無効になります。
アプリがPOSTの動作に依存している場合は、コントローラのアクションで#post?、#delete?、#put?を使ってリクエストオブジェクトのメソッドがどれであるかを確認する必要があります。 remote:trueを指定すると、リクエストをURLに送信する際にリンクをたどるのではなく、Unobtrusive JavaScript（控えめなJavaScript）ドライバを使ってAjaxリクエストを送信します。ドライバはAjaxリクエストの完了をリッスンし、完了後に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)とlink_to (:confirm)固有のオプションは以下のような方法でのみ使えます。
link_to "Visit Other Site", "http://www.rubyonrails.org/", :confirm => "Are you sure?"
# => <a href="http://www.rubyonrails.org/" data-confirm="Are you sure?"">Visit Other Site</a>
link_to("Destroy", "http://www.example.com", :method => :delete, :confirm => "Are you sure?")
# => <a href='http://www.example.com' rel="nofollow" data-method="delete" data-confirm="Are you sure?">Destroy</a>