クイックスタートガイド

フォームの構築

$form = new HTML_QuickForm('firstForm');

の行で、HTML_QuickForm オブジェクトが生成されています。 後で、このHTML_QuickForm オブジェクトに、要素に対応したオブジェクトや他の必要な情報を加えていくこととなります。 ここで、コンストラクタには、 フォームの名称のみを渡し、他のパラメータはデフォルト値が使われています。 フォームの method 属性のデフォルト値は POST、そして action 属性のデフォルト値は現在のファイル名となります。QuickForm を使用する際には、 フォームに関連するロジックをひとつのファイルにまとめておくと楽になります。

次のコードが name 要素のデフォルト値を '山田太郎' に設定するものであることは、おそらく予想が付くでしょう。

$form->setDefaults(array( 'name' => '山田太郎' ));

QuickForm には、デフォルト値 (setDefaults() メソッドで設定します) および定数値 (setConstants() メソッドで設定します) という概念があります。これらの違いは、デフォルト値はユーザの入力によって上書きされるが、 定数値は上書きされないという点です。

今回のフォームは、3 つの要素から構成されています。

$form->addElement('header', null, 'QuickForm チュートリアルのサンプル'); $form->addElement('text', 'name', '名前を入力してください:', array('size' => 50, 'maxlength' => 255)); $form->addElement('submit', null, '送信');

最初の要素は「本来の」要素ではありません。これは単に見栄えをよくするための見出しです。 2 番目の要素はテキスト入力欄で、3 番目は送信ボタンです。 addElement() メソッドのパラメータは、要素の型によって意味が異なってくることに注意しましょう。 なぜなら、このパラメータはそれぞれの要素のコンストラクタに渡されるものだからです。

入力のチェック

次の行では、'name' 要素の値に対する フィルタ を定義しています。

$form->applyFilter('name', 'trim');

フィルタとは、フォームが送信された際に要素の値に対して適用される関数のことです。 この例の場合は組み込みの trim() 関数を使用していますが、これ以外にも任意の callback を使用することができます。 ここでは、入力された名前から空白を取り除いています。というのも、 空白は不要なものであり、単に空白が入力されたのではなく きちんと名前が入力されたのだということを確認したいからです。

次に、名前欄の 規則 を定義します。

$form->addRule('name', '名前を入力してください', 'required', null, 'client');

このコードの意味は、名前が入力されなかった場合に QuickForm がエラーメッセージを表示するということです。 'client' という指定をすると、サーバ側での検証だけでなく クライアント側での JavaScript による検証も有効にします。また、QuickForm はこのフィールドに対して必須フィールドの印を自動的につけることにも注意しましょう。

入力の検証および処理

フォームの作成が終了し、検証規則も定義しました。 次に、フォームを処理するのか表示するのかを決めなければなりません。

if ($form->validate()) { // 何らかの処理 }

validate() メソッドが「フォームが有効である」と判断する (つまり TRUE を返す) のは、 何らかのデータが送信され、かつフォームに定義されている規則がすべて満たされた場合です。 今回の例では、これは 'name' 要素が空でなかったことを表します。

フォームの入力が検証されたら、その値を処理しなければなりません。

echo '<h1>こんにちは、' . htmlspecialchars($form->exportValue('name')) . 'さん!</h1>'; exit;

これはひとつの例です。実際のスクリプトでは、値をどこかに保存したうえで別のページにリダイレクトし、 二重送信を防ぐなどの処理も必要になることでしょう。 このような場合に使用されるメソッドは process() および exportvalues() です。

最後の行は、とても簡単です。

$form->display();

フォームが有効でない場合、すなわちまだ送信されていなかったり入力内容に不備があった場合は、 フォームの内容が表示されます。もしエラーメッセージが存在すれば、 対応する要素のそばにそれが表示されます。