§フォームテンプレートヘルパーの利用

Play には HTML テンプレート中にフォームやフィールドを生成するためのヘルパー関数が用意されています。

§<form> タグの作成

まず、 <form> タグを作成するヘルパーがあります。これは、 action と method タグパラメータを引数に渡したリバースルートに基づいて設定する、かなりシンプルなヘルパーです。

@helper.form(action = routes.Application.submit()) {

}

生成される HTML に追加されるその他のパラメータを渡すこともできます。

@helper.form(action = routes.Application.submit(), 'id -> "myForm") {

}

§<input> 要素のレンダリング

views.html.helper パッケージには input 要素のヘルパーがいくつか用意されています。これらヘルパーにフォームフィールドのオブジェクトを渡すと、それに対応した HTML フォームコントロールが表示されます。コントロールには値がセットされ、制約、エラー情報も付与されます。

@(myForm: Form[User])

@helper.form(action = routes.Application.submit()) {

    @helper.inputText(myForm("email"))

    @helper.inputPassword(myForm("password"))

}

form ヘルパーと同様に、生成される HTML に追加されるその他のパラメータを指定することができます。

@helper.inputText(myForm("email"), 'id -> "email", 'size -> 30)

ノート: _ という文字以外で始まるパラメータは全て生成される HTML に追加されます。アンダースコアで始まるパラメータは、フィールドコンストラクタの引数（後で説明します）のために予約されています。

§input 要素を自由に生成する

生成される HTML をもっと細かくコントロールしたい時のために、より汎用的な input ヘルパーも用意されています。

@helper.input(myForm("email")) { (id, name, value, args) =>
    <input type="date" name="@name" id="@id" @toHtmlArgs(args)>
}

§フィールドコンストラクタ

フィールドをレンダリングする際、単に <input> タグを出力するだけでなく、<label> タグや、利用している CSS フレームワークによってはフィールドを修飾する他の HTML 要素を出力しなければならないこともあります。

全ての input ヘルパーはこの目的のために FieldConstructor という暗黙的な引数をとります。デフォルト (フィールドコンストラクタがスコープ内に存在しない場合に使われる) では、次のような HTML が生成されます。

<dl class="error" id="email_field">
    <dt><label for="email">Email:</label></dt>
    <dd><input type="text" name="email" id="email" value=""></dd>
    <dd class="error">This field is required!</dd>
    <dd class="error">Another error</dd>
    <dd class="info">Required</dd>
    <dd class="info">Another constraint</dd>
</dl>

デフォルトのフィールドコンストラクタは、input ヘルパーの引数に渡すことができる以下の追加オプションに対応しています。

'_label -> "Custom label"
'_id -> "idForTheTopDlElement"
'_help -> "Custom help"
'_showConstraints -> false
'_error -> "Force an error"
'_showErrors -> false

§フィールドコンストラクタを自作する

独自のフィールドコンストラクタが必要になることもあります。まず以下のようなテンプレートを作成します。

@(elements: helper.FieldElements)

<div class="@if(elements.hasErrors) {error}">
<label for="@elements.id">@elements.label</label>
<div class="input">
    @elements.input
    <span class="errors">@elements.errors.mkString(", ")</span>
    <span class="help">@elements.infos.mkString(", ")</span>
</div>
</div>

これを myFieldConstructorTemplate.scala.html という名前で views/ に保存します。

Note: これはただのサンプルです。必要であれば、もっと複雑なテンプレートを作成することもできます。また、@elements.field と書くと元のフィールドを参照することができます。

次に、以下のように FieldConstructor を作成します。

@implicitField = @{ FieldConstructor(myFieldConstructorTemplate.f) }

@inputText(myForm("email"))

§値の繰り返しを扱う

最後に紹介するヘルパーは、値の繰り返しに関する input 要素を生成するものです。まず、次のようなフォームを定義したとします。

public class UserForm {
    public String name;
    public List<String> emails;
}

次に、フォームにの emails フィールドのために沢山の input 要素を生成する必要があります。ここで repeat ヘルパーが役に立ちます。

@helper.inputText(userForm("name"))

@helper.repeat(userForm("emails"), min = 1) { emailField =>

    @helper.inputText(emailField)

}

フィールドが空の場合であっても、min パラメータに指定した個数の input 要素が生成されます。

Next: CSRF 対策

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