先生と生徒の会話形式で理解しよう

生徒

「Play Frameworkでユーザーが入力するお問い合わせフォームや登録画面を作りたいのですが、ビューではどのように記述すればいいですか？」

先生

「Play FrameworkのビューエンジンであるTwirl（トワール）では、HTMLのフォームタグをそのまま書くこともできますし、フレームワークが提供する便利なヘルパー機能を使ってスマートに書くこともできるんですよ。」

生徒

「普通のHTMLと何が違うんですか？」

先生

「一番のメリットは、コントローラ側で定義したJavaのフォームオブジェクトと簡単に連携できる点です。それでは、具体的な作り方を順番に見ていきましょう！」

1. フォーム表示の基本概念

Webアプリケーションにおいて、ユーザーからの入力を受け取るフォーム（Form）は非常に重要な要素です。 Play Frameworkのビュー（Twirlテンプレート）では、Javaのコントローラから渡されたフォーム情報を元に、入力項目やエラーメッセージを動的に表示します。

一般的な開発の流れとしては、まずJava側で「入力項目をまとめたクラス」を用意し、それをビューに渡して表示させます。これにより、入力値の自動保持やバリデーション（入力チェック）結果の表示がスムーズに行えるようになります。

2. Javaでのフォーム用データクラスの準備

ビューでフォームを表示する前に、まずはJava側で受け皿となるデータクラスを作成します。初心者の方でも分かりやすいように、シンプルな「ユーザー登録」を例に考えてみましょう。


package models;

import play.data.validation.Constraints;

public class UserFormData {
    @Constraints.Required
    public String name;

    @Constraints.Email
    public String email;

    public String comment;
}

このクラスのフィールド（nameやemail）が、HTMLフォーム内の各入力項目（inputタグ）に対応することになります。 @Constraints.Required などの注釈を付けることで、必須入力などのルールを定義できます。

3. コントローラでフォームをビューに渡す

次に、Javaのコントローラでこのフォームオブジェクトを初期化し、ビューへレンダリングします。 Play Frameworkでは FormFactory というツールを使って、先ほど作ったクラスをフォーム形式に変換します。


package controllers;

import play.mvc.*;
import play.data.Form;
import play.data.FormFactory;
import javax.inject.Inject;
import models.UserFormData;

public class UserController extends Controller {
    @Inject
    FormFactory formFactory;

    public Result showForm() {
        // 空のフォームオブジェクトを作成
        Form<UserFormData> userForm = formFactory.form(UserFormData.class);
        // ビューにフォームを渡す
        return ok(views.html.userView.render(userForm));
    }
}

render(userForm) とすることで、テンプレート側でこのフォーム情報を利用できるようになります。

4. Twirlビューでのフォーム記述方法

いよいよ本題のビュー（テンプレート）側の記述です。ファイル名の先頭で、コントローラから渡された Form 型の引数を受け取る宣言をします。


@(userForm: Form[models.UserFormData])

@import helper._

<!DOCTYPE html>
<html>
<head>
    <title>ユーザー登録フォーム</title>
    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/css/bootstrap.min.css">
</head>
<body class="container mt-5">
    <h2 class="mb-4">ユーザー情報の入力</h2>

    @helper.form(action = routes.UserController.showForm()) {
        <div class="mb-3">
            @helper.inputText(userForm("name"), '_label -> "お名前", 'class -> "form-control")
        </div>
        <div class="mb-3">
            @helper.inputText(userForm("email"), '_label -> "メールアドレス", 'type -> "email", 'class -> "form-control")
        </div>
        <div class="mb-3">
            @helper.textarea(userForm("comment"), '_label -> "備考", 'class -> "form-control")
        </div>
        <button type="submit" class="btn btn-primary">送信する</button>
    }
</body>
</html>

@helper.form は、適切な action 属性と method="POST" 属性を持つformタグを自動生成してくれます。また、@helper.inputText を使うと、ラベルや入力エラー時の表示もまとめて処理してくれるため、非常に便利です。

5. フォームヘルパーが生成するHTMLの構造

Twirlのヘルパーを使うと、実際にブラウザには以下のようなHTMLが出力されます。手書きで書く手間が省けるだけでなく、BootstrapなどのCSSフレームワークと相性の良い構造になっています。


<form action="/user/show" method="POST">
    <dl id="name_field">
        <dt><label for="name">お名前</label></dt>
        <dd><input type="text" id="name" name="name" value="" class="form-control"></dd>
    </dl>
    <!-- 他の項目も続く -->
</form>

このように、dl, dt, dd タグを使って構成されるのがPlayのデフォルトの挙動です。もしデザインをより細かくカスタマイズしたい場合は、独自のフィールドコンストラクターを作成することも可能ですが、まずはこの基本形を覚えるのが近道です。

6. CSRF対策（セキュリティ設定）

Play Frameworkでは、セキュリティ対策としてCSRF（クロスサイトリクエストフォージェリ）攻撃を防ぐ仕組みが標準で備わっています。フォームを送信する場合、この設定を有効にしていると、フォーム内にトークン（秘密の合言葉）を埋め込む必要があります。

Twirlのヘルパーを使っている場合、以下の一行をフォーム内に追加するだけで対応完了です。


@helper.form(action = routes.UserController.submit()) {
    @CSRF.formField
    @* ... 入力項目 ... *@
}

これだけで、目に見えない hidden 属性の入力項目が追加され、安全にデータを送信できるようになります。

7. セレクトボックスやラジオボタンの表示

テキスト入力以外にも、選択肢から選ぶセレクトボックスやラジオボタンも頻繁に使われます。これらも専用のヘルパーで簡単に記述できます。


@helper.select(
    userForm("gender"),
    options = Seq("M" -> "男性", "F" -> "女性"),
    '_label -> "性別",
    '_default -> "-- 選択してください --"
)

@helper.inputRadioGroup(
    userForm("pref"),
    options = Seq("1" -> "東京", "2" -> "大阪"),
    '_label -> "お住まい"
)

options には、Javaの Map や List を渡すこともできるため、データベースから取得したマスターデータをそのまま選択肢に反映させることが可能です。

8. エラーメッセージの表示制御

ユーザーが誤った入力をした際、フォームヘルパーは自動的にエラーメッセージを表示してくれます。しかし、時には特定の位置にまとめてエラーを出したいこともあります。

そのような場合は、userForm.hasErrors や userForm.errors を使うことで、独自のエラー表示エリアを作ることができます。


@if(userForm.hasErrors) {
    <div class="alert alert-danger">
        入力内容に不備があります。修正してください。
    </div>
}

このように、Java側でのバリデーション結果をビューで柔軟に扱えるのが、Play Frameworkの大きな魅力です。

9. 静的なHTMLとヘルパーの使い分け

「必ずしもヘルパーを使わないといけないの？」という疑問を持つ方もいるでしょう。結論から言えば、普通のHTMLタグ（<input>など）を書いても全く問題ありません。

特にデザインが非常に複雑で、ヘルパーが生成するHTML（dlタグなど）が邪魔になる場合は、手書きの方が制御しやすいこともあります。その際は、name 属性をJavaのクラスのフィールド名と一致させることだけ忘れないようにしましょう。そうすれば、送信されたデータは正しくJava側で受け取ることができます。