You are viewing the documentation for the 2.3.x release series. The latest stable release series is 2.4.x.

§テンプレートエンジン

§Scala ベースのタイプセーフなテンプレートエンジン

Play には Twirl という、ASP.NET Razor に影響を受けた強力な Scala ベースのテンプレートエンジンが含まれています。特徴は以下の通りです:

簡潔さ、表現力、書きやすさを重視: このテンプレートエンジンを利用すると、1 ファイルあたりに必要な文字数やタイプ量が最小化され、サクサクとコーディングができます。よくあるテンプレートの文法とは異なり、サーバで実行されるコードブロックを HTML 中に明示する必要がありませんので、コーディングを妨げることがありません。パーサが優秀なので、コードブロックと HTML 部分を自動的に区別することができるのです。これにより、簡潔さ、表現力、書きやすさに優れた文法になっています。
学習コストが低い: テンプレート文法は最小限になっているので、すぐにテンプレートを書き始めることができます。簡潔な Scala の構文を使うことができ、また HTML についての知識がそのまま応用できます。
新しい言語ではありません: Play framework の開発者は、新しい言語を作ることを意識的に避けました。その代わり、Scala 版のフレームワークの利用者が、テンプレートのマークアップ言語を拡張できるようにしました。
エディタを選ばない: 特別なツールがなくても、ただのテキストエディタで書くことができます。

テンプレートはコンパイルされて、エラーはブラウザ上で確認することができます。

§概観

Play Scala テンプレートは Scala のコードブロックを少し含む以外は、ただのテキストファイルです。したがって、HTML, XML, CSV などあらゆるテキストベースのフォーマットを生成するために利用できます。

テンプレートシステムは HTML に慣れた人に向けて設計されているので、フロントエンドエンジニアでも簡単に書くことができます。

テンプレートは簡単な命名規則に従って、ただの Scala の関数としてコンパイルされます。views/Application/index.scala.html というテンプレートファイルを作成すると、コンパイルにより views.html.Application.index という apply() メソッドを持つクラスが生成されます。

例えば、次のようなシンプルなテンプレートを作成します。

@(customer: Customer, orders: List[Order])

<h1>Welcome @customer.name!</h1>

<ul>
@for(order <- orders) {
  <li>@order.title</li>
}
</ul>

このテンプレートは、いつもクラスのメソッドを呼び出しているように、あらゆる Scala コードから呼び出すことができます:

val content = views.html.Application.index(c, o)

§文法: 魔法の `@`

Scala テンプレートでは @ という文字が唯一の特殊文字です。この文字はテンプレート中に登場すると動的コードの開始として認識されます。コードブロックの終わりはコンパイラにより自動的に推論されるため、明示的に閉じる必要がありません。

Hello @customer.name!
       ^^^^^^^^^^^^^
       Dynamic code

テンプレートエンジンがコードを解析してコードブロックの終わりを自動的に認識するため、この文法では単純な Scala 文しかサポートされません。複数のトークンにまたがるようなコードを挿入したい場合は、その範囲を括弧で明示することができます。

Hello @(customer.firstName + customer.lastName)!
       ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
                    Dynamic Code

同様に、複数の文を含むコードを挿入したい場合は、中括弧を利用することができます。

Hello @{val name = customer.firstName + customer.lastName; name}!
       ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
                             Dynamic Code

@ は特殊文字ですが、これをエスケープしたいときは @@ と書きます。

My email is bob@@example.com

§テンプレート引数

テンプレートは関数のように引数をとります。引数はテンプレートの先頭行で宣言します。

@(customer: Customer, orders: List[Order])

引数のデフォルト値を設定することもできます。

@(title: String = "Home")

複数の引数グループを作成することもできます。

@(title: String)(body: Html)

§反復

for キーワードをよくある形で使うことができます。

<ul>
@for(p <- products) {
  <li>@p.name ([email protected])</li>
}
</ul>

ノート: 次の行に式が続いていることを示すために、for と同じ行に { を置いていることを確認してください。

§If ブロック

If ブロックについても特別なことはなにもありません。Scala の if 式がそのまま使えます。

@if(items.isEmpty) {
  <h1>Nothing to display</h1>
} else {
  <h1>@items.size items!</h1>
}

§再利用可能なブロックの宣言

次のように、再利用可能なコードブロックを作成することができます。

@display(product: Product) = {
  @product.name ([email protected])
}

<ul>
@for(product <- products) {
  @display(product)
}
</ul>

再利用可能な Scala のコードブロックを宣言することもできます。

@title(text: String) = @{
  text.split(' ').map(_.capitalize).mkString(" ")
}

<h1>@title("hello world")</h1>

ノート: このようにコードブロックをテンプレートで宣言すると便利なこともありますが、テンプレートは込み入ったロジックを置く場所としては適切でないことを覚えておいてください。このようなコードは、(必要であれば views パッケージ配下に配置することもできる) Scala クラスに切り出すと良いことが多いです。

慣習として、名前が implicit で始まる再利用可能なブロックは、implicit として扱われます。

@implicitFieldConstructor = @{ MyFieldConstructor() }

§再利用可能な値の宣言

defining ヘルパ関数を使って、特定のスコープ内でのみ有効な値を定義することができます。

@defining(user.firstName + " " + user.lastName) { fullName =>
  <div>Hello @fullName</div>
}

§import 文

テンプレート (またはサブテンプレート) の冒頭で、任意のパッケージやオブジェクトなどを import することができます。

@(customer: Customer, orders: List[Order])

@import utils._

...

絶対パスでパッケージを指定をしたい場合は、import 文で先頭に _root_ を指定します。

@import _root_.company.product.core._

全てのテンプレートで必要な共通の import 文がある場合は、 build.sbt で指定することができます。

TwirlKeys.templateImports += "org.abc.backend._"

§コメント

@* *@ を利用して、サーバーサイドのブロックコメントを書くことができます。

@*********************
* This is a comment *
*********************@

テンプレートの先頭行にコメントを記述すると、Scala API doc にドキュメントが出力されます。

@*************************************
 * Home page.                        *
 *                                   *
 * @param msg The message to display *
 *************************************@
@(msg: String)

<h1>@msg</h1>

§エスケープ

デフォルトでは、動的なコンテンツ部分はテンプレートの型 (HTML や XML など) に応じてエスケープされます。エスケープなしでコンテンツを出力したい場合、コンテンツをテンプレートのコンテンツタイプでラップしてください。

例えば、生の HTML を出力する場合は次のように記述します。

<p>
  @Html(article.content)
</p>

Next: よくある使い方

このドキュメントの翻訳は Play チームによってメンテナンスされているものではありません。間違いを見つけた場合、このページのソースコードをここで確認することができます。ドキュメントガイドラインを読んで、お気軽にプルリクエストを送ってください。