Action View ヘルパー

このガイドの内容:

  • 日付、文字列、数値のフォーマット方法
  • 画像、動画、スタイルシートなどへのリンク方法
  • コンテンツのサニタイズ方法
  • コンテンツのローカライズ方法

1 Action Viewで提供されるヘルパーの概要

WIP: ここに記載されているのはヘルパーの一部です。完全なリストについてはAPIドキュメントを参照してください。

以下は、Action Viewで利用できるヘルパーの簡単な概要のまとめに過ぎません。すべてのヘルパーについて詳しくはAPIドキュメントを参照することをおすすめしますが、本ガイドを最初に読んでおくとよいでしょう。

1.1 AssetTagHelperモジュール

このモジュールは、ビューを「画像」「JavaScriptファイル」「スタイルシート(CSS)」「フィード」などのアセットにリンクするHTMLを生成するメソッド(ヘルパーメソッド)を提供します。

デフォルトでは、現在のホストのpublic/フォルダにあるこれらのアセットにリンクされますが、アプリケーション設定のconfig.asset_hostを設定すれば、アセット専用サーバー上にあるアセットに直接リンクできます。たとえば、アセットホストがassets.example.comの場合は以下のように設定します。

config.asset_host = "assets.example.com"
image_tag("rails.png")
# => <img src="http://assets.example.com/images/rails.png" />

ブラウザやRSSフィードリーダーが「RSS」「Atom」または「JSON」フィードを自動検出するときに利用可能なリンクタグを返します。

auto_discovery_link_tag(:rss, "http://www.example.com/feed.rss", { title: "RSS Feed" })
# => <link rel="alternate" type="application/rss+xml" title="RSS Feed" href="http://www.example.com/feed.rss" />
1.1.2 image_path

app/assets/imagesディレクトリの下に置かれている画像アセットへのパスを算出します。ドキュメントルートを基点とする完全なパスはそのままパススルーされます。内部ではimage_tagを用いて画像パスをビルドします。

image_path("edit.png") # => /assets/edit.png

config.assets.digestをtrueに設定すると、以下のようにフィンガープリントがファイル名に追加されます。

image_path("edit.png")
# => /assets/edit-2d1a2db63fc738690021fedb5a65b68e.png
1.1.3 image_url

app/assets/imagesディレクトリの下に置かれている画像アセットへのURLを算出します。このヘルパーの内部ではimage_pathを呼び出し、現在のホストやアセットホストをマージします。

image_url("edit.png") # => http://www.example.com/assets/edit.png
1.1.4 image_tag

指定されたソースに対応するHTMLのimgタグを返します。ソースには、完全なパスか、アプリのapp/assets/imagesディレクトリの下に存在するファイルを指定できます。

image_tag("icon.png") # => <img src="/assets/icon.png" />
1.1.5 javascript_include_tag

指定されたソースごとにHTMLのscriptタグを返します。app/assets/javascriptsディレクトリの下に存在するJavaScriptファイル名(拡張子.jsはオプションなので、あってもなくてもよい)を渡すことも、ドキュメントルートからの相対的な完全パスを渡すこともできます。

javascript_include_tag "common"
# => <script src="/assets/common.js"></script>
1.1.6 javascript_path

app/assets/javascriptsディレクトリの下に置かれているJavaScriptアセットへのパスを算出します。ソースファイル名に拡張子がない場合は.jsが追加されます。ドキュメントルートを基点とする完全なパスはそのままパススルーされます。このヘルパーの内部ではjavascript_include_tagを用いてスクリプトパスをビルドします。

javascript_path "common" # => /assets/common.js
1.1.7 javascript_url

app/assets/javascriptsディレクトリの下にあるJavaScriptアセットへのURLを算出します。このヘルパーの内部ではjavascript_pathを呼び出し、現在のホストやアセットホストをマージします。

javascript_url "common"
# => http://www.example.com/assets/common.js

引数で指定されたソースに対応するスタイルシートリンクタグを返します。拡張子が指定されていない場合は、自動的に.cssが追加されます。

stylesheet_link_tag "application"
# => <link href="/assets/application.css" rel="stylesheet" />
1.1.9 stylesheet_path

app/assets/stylesheetsディレクトリの下にあるスタイルシートアセットへのパスを算出します。ファイル名に拡張子がない場合は.cssが追加されます。ドキュメントルートを基点とする完全なパスはそのままパススルーされます。このヘルパーの内部ではstylesheet_link_tagを用いてスタイルシートパスをビルドします。

stylesheet_path "application" # => /assets/application.css
1.1.10 stylesheet_url

app/assets/stylesheetsディレクトリの下にあるスタイルシートアセットへのURLを算出します。このヘルパーの内部ではstylesheet_pathを用いてスタイルシートパスをビルドします。

stylesheet_url "application"
# => http://www.example.com/assets/application.css

1.2 AtomFeedHelperモジュール

1.2.1 atom_feed

このヘルパーは、Atomフィードを簡単にビルドできるようにします。以下は完全な利用例です。

config/routes.rb

resources :articles

app/controllers/articles_controller.rb

def index
  @articles = Article.all

  respond_to do |format|
    format.html
    format.atom
  end
end

app/views/articles/index.atom.builder

atom_feed do |feed|
  feed.title("Articles Index")
  feed.updated(@articles.first.created_at)

  @articles.each do |article|
    feed.entry(article) do |entry|
      entry.title(article.title)
      entry.content(article.body, type: 'html')

      entry.author do |author|
        author.name(article.author_name)
      end
    end
  end
end

1.3 BenchmarkHelperモジュール

1.3.1 benchmark

ビューテンプレート内にあるブロックの実行時間を測定して、結果をログに出力できます。コストの高い操作やボトルネックになっている可能性のある部分をブロックで囲むことで、その中での処理時間を読み取れます。

<% benchmark "データファイルの処理" do %>
  <%= expensive_files_operation %>
<% end %>

上のようにすることで、"Process data files (0.34523)" のような情報がログに追加され、コード最適化作業でタイミングを比較できるようになります。

1.4 CacheHelperモジュール

1.4.1 cache

アクション全体やページ全体ではなく、ビューのフラグメントをキャッシュするメソッドです。この手法は、メニューやニューストピックのリスト、静的なHTMLフラグメントなどをキャッシュする場合に便利です。このメソッドは、キャッシュしたいコンテンツを含むブロックを1個受け取ります。詳しくはAbstractController::Caching::Fragmentsを参照してください。

<% cache do %>
  <%= render "shared/footer" %>
<% end %>

1.5 CaptureHelperモジュール

1.5.1 capture

captureは、テンプレートの一部を変数に切り出すのに使えます。切り出したこの変数は、そのテンプレートやレイアウト内のどこでも利用できます。

<% @greeting = capture do %>
  <p>ようこそ!現在の日時: <%= Time.now %></p>
<% end %>

上のように書くことで、キャプチャされた変数を以下のように他のどこでも利用できるようになります。

<html>
  <head>
    <title>ようこそ!</title>
  </head>
  <body>
    <%= @greeting %>
  </body>
</html>
1.5.2 content_for

content_forを呼び出すと、マークアップのブロックを識別子に保存して、後で利用できるようにします。その識別子をyieldの引数に渡すことで、以後他のテンプレートやレイアウト内に保存されたコンテンツを呼び出せるようになります。

たとえば、標準的なアプリケーションレイアウトがあり、特定のページでのみ、他のサイトでは必要とされないJavaScriptが必要になるとします。このような場合は、以下のようにcontent_forを使うことで、他のサイトのコード量を増やさずに特定のページでのみこのJavaScriptコードをインクルードできます。

app/views/layouts/application.html.erb

<html>
  <head>
    <title>ようこそ!</title>
    <%= yield :special_script %>
  </head>
  <body>
    <p>ようこそ!現在の日時:  <%= Time.now %></p>
  </body>
</html>

app/views/articles/special.html.erb

<p>ここは特別なページ</p>

<% content_for :special_script do %>
  <script>alert('こんにちは!')</script>
<% end %>

1.6 DateHelperモジュール

1.6.1 distance_of_time_in_words

2つの「Timeオブジェクト」「Dateオブジェクト」「整数(秒)」同士のおおよそのインターバル(時刻と時刻の間隔)を英文で出力します。単位を詳細にしたい場合はinclude_secondsをtrueに設定します。

distance_of_time_in_words(Time.now, Time.now + 15.seconds)
# => less than a minute
distance_of_time_in_words(Time.now, Time.now + 15.seconds, include_seconds: true)
# => less than 20 seconds
1.6.2 time_ago_in_words

distance_of_time_in_wordsと同様ですが、to_time(終端時刻)がTime.now`に固定されている点が異なります。

time_ago_in_words(3.minutes.from_now) # => 3 minutes

1.7 DebugHelperモジュール

オブジェクトをYAML形式でダンプしたpreタグを返します。これにより、オブジェクトを見やすい形で取り出せます。

my_hash = { 'first' => 1, 'second' => 'two', 'third' => [1,2,3] }
debug(my_hash)
<pre class='debug_dump'>---
first: 1
second: two
third:
- 1
- 2
- 3
</pre>

1.8 FormHelperモジュール

フォームヘルパーは、モデルに基づいてフォームを作成する一連のメソッドを提供します。これらを用いることで、標準のHTML要素を用いるよりもモデルでの作業の負担を大きく軽減できるよう設計されています。フォームペルパーは、フォーム用のHTMLを生成し、ユーザー入力の種類(テキストフィールド、パスワードフィールド、ドロップダウンボックスなど)に応じたメソッドを提供します。フォームが(ユーザーが送信ボタンを押す、JavaScriptでform.submitを呼び出すなどの方法で)送信されると、フォームへの入力がparamsオブジェクトにまとめられてコントローラに返されます。

フォームヘルパーについて詳しくは、ガイドのAction View フォームヘルパーを参照してください。

1.9 JavaScriptHelperモジュール

ビューでJavaScriptを操作するための機能を提供します。

1.9.1 escape_javascript

JavaScriptセグメントでキャリッジリターンや一重引用符や二重引用符をエスケープします。

1.9.2 javascript_tag

渡されたコードをJavaScriptタグでラップして返します。

javascript_tag "alert('All is good')"
<script>
//<![CDATA[
alert('All is good')
//]]>
</script>

1.10 NumberHelperモジュール

数値を書式付き文字列に変換するメソッドを提供します。「電話番号」「通貨」「パーセント」「精度」「桁区切り記号の位置」「ファイルサイズ」用のメソッドが提供されます。

1.10.1 number_to_currency

数値を通貨表示の文字列にフォーマットします($13.65など)。

number_to_currency(1234567890.50) # => $1,234,567,890.50
1.10.2 number_to_human

数値を、人間が読みやすい形式(数詞を追加)で近似表示します。数値が非常に大きくなる可能性がある場合に便利です。

number_to_human(1234)    # => 1.23 Thousand
number_to_human(1234567) # => 1.23 Million
1.10.3 number_to_human_size

バイト単位の数値を、KBやMBなどのわかりやすい単位でフォーマットします。ファイルサイズを表示する場合に便利です。

number_to_human_size(1234)    # => 1.21 KB
number_to_human_size(1234567) # => 1.18 MB
1.10.4 number_to_percentage

数値をパーセント形式の文字列にフォーマットします。

number_to_percentage(100, precision: 0) # => 100%
1.10.5 number_to_phone

数値を電話番号形式にフォーマットします(デフォルトは米国の電話番号形式)。

number_to_phone(1235551234) # => 123-555-1234
1.10.6 number_with_delimiter

数値を区切り文字で3桁ずつグループ化します。

number_with_delimiter(12345678) # => 12,345,678
1.10.7 number_with_precision

数値の小数点以下の精度(表示を丸める位置)をprecisionで指定できます(デフォルトは3)。

number_with_precision(111.2345)               # => 111.235
number_with_precision(111.2345, precision: 2) # => 111.23

1.11 SanitizeHelperモジュール

SanitizeHelperモジュールは、望ましくないHTML要素のテキストをスクラブ(除去)する一連のメソッドを提供します。

1.11.1 sanitize

このsanitizeヘルパーは、すべてのタグをHTMLエンコードし、許可されていない属性をすべて削除します。

sanitize @article.body

:attributesオプションと:tagsオプションのいずれかを渡すと、オプションで指定した属性またはタグだけが許可されます(つまり除去されません)。それ以外の属性やタグは許可されません(つまり除去されます)。

sanitize @article.body, tags: %w(table tr td), attributes: %w(id class style)

よく使うオプションをデフォルト化するには、以下のようにアプリケーション設定でオプションをデフォルトに追加します。以下はtable関連のタグを追加した場合の例です。

class Application < Rails::Application
  config.action_view.sanitized_allowed_tags = 'table', 'tr', 'td'
end
1.11.2 sanitize_css(style)

CSSコードのブロックをサニタイズします。

テキスト内のリンクタグを削除し、リンクテキストだけを残します。

strip_links('<a href="https://rubyonrails.org">Ruby on Rails</a>')
# => Ruby on Rails
strip_links('emails to <a href="mailto:me@email.com">me@email.com</a>.')
# => emails to me@email.com.
strip_links('Blog: <a href="http://myblog.com/">Visit</a>.')
# => Blog: Visit.
1.11.4 strip_tags(html)

HTMLからすべてのHTMLタグをストリップします(コメントもストリップされます)。 この機能はrails-html-sanitizer gemによるものです。

strip_tags("Strip <i>these</i> tags!")
# => Strip these tags!
strip_tags("<b>Bold</b> no more!  <a href='more.html'>See more</a>")
# => Bold no more!  See more

1.12 UrlHelper

リンクを作成するメソッドや、ルーティングサブシステムに応じたURLを取得するメソッドを提供します。

1.12.1 url_for

optionsで渡されたセットに対応するURLを返します。

1.12.1.1 例
url_for @profile
# => /profiles/1

url_for [ @hotel, @booking, page: 2, line: 3 ]
# => /hotels/1/bookings/1?line=3&page=2

背後のurl_forで得られたURLへのリンクを生成します。主な用途は、RESTfulなリソースリンクの作成です。たとえばlink_toにモデルを渡すと以下のようにリンクが生成されます。

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

以下のERBのようにブロックを渡すことで、リンク文字列をnameパラメータに応じて変えることもできます。

<%= 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>

詳しくはAPIドキュメントを参照してください。

1.12.3 button_to

渡されたURLに送信するフォームを生成します。このフォームには、nameの値がボタン名となる送信ボタンが表示されます。

1.12.3.1 例
<%= button_to "Sign in", sign_in_path %>

上は以下のようなフォームを生成します。

<form method="post" action="/sessions" class="button_to">
  <input type="submit" value="Sign in" />
</form>

詳しくはAPIドキュメントを参照してください。

1.13 CsrfHelper

"csrf-param"メタタグと"csrf-token"メタタグに、CSRF保護用のパラメータとトークンを入れて返します。

<%= csrf_meta_tags %>

通常のフォームではhiddenフィールドが生成されるので、これらのタグは使われません。詳しくはRailsセキュリティガイドを参照してください。

フィードバックについて

Railsガイドは GitHub の yasslab/railsguides.jp で管理・公開されております。本ガイドを読んで気になる文章や間違ったコードを見かけたら、気軽に Pull Request を出して頂けると嬉しいです。Pull Request の送り方については GitHub の README をご参照ください。

原著における間違いを見つけたら『Rails のドキュメントに貢献する』を参考にしながらぜひ Rails コミュニティに貢献してみてください 🛠💨✨

本ガイドの品質向上に向けて、皆さまのご協力が得られれば嬉しいです。よろしくお願いします。

YassLab 株式会社
https://yasslab.jp/

支援・協賛

Railsガイドは下記のサポーターから継続的な支援を受けています。Railsガイドへの支援・協賛にご興味あれば info@yasslab.jp までお問い合わせください。

  1. Star
  2. このエントリーをはてなブックマークに追加