Documentation

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 ベースのテンプレートエンジンが含まれています。特徴は以下の通りです:

ノート: テンプレートエンジンは Scala を式言語として使っていますが、これは Java 開発者にとって問題にはなりません。式言語は Java とほとんど同じ物として扱うことができます。

テンプレートは複雑なロジックを記述する場所ではない事を忘れないで下さい。複雑な Scala コードをここに書く必要はありません。ほとんどの場合は以下のようにモデルオブジェクトからデータにアクセスするだけで済むでしょう。

myUser.getProfile().getUsername()

引数の型は後置形式で指定されます。ジェネリックスの型は Java の <> 構文の代わりに [] で指定されます。例えば、 Java での List<String> と同じ意味で List[String] と書きます。

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

§概観

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

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

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

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

@(customer: Customer, orders: List[Order])
 
<h1>Welcome @customer.name!</h1>

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

このテンプレートは次のような static メソッド呼び出しにより、Java コード中のどこからでも呼び出すことができます。

Content html = views.html.Application.index.render(customer, orders);

§文法: 魔法の @

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

Hello @customer.getName()!
       ^^^^^^^^^^^^^^^^^^
          Dynamic code

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

Hello @(customer.getFirstName() + customer.getLastName())!
       ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 
                          Dynamic Code

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

Hello @{val name = customer.getFirstName() + customer.getLastName(); name}!
       ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
                                  Dynamic Code

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

My email is [email protected]@example.com

§テンプレート引数

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

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

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

@(title: String = "Home")

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

@(title:String)(body: Html)

§反復

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

<ul>
@for(p <- products) {
  <li>@p.getName() ([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: models.Product) = {
  @product.getName() ([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.getFirstName() + " " + user.getLastName()) { fullName =>
  <div>Hello @fullName</div>
}

§import 文

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

@(customer: models.Customer, orders: List[models.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 チームによってメンテナンスされているものではありません。 間違いを見つけた場合、このページのソースコードを ここ で確認することができます。 ドキュメントガイドライン を読んで、お気軽にプルリクエストを送ってください。