Documentation

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

§テンプレートエンジンに対するカスタムフォーマットのサポートの追加

組み込みのテンプレートエンジンは一般的なテンプレートフォーマット (HTML、XML、等) をサポートしていますが、必要であれば独自のフォーマットのサポートを簡単に追加する事ができます。このページではカスタムフォーマットをサポートする為に必要なステップをまとめています。

§テンプレートプロセスの概要

テンプレートエンジンはテンプレートの静的および動的な部品を結合する事でビルドします。例えば以下のテンプレートを考えてみて下さい:

foo @bar baz

上記のテンプレートは一つの動的な部品 (bar) およびその周囲の二つの静的な部品 (foo および baz) から構成されています。テンプレートエンジンはこれらの部品を結合する事で結果をビルドします。実際には、クロスサイトスクリプティング攻撃を防ぐ為、他の部品と結合される前に bar の値をエスケープすることができます。このエスケーププロセスはフォーマット毎に特有となります: 例えば、 HTML の場合は「<」を「&lt;」に変換したくなるでしょう。

テンプレートエンジンはどのようにしてテンプレートファイルに対応するフォーマットを知る事が出来るのでしょうか? 拡張子を見ています: 例えば、 .scala.html で終わる場合は、HTML フォーマットとファイルを紐付けます。

まとめると、独自のテンプレートフォーマットをサポートするには、以下のステップを行う必要があります:

§フォーマットを実装する

play.templates.Format<A> インタフェースを実装しましょう。このインタフェースは A raw(String text) および A escape(String text) メソッドがあり、それぞれ静的および動的なテンプレートの部品を統合する為に使われます。

フォーマットの A 型パラメータは、例えば HTML のテンプレートには Html といったように、テンプレートのレンダリング結果の型を定義します。この型は play.templates.Appendable<A> のサブタイプである必要があり、各部品をどうやって結合するかを定義します。

利便性のため、 Play は play.api.templates.BufferedContent<A> 抽象クラスを提供します。このクラスは結果をビルドする為に play.templates.Appendable<A> を StringBuilder を使って実装していて、また HTTP のレスポンスボディにシリアライズする方法を Play に知らせるために play.mvc.Content インタフェースを実装しています。

つまり、二つのクラスを書く必要があります: 一つは (play.templates.Appendable<A> を実装する事で) 結果を定義したクラスで、もう一つは (play.templates.Format<A> を実装する事で) テキストの統合プロセスを定義したクラスです。例えば、 HTML フォーマットを定義するには以下のようにします:

public class Html extends BufferedContent<Html> {
  public Html(StringBuilder buffer) {
    super(buffer);
  }
  String contentType() {
    return "text/html";
  }
}

public class HtmlFormat implements Format<Html> {
  Html raw(String text: String) { … }
  Html escape(String text) { … }
  public static final HtmlFormat instance = new HtmlFormat(); // ビルドプロセスにおいてフォーマットに対する static な参照が必要となります (次のセクション参照)
}

§ファイル拡張子をフォーマットと関連づける

テンプレートは、ビルドプロセスでアプリケーションのソース全体をコンパイルする直前に .scala ファイルにコンパイルされます。 sbt.PlayKeys.templatesTypes キーは Map[String, String] 型の sbt 設定で、ファイル拡張子とテンプレートフォーマットのマッピングを定義しています。例えば、もし独自の HTML 形式の実装を使いたい場合、以下のようにビルドファイルに書く事で .scala.html を独自の my.HtmlFormat フォーマットに関連づける必要があります:

templatesTypes += ("html" -> "my.HtmlFormat.instance")

矢印の右側には play.templates.Format<?> 型の静的な値への完全修飾名が含まれている事に注意して下さい。

次: HTTP フォーム送信とバリデーション

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