[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よりも少なくなっています。

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

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によってリファラの代わりにバック用リンクが使われます。

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

シグネチャ

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 4、Rails 5

Rails 3

Ruby on RailsによるWEBシステム開発、Android/iPhoneアプリ開発、電子書籍配信のことならお任せください この記事を書いた人と働こう! Ruby on Rails の開発なら実績豊富なBPS

この記事の著者

hachi8833

Twitter: @hachi8833、GitHub: @hachi8833 コボラー、ITコンサル、ローカライズ業界、Rails開発を経てTechRachoの編集・記事作成を担当。 これまでにRuby on Rails チュートリアル第2版の半分ほど、Railsガイドの初期翻訳ではほぼすべてを翻訳。その後も折に触れてそれぞれ一部を翻訳。 かと思うと、正規表現の粋を尽くした日本語エラーチェックサービス enno.jpを運営。 実は最近Go言語が好き。 仕事に関係ないすっとこブログ「あけてくれ」は2000年頃から多少の中断をはさんで継続、現在はnote.muに移転。

hachi8833の書いた記事

週刊Railsウォッチ

インフラ

BigBinary記事より

ActiveSupport探訪シリーズ