ドキュメント

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

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

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

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

foo @bar baz

これは、1つの動的部分( `bar` )の周囲に2つの静的部分( `foo ` と ` baz` )で構成されています。テンプレートエンジンは、これらの部分を連結して結果を構築します。実際、クロスサイトスクリプティング攻撃を防ぐために、 `bar` の値は結果の残りの部分に連結される前にエスケープされる場合があります。このエスケーププロセスは、各フォーマットに固有です。たとえば、HTMLの場合、「<」を「&lt;」に変換します。

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

最終的に、テンプレートファイルがHTTPレスポンスの本文として使用されるようにするため、テンプレートレンダリング結果からPlay結果を作成する方法を定義する必要があります。

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

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

静的および動的テンプレート部分を統合するために使用される `raw(text:String):A` および `escape(text:String):A` メソッドを持つ `play.twirl.api.Format [A]` トレイトを実装します。

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

便宜上、Playは `StringBuilder` を使用して結果を構築し、 `play.twirl.api.Content` トレイトを実装する `play.twirl.api.BufferedContent [A]` 抽象クラスを提供します。そのため、PlayはそれをHTTPレスポンス本文としてシリアル化する方法を知っています(詳細については、このページの最後のセクションを参照してください)。

要するに、2つのクラスを作成する必要があります。1つは結果を定義するクラス( `play.twirl.api.Appendable [A]` を実装)、もう1つはテキスト統合プロセスを定義するクラス( `play.twirl.api.Format [A]` を実装)です。たとえば、HTMLフォーマットの定義方法は次のとおりです。

// The `Html` result type. We extend `BufferedContent[Html]` rather than just `Appendable[Html]` so
// Play knows how to make an HTTP result from a `Html` value
class Html(buffer: StringBuilder) extends BufferedContent[Html](buffer) {
  val contentType = MimeTypes.HTML
}

object HtmlFormat extends Format[Html] {
  def raw(text: String): Html = …
  def escape(text: String): Html = …
}

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

テンプレートは、アプリケーションソース全体をコンパイルする直前に、ビルドプロセスによって `.scala` ファイルにコンパイルされます。 `TwirlKeys.templateFormats` キーは、ファイル拡張子とテンプレートフォーマット間のマッピングを定義する `Map [String、String]` 型のsbt設定です。たとえば、HTMLがPlayで標準でサポートされていない場合は、ビルドファイルに次のように記述して、 `.scala.html` ファイルを `play.twirl.api.HtmlFormat` フォーマットに関連付ける必要があります。

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

矢印の右側には、 `play.twirl.api.Format [_]` 型の値の完全修飾名が含まれていることに注意してください。

§テンプレート結果タイプからHTTP結果を作成する方法をPlayに指示する

Playは、暗黙的な `play.api.http.Writeable [A]` 値が存在する任意のタイプ `A` の値に対してHTTPレスポンス本文を記述できます。したがって、必要なのは、テンプレート結果タイプに対してそのような値を定義することだけです。たとえば、HTTPに対してそのような値を定義する方法は次のとおりです。

implicit def writableHttp(implicit codec: Codec): Writeable[Http] =
  Writeable[Http](result => codec.encode(result.body), Some(ContentTypes.HTTP))

**注:**テンプレート結果タイプが `play.twirl.api.BufferedContent` を拡張する場合、定義する必要があるのは
暗黙的な `play.api.http.ContentTypeOf` 値のみです

implicit def contentTypeHttp(implicit codec: Codec): ContentTypeOf[Http] =
  ContentTypeOf[Http](Some(ContentTypes.HTTP))

**次:**フォームの送信と検証


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