---
title: Custom format
robots: noindex, noarchive
---

# Adding support for a custom format to the template engine

テンプレートエンジンにカスタム形式のサポートを追加する

The built-in template engine supports common template formats (HTML, XML, etc.) but you can easily add support for your own formats, if needed. This page summarizes the steps to follow to support a custom format.

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

# Overview of the templating process
テンプレート作成プロセスの概要

The template engine builds its result by appending static and dynamic content parts of a template. Consider for instance the following template:

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

foo @bar baz

It consists in two static parts (foo and baz) around one dynamic part (bar). The template engine concatenates these parts together to build its result. Actually, in order to prevent cross-site scripting attacks, the value of bar can be escaped before being concatenated to the rest of the result. This escaping process is specific to each format: e.g. in the case of HTML you want to transform “<” into “&lt;”.

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

How does the template engine know which format correspond to a template file? It looks at its extension: e.g. if it ends with .scala.html it associates the HTML format to the file.

テンプレートエンジンは、テンプレートファイルに対応する形式をどのように知っていますか？拡張子を確認します（例： .scala.htmlで終わる場合、HTML形式をファイルに関連付けます。

Finally, you usually want your template files to be used as the body of your HTTP responses, so you have to define how to make a Play result from a template rendering result.

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

In summary, to support your own template format you need to perform the following steps:

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

Implement the text integration process for the format ;
フォーマットのテキスト統合プロセスを実装します。

Associate a file extension to the format ;
ファイル拡張子をフォーマットに関連付けます。

Eventually tell Play how to send the result of a template rendering as an HTTP response body.

最終的には、テンプレートレンダリングの結果をHTTPレスポンスボディとして送信する方法をPlayに伝えます。

# Implement a format
フォーマットを実装する

Implement the play.twirl.api.Format[A] trait that has the methods raw(text: String): A and escape(text: String): A that will be used to integrate static and dynamic template parts, respectively.

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

The type parameter A of the format defines the result type of the template rendering, e.g. Html for a HTML template. This type must be a subtype of the play.twirl.api.Appendable[A] trait that defines how to concatenates parts together.

フォーマットの型パラメータAは、テンプレートレンダリングの結果の型を定義する。 HTMLテンプレート用のHTML。このタイプは、パートを連結する方法を定義するplay.twirl.api.Appendable[A] traitのサブタイプでなければなりません。

For convenience, Play provides a play.twirl.api.BufferedContent[A] abstract class that implements play.twirl.api.Appendable[A] using a StringBuilder to build its result and that implements the play.twirl.api.Content trait so Play knows how to serialize it as an HTTP response body (see the last section of this page for details).

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

In short, you need to write to classes: one defining the result (implementing play.twirl.api.Appendable[A]) and one defining the text integration process (implementing play.twirl.api.Format[A]). For instance, here is how the HTML format is defined:

つまり、結果を定義する（play.twirl.api.Appendable[A]を実装する）クラスと、テキスト統合プロセスを定義するクラス（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 = …
}

# Associate a file extension to the format
ファイル拡張子をフォーマットに関連付ける

The templates are compiled into a .scala files by the build process just before compiling the whole application sources. The TwirlKeys.templateFormats key is a sbt setting of type Map[String, String] defining the mapping between file extensions and template formats. For instance, if HTML was not supported out of the box by Play, you would have to write the following in your build file to associate the .scala.html files to the play.twirl.api.HtmlFormat format:

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

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

Note that the right side of the arrow contains the fully qualified name of a value of type play.twirl.api.Format[_].

矢印の右側には、play.twirl.api.Format [_]型の値の完全修飾名が含まれています。

# Tell Play how to make an HTTP result from a template result type
テンプレート結果のtypeからHTTPの結果を作る方法をPlayに教えてください

Play can write an HTTP response body for any value of type A for which it exists an implicit play.api.http.Writeable[A] value. So all you need is to define such a value for your template result type. For instance, here is how to define such a value for HTTP:

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))
Note: if your template result type extends play.twirl.api.BufferedContent you only need to define an
implicit play.api.http.ContentTypeOf value:

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