§テンプレートエンジンへのカスタム形式のサポートの追加

組み込みのテンプレートエンジンは、一般的なテンプレート形式（HTML、XMLなど）をサポートしていますが、必要に応じて独自の形式のサポートを簡単に追加できます。このページでは、カスタム形式をサポートするために従うべき手順をまとています。

§テンプレート処理の概要

テンプレートエンジンは、テンプレートの静的および動的なコンテンツ部分を連結することで結果を構築します。たとえば、次のテンプレートを考えてみましょう。

foo @bar baz

これは、1つの動的な部分（bar）の周りに2つの静的な部分（foo と baz）で構成されています。テンプレートエンジンは、これらの部分を連結して結果を構築します。実際には、クロスサイトスクリプティング攻撃を防ぐために、barの値は、結果の残りの部分に連結される前にエスケープできます。このエスケープ処理は、各形式に固有です。たとえば、HTMLの場合、「<」を「<」に変換する必要があります。

テンプレートエンジンは、どの形式がテンプレートファイルに対応するかをどのように知るのでしょうか？それは拡張子を見て判断します。たとえば、.scala.htmlで終わる場合は、HTML形式をファイルに関連付けます。

要約すると、独自のテンプレート形式をサポートするには、次の手順を実行する必要があります。

形式のテキスト統合処理を実装します。
ファイル拡張子を形式に関連付けます。

§形式の実装

play.twirl.api.Format<A>インターフェースを実装します。これには、静的および動的なテンプレート部分をそれぞれ統合するために使用されるA raw(String text)メソッドとA escape(String text)メソッドがあります。

形式の型パラメータAは、テンプレートレンダリングの結果の型を定義します。たとえば、HTMLテンプレートの場合はHtmlです。この型は、部分を連結する方法を定義するplay.twirl.api.Appendable<A>トレイトのサブタイプである必要があります。

便宜上、Playは、結果を構築するためにStringBuilderを使用し、play.twirl.api.Appendable<A>を実装するplay.twirl.api.BufferedContent<A>抽象クラスを提供します。また、play.twirl.api.Contentインターフェースを実装しているため、PlayはHTTPレスポンスボディとしてシリアル化する方法を認識しています。

要するに、2つのクラスを作成する必要があります。1つは結果を定義し（play.twirl.api.Appendable<A>を実装）、もう1つはテキスト統合プロセスを定義します（play.twirl.api.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(); // The build process needs a static reference to the format (see the next section)
}

§ファイル拡張子を形式に関連付ける

テンプレートは、アプリケーションソース全体をコンパイルする直前に、ビルドプロセスによって.scalaファイルにコンパイルされます。TwirlKeys.templateFormatsキーは、ファイル拡張子とテンプレート形式間のマッピングを定義するMap[String, String]型のsbt設定です。たとえば、Playに独自のHTML形式の実装を使用させたい場合は、ビルドファイルに次のように記述して、.scala.htmlファイルをカスタムのmy.HtmlFormat形式に関連付ける必要があります。

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

矢印の右側には、play.twirl.api.Format<?>型の静的な値の完全修飾名が含まれていることに注意してください。

次へ： フォームの送信とバリデーション

このドキュメントにエラーを見つけましたか？このページのソースコードはこちらにあります。ドキュメントのガイドラインを読んだ後、プルリクエストを自由にご投稿ください。質問や共有するアドバイスがありますか？コミュニティフォーラムにアクセスして、コミュニティとの会話を始めてください。