DB_Table フォームのチュートリアル
Description
このページでは、DB_Table クラスを使って HTML_QuickForm のフォーム要素を作成する方法を説明します。 これは、テーブルのカラムを表示したり新たな行を作成したりするときのために使用できます。 DB_Table を使用すると、 カラム定義から自動的にデフォルトのフォーム要素を作成してくれます。 ごく普通のカラム定義でもそれなりのフォームが作成できますが、 独自のラベルやオプションを指定したいこともあるでしょう。 その場合は、カラム定義の中に 'qf_*' というキーを追加します。
注意: HTML_QuickForm は非常に強力なパッケージで、 さまざまなオプションを持っています。一方 DB_Table では複雑なところは無視してシンプルなフォームを自動生成するようにしています。 HTML_QuickForm の強力な機能を活用するには、 DB_Table で自動生成した要素を HTML_QuickForm で作成した独自のフォームと うまく組み合わせることが大切です。DB_Table はとりあえず HTML_QuickForm を使いたい場合に 手始めに用いるには便利ですが、完全に HTML_QuickForm に取って代わるものではありません。
デフォルトの要素にもとづくシンプルなフォーム
カラムを定義してオブジェクトのインスタンスを作成したら、 getForm() メソッドを用いて完全な HTML_QuickForm オブジェクトを生成することができます。 getForm() に何もパラメータを指定せずにコールすると、 $GuestBook オブジェクトのすべてのカラムを入力フィールドとするフォームを返します。
すべてのカラムを使用するデフォルトのフォーム
<?php
// [省略] GuestBook_Table オブジェクト ($GuestBook) を作成します
// <classname>HTML_QuickForm</classname> オブジェクトを作成します
$form =& $GuestBook->getForm(); // "=&" に注意 -- 重要です
// フォームを表示します
$form->display();
?>
カラムの指定
表示するフィールドを絞り込んだり表示順を変更したりするには、 カラム名を指定した数値添字配列を getForm() の最初のパラメータに指定します。
getForm() でのカラム名の指定
<?php
// [省略] GuestBook_Table オブジェクト ($GuestBook) を作成します
// 姓、名、メールアドレスのみをフォームに表示します
$cols = array('fname', 'lname', 'email');
// <classname>HTML_QuickForm</classname> オブジェクトを作成します
$form =& $GuestBook->getForm($cols);
// フォームを表示します
$form->display();
?>
ボタンの追加
残念ながら、このフォームには入力フィールドしかありません。"送信" ボタンや "リセット" ボタンは自動的には生成されないのです。
getForm() での "送信" および "リセット" ボタンの追加
<?php
// [省略] GuestBook_Table オブジェクト ($GuestBook) を作成します
// HMTL_QuickForm オブジェクトを作成します
$form =& $GuestBook->getForm($cols);
// "op" という名前で "Go!" と表示する送信ボタンを追加します
$form->addElement('submit', 'op', 'Go!');
// リセットボタンを追加します
$form->addElement('reset');
// フォームを表示します
$form->display();
?>
独自の要素を使用したシンプルなフォーム
基本のフォームもよくできていますが、これはほんとうに標準的なものでしかありません。 入力フィールドの説明用のラベルもないし、 入力フィールドはすべてテキストボックスだし、といった具合です。 このセクションでは、カラム定義の中にフォーム要素のプロパティを含めることで、 もう少ししっかりした独自のフォームを作成する方法を説明します。
ここでは、$col プロパティに 'qf_*' というキーと値を追加します。
-
'qf_label' (文字列) フィールドにテキストラベルを追加する
-
'qf_type' (文字列) 入力フィールドの形式 (text、hidden、select、checkbox など) を設定する
-
'qf_vals' (配列) select、radio および checkbox の value の一覧を設定する elements
-
'qf_attrs' (配列) 入力要素の HTML 属性を追加で指定する
-
'qf_opts' (配列) 日付要素 (date、time、timestamp、jscalendar) のオプションを設定する
要素のラベル
あるカラムをフォームに表示させる際に、同時にラベルを表示させることができます。 最大 32 文字までの文字列であるカラム "other" があるとしましょう。 もしフォーム上でこの項目のラベルとして "その他の情報" と表示させたければ 'qf_label' キーを次のように使用します。
'qf_label' の設定
<?php
class GuestBook_Table extends DB_Table
{
var $col = array(
// ...
'example' => array(
// テーブルのカラムの定義
'type' => 'varchar',
'size' => 32,
// フォームの要素の定義
'qf_label' => 'その他の情報'
)
);
}
?>
要素の型
デフォルトで、DB_Table はカラムの型に応じてフォームの入力フィールドの型を決めようとします。 大半のカラム型はテキストフィールドとなりますが、いくつか例外があります。
-
Boolean 型のカラムは HTML_QuickForm の 'advcheckbox' フィールドとなり、チェックされていないときの値が 0、 チェックされているときの値が 1 となります。
-
CLOB 型のカラムは HTML_QuickForm の 'textarea' フィールドとなります。
-
Date 型のカラムは HTML_QuickForm の 'date' 選択フィールド ('Y-m-d' 形式) となります。
-
Time 型のカラムは HTML_QuickForm の 'date' 選択フィールド ('H:i:s' 形式) となります。
-
Timestamp 型のカラムは HTML_QuickForm の 'date' 選択フィールド ('Y-m-d H:i:s' 形式) となります。
特定のカラムに対する HTML_QuickForm の要素の型を指定して上のデフォルトより優先させたい場合は、 'qf_type' 要素をカラム定義に追加します。 DB_Table に対して、 HTML_QuickForm がサポートする任意の要素型を指定することができます。 'qf_type' 要素には、これらの文字列値を指定します。
-
'checkbox' は単一のチェックボックスとなり、 HTML_QuickForm の 'advcheckbox' に対応します。
-
'hidden' は hidden 要素となります。
-
'password' はパスワードテキストボックスとなります。
-
'radio' はラジオボタンのセットとなります。
-
'select' は select メニューとなります。
-
'text' はテキストボックスとなります。
-
'textarea' はテキストエリアとなります。
-
'date' は日付選択要素で 'Y-m-d' 形式となります。
-
'time' は時刻選択要素です。'date' 型で 'H:i:s' 形式となります。
-
'timestamp' はタイムスタンプ選択要素です。'date' 型で 'Y-m-d H:i:s' 形式となります。
この例では、'example' カラムをテキストフィールドに指定しています。
要素の型の設定
<?php
class GuestBook_Table extends DB_Table
{
var $col = array(
// ...
'example' => array(
// テーブルのカラムの定義
'type' => 'varchar',
'size' => 32,
// フォームの要素の定義
'qf_label' => 'その他の情報',
'qf_type' => 'text'
)
);
}
?>
要素の値
カラムに対応するフォーム要素が 'checkbox'、'radio' あるいは 'select' の場合は、フォーム要素の選択肢の値を設定することができます。 これは、対応するカラム定義の 'sq_vals' 要素で行います。
チェックボックスの値の設定
チェックボックスの場合は、ふたつの要素からなる数値添字配列を使用します。 最初の要素はチェックされていないときの値、 次の要素がチェックされているときの値となります。
この例では、チェックされていないときの値が 0、 チェックされているときの値が 1 となります。 これらの値がこのカラムに保存されます。
<?php
class GuestBook_Table extends DB_Table
{
var $col = array(
// ...
'example' => array(
// テーブルのカラムの定義
'type' => 'varchar',
'size' => 32,
// フォームの要素の定義
'qf_label' => 'その他の情報',
'qf_type' => 'text',
'qf_vals' => array(0, 1)
)
);
}
?>
ラジオボタンおよび select 要素の値
ラジオボタンや select メニューでは、連想配列を使用します。 カラムに保存される値が連想配列のキー、 そしてユーザに対して表示されるテキストが連想配列の値となります。
この例は、3 つの値 ('a'、'b' および 'c') とそれに対応するラベルを持つ select メニューを作成します。
<?php
class GuestBook_Table extends DB_Table
{
var $col = array(
// ...
'example' => array(
// テーブルのカラムの定義
'type' => 'varchar',
'size' => 32,
// フォームの要素の定義
'qf_label' => 'その他の情報',
'qf_type' => 'text',
'qf_vals' => array(
'a' => 'これは "a" です',
'b' => '"b" を選びます',
'c' => 'いや、いつだって "c" が正解さ'
)
)
);
}
?>
要素の HTML 属性
もしお望みなら、フォームの要素の HTML に属性を追加することもできます。 そうするには 'qf_attrs' キーを使用します。追加する属性は、 キーと値の組み合わせで連装配列として指定します。 属性の名前が連装配列のキー、属性の値が連装配列の値となります。 たとえば、textarea 要素の行数と列数を指定するには次のようにします。
テキストエリアの行数と列数の設定
<?php
class GuestBook_Table extends DB_Table
{
var $col = array(
// ...
'example' => array(
// テーブルのカラムの定義
'type' => 'varchar',
'size' => 32,
// フォームの要素の定義
'qf_label' => 'その他の情報',
'qf_type' => 'textarea',
'qf_attrs' => array(
'rows' => 24,
'cols' => 80
)
)
);
}
?>
DB_Table は、text 要素と password 要素の "maxlength" 属性はカラムの定義にもとづいて自動的に設定します。 したがって、カラムのサイズより大きな値は入力することができません。
要素の規則
HTML_QuickForm では、 入力フォームの検証規則を追加することができます。 この規則は DB_Table が自動的に行う検証とは異なります。 HTML_QuickForm の規則はフォームに関連する値にのみ適用され、 テーブルに関連する値には適用されません。 この点は、HTML_QuickForm を使う際に常に意識しておくことが大切です。
使用できる規則は次のとおりです。
-
email - 入力はメールアドレスのみでなければならない
-
lettersonly -- 入力は文字のみでなければならない
-
maxlength -- 入力の文字数をこれより多くすることはできない
-
maxlength -- 入力の文字数をこれより少なくすることはできない
-
nonzero -- 入力はゼロより大きいかゼロより小さいかのいずれかでなければならない
-
nopunctuation -- 入力に記号を含んではいけない
-
numeric -- 入力は数値形式 (文字以外) でなければならない
-
regex -- 入力が正規表現にマッチしなければならない
-
required -- 必ず入力しなければならない (たとえ空白ひとつでも)
-
必須カラム ('require' => true) の場合は、 DB_Table は HTML_QuickForm の規則 'required' を追加します。
-
数値型のカラム ('smallint'、'integer'、'bigint'、'single'、 'double' あるいは 'timestep') の場合は、DB_Table は HTML_QuickForm の規則 'numeric' を追加します。
-
カラムにサイズ ('size') が指定されている場合は、 DB_Table は規則 'maxlength' を追加します。
QuickForm の規則
<?php
class GuestBook_Table extends DB_Table
{
var $col = array(
// ...
'example1' => array(
// テーブルのカラムの定義
'type' => 'integer',
// フォームの要素の定義
'qf_label' => 'Information',
'qf_type' => 'text',
// QuickForm の規則
'qf_rules' => array(
'required' => 'このフィールドは必須です。',
'numeric' => '数値しか使用できません。文字は使用できません。'
)
),
'example2' => array(
// テーブルのカラムの定義
'type' => 'varchar',
'size' => 10,
// フォームの要素の定義
'qf_label' => 'Something:',
'qf_type' => 'text',
// QuickForm の規則
'qf_rules' => array(
'minlength' => array('6 文字以上で指定してください。', 6),
'maxlength' => array('10 文字以下で指定してください。', 10),
'regex' => array(
'大文字とアンダースコア以外は使用できません。',
'/^[A-Z_]+$/'
)
);
)
)
}
?>
HTML_QuickForm ではグループに対する規則やフォーム全体に対する規則もサポートしていますが、 DB_Table はこれらの自動生成には対応していません。 必要に応じて自分で追加してください。
デフォルト値の設定
入力フォームにデフォルト値を表示させたいこともあるでしょう。 たとえば現在データベースに登録されている値を表示させるなどです。 これを行うのは簡単です。
getForm() をコールする際に、 カラム名の配列ではなく連装配列を渡すようにします。 カラム名が連装配列のキー、そしてその値が連装配列の値となります。
フォームのフィールドへのデフォルト値の設定
<?php
// [省略] GuestBook_Table オブジェクト ($GuestBook) を作成します
// 姓、名、メールアドレスのみをフォームに表示します
// フォーム要素のデフォルト値を設定します
$cols = array(
'fname' => 'トーマス',
'lname' => 'アンダーソン',
'email' => 'neo@matrix.net'
);
// HTML_QuickForm オブジェクトを作成します
$form =& $GuestBook->getForm($cols);
// フォームを表示します
$form->display();
?>
配列のキーで指定する要素名
デフォルトでは、getForm() をコールする際のフォーム要素の名前はカラム名となります。 たとえば、カラム 'fname' に対応するフォーム項目の名前は 'fname' となります。
<!-- [省略] フォームここから --> <input type="text" name="fname" ... /> <!-- [省略] フォームここまで -->
しかし、時にはフォームの要素を個別の変数で管理するのではなく 配列のキーで管理したいこともあるでしょう。 これは、たとえばその値を DB_Table の insert() や update() のコールで使用したい場合に便利です。
これを行うには、名前の配列を getForm() の 2 番目の引数 (フォームで使用するカラムの一覧を渡したあとの引数) として渡します。たとえば、カラム名を 'new_row' という配列のキーとしたい場合は、このようにします。
フォームの値を配列形式で返す
<?php
// [省略] GuestBook_Table クラスのオブジェクト $GuestBook を作成します
// フォームに表示するカラムを選択します
$cols = array('fname', 'lname', 'email');
// HTML_QuickForm オブジェクトを作成します
// 要素命は 'new_row' という配列で指定します
$form = $GuestBook->getForm($cols, 'new_row');
// フォームを表示します
$form->display()
?>
独自の HTML_QuickForm オブジェクト
getForm() メソッドはすべての HTML_QuickForm パラメータ (フォームの名前、 メソッド、アクションなど) をサポートしてはいますが、 DB_Table だけでフォーム全体を作成する必要はありません。 もしそうしたいなら、まず自分で HTML_QuickForm オブジェクトを作成し、そこに DB_Table のカラムをひとつづつ (あるいはグループで) 追加していくといいでしょう。
DB_Table には以下のようなメソッドがあり、 これらを使用すると自動定義された要素を既存の HTML_QuickForm オブジェクトに追加することができます。
-
addFormElements() はひとつあるいは複数の自動定義されたフォーム要素オブジェクトを 既存の HTML_QuickForm オブジェクトに追加し、 DB_Table で定義された規則も関連付けます。
-
getFormGroup() は、自動定義されたフォーム要素オブジェクトの HTML_QuickForm グループ配列を取得します。
-
getFormElement() は自動定義された要素オブジェクトを取得します。
独自の HTML 要素
<?php
// [省略] GuestBook_Table のオブジェクト $GuestBook を作成します
// クラスファイルを読み込み QuickForm オブジェクトを作成します
require_once 'HTML/QuickForm.php';
$form =& new HTML_QuickForm();
// ひとつあるいは複数の要素を GuestBook オブジェクトから
// QuickForm オブジェクトに追加し、同時にこれらの要素の
// 規則も設定します
$cols = array('email', 'signdate');
$GuestBook->addFormElements($form, $cols);
// GuestBook カラムの要素グループを
// QuickForm オブジェクトに追加します (規則は追加しません)
$cols = array('fname', 'lname');
$group =& $GuestBook->getFormGroup($cols);
$form->addGroup($group);
// 単一のフォーム要素オブジェクトに独自の名前を指定し、
// それをフォームに追加します
$col = 'id';
$name = 'new_row[id]';
$element =& $GuestBook->getFormElement($col, $name);
$form->addElement($element);
?>
忘却曲線を使ってこの知識を確実に記憶に残す
