このチュートリアルは、QuickForm を初めて使うユーザに対して、 機能と使用法の概要を紹介するものです。 ここでは、利用できる機能の内のほんの一部だけについて解説しますが、 より広く深く知るために本マニュアルのどこを見れば良いかについても示していきます。
Keith Edmunds によって書かれた、QuickForm の使用法についての いくぶん長めのチュートリアル も参考となるでしょう。
基本的な使用方法
<?php
// メインクラスの読み込み
require_once 'HTML/QuickForm.php';
// HTML_QuickForm オブジェクトを生成
$form = new HTML_QuickForm('firstForm');
// フォーム要素のデフォルト値を設定
$form->setDefaults(array(
'name' => '山田太郎'
));
// フォームに要素をいくつか追加
$form->addElement('header', null, 'QuickForm チュートリアルのサンプル');
$form->addElement('text', 'name', '名前を入力してください:', array('size' => 50, 'maxlength' => 255));
$form->addElement('submit', null, '送信');
// フィルタと検証ルールを追加
$form->applyFilter('name', 'trim');
$form->addRule('name', '名前を入力してください', 'required', null, 'client');
// フォームの妥当性検証
if ($form->validate()) {
echo '<h1>こんにちは、' . htmlspecialchars($form->exportValue('name')) . 'さん!</h1>';
exit;
}
// フォームの出力
$form->display();
?>
では、順を追って上記の例を検討して行きましょう。
<?php
$form = new HTML_QuickForm('firstForm');
?>
の行で、HTML_QuickForm オブジェクトが生成されています。
後で、このHTML_QuickForm オブジェクトに、要素に対応したオブジェクトや他の必要な情報を加えていくこととなります。
ここで、コンストラクタには、
フォームの名称のみを渡し、他のパラメータはデフォルト値が使われています。
フォームの method 属性のデフォルト値は POST、そして
action 属性のデフォルト値は現在のファイル名となります。QuickForm を使用する際には、
フォームに関連するロジックをひとつのファイルにまとめておくと楽になります。
次のコードが name 要素のデフォルト値を '山田太郎'
に設定するものであることは、おそらく予想が付くでしょう。
<?php
$form->setDefaults(array(
'name' => '山田太郎'
));
?>
QuickForm には、デフォルト値 (setDefaults() メソッドで設定します) および定数値 (setConstants() メソッドで設定します) という概念があります。これらの違いは、デフォルト値はユーザの入力によって上書きされるが、 定数値は上書きされないという点です。
今回のフォームは、3 つの要素から構成されています。
<?php
$form->addElement('header', null, 'QuickForm チュートリアルのサンプル');
$form->addElement('text', 'name', '名前を入力してください:', array('size' => 50, 'maxlength' => 255));
$form->addElement('submit', null, '送信');
?>
最初の要素は「本来の」要素ではありません。これは単に見栄えをよくするための見出しです。 2 番目の要素はテキスト入力欄で、3 番目は送信ボタンです。 addElement() メソッドのパラメータは、要素の型によって意味が異なってくることに注意しましょう。 なぜなら、このパラメータはそれぞれの要素のコンストラクタに渡されるものだからです。
次の行では、'name' 要素の値に対する フィルタ を定義しています。
<?php
$form->applyFilter('name', 'trim');
?>
フィルタとは、フォームが送信された際に要素の値に対して適用される関数のことです。 この例の場合は組み込みの trim() 関数を使用していますが、これ以外にも任意の callback を使用することができます。 ここでは、入力された名前から空白を取り除いています。というのも、 空白は不要なものであり、単に空白が入力されたのではなく きちんと名前が入力されたのだということを確認したいからです。
次に、名前欄の 規則 を定義します。
<?php
$form->addRule('name', '名前を入力してください', 'required', null, 'client');
?>
このコードの意味は、名前が入力されなかった場合に QuickForm がエラーメッセージを表示するということです。
'client' という指定をすると、サーバ側での検証だけでなく
クライアント側での JavaScript による検証も有効にします。また、QuickForm
はこのフィールドに対して必須フィールドの印を自動的につけることにも注意しましょう。
フォームの作成が終了し、検証規則も定義しました。 次に、フォームを処理するのか表示するのかを決めなければなりません。
<?php
if ($form->validate()) {
// 何らかの処理
}
?>
validate() メソッドが「フォームが有効である」と判断する (つまり TRUE を返す) のは、 何らかのデータが送信され、かつフォームに定義されている規則がすべて満たされた場合です。 今回の例では、これは 'name' 要素が空でなかったことを表します。
フォームの入力が検証されたら、その値を処理しなければなりません。
<?php
echo '<h1>こんにちは、' . htmlspecialchars($form->exportValue('name')) . 'さん!</h1>';
exit;
?>
これはひとつの例です。実際のスクリプトでは、値をどこかに保存したうえで別のページにリダイレクトし、 二重送信を防ぐなどの処理も必要になることでしょう。 このような場合に使用されるメソッドは process() および exportvalues() です。
最後の行は、とても簡単です。
<?php
$form->display();
?>
フォームが有効でない場合、すなわちまだ送信されていなかったり入力内容に不備があった場合は、 フォームの内容が表示されます。もしエラーメッセージが存在すれば、 対応する要素のそばにそれが表示されます。
基本的な QuickForm の機能についてはこれでご理解いただけたことでしょう。 しかし、このパッケージにはここで取り上げた以外にも多くの機能があります。 それらについてはそれぞれ個別のチュートリアルを設けています。 この節ではそれらについての簡単な説明をした上で、詳細なドキュメントの場所を示します。
グループ を使用すると、 複数の独立した要素をひとつのエンティティにまとめ、 それをひとつの要素であるかのように使用することができます。 これは date や hierselect のような擬似要素を作成するためにも使用されています。
QuickForm は、フォームのレイアウトや見栄えを変更するために多くの機能を提供しています。 フォームの出力は レンダラ が行います。これは必要なロジックが組み込まれた特別なクラスです。 直接 HTML を出力する レンダラや、 テンプレートエンジンを使用する レンダラがあります。
そして最後に、独自の要素型や検証規則そして レンダラ を追加することで QuickForm を拡張することもできます。