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

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("username"))
    
    @helper.inputPassword(myForm("password"))
    
}

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

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

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

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

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

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

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

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

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

<dl class="error" id="username_field">
    <dt><label for="username"><label>Username:</label></dt>
    <dd><input type="text" name="username" id="username" 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

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

Play には、TwitterBootstrap 1.4 に対応したフィールドコンストラクタが組み込みで用意されています。 (注意: 2.0.2 は LESS 1.3 と Bootstrap 2.0 をサポートする予定です)

これを利用するためには、単にスコープ内にインポートしてください。

@import helper.twitterBootstrap._

このフィールドコンストラクタは、次のような HTML を生成します。

<div class="clearfix error" id="username_field">
    <label for="username">Username:</label>
    <div class="input">
        <input type="text" name="username" id="username" value="">
        <span class="help-inline">This field is required!, Another error</span>
        <span class="help-block">Required, Another constraint</span> 
    </div>
</div>

また、デフォルトのフィールドコンストラクタと同様のオプションにも対応しています (以下を参照) 。

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

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

@(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>

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

次に、このテンプレートを利用して FieldConstructor を作成します。

object MyHelpers {
    
  implicit val myFields = FieldConstructor(myFieldConstructorTemplate.f)    
    
}

フォームヘルパーにこのフィールドコンストラクタを使わせるため、テンプレートにインポートします。

@import MyHelpers._

@inputText(myForm("username"))

これで、作成したフィールドコンストラクタを使って、テキスト用の input 要素がレンダリングされます。

Note: テンプレート内で FieldConstructor を implicit value として定義することもできます。

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

@inputText(myForm("username"))

§値の繰り返しを扱う

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

val myForm = Form(
  tuple(
    "name" -> text,
    "emails" -> list(email)
  )
)

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

@inputText(myForm("name"))

@repeat(myForm("emails"), min = 1) { emailField =>
    
    @inputText(emailField)
    
}

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

次ページ: JSON