PEAR マニュアル
前のページ次のページ

DB_Table フォームのチュートリアル

DB_Table フォームのチュートリアル --  HTML_QuickForm のフォームの作成

説明

このページでは、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 オブジェクトのすべてのカラムを入力フィールドとするフォームを返します。

例 39-1すべてのカラムを使用するデフォルトのフォーム

<?php
// [省略] GuestBook_Table オブジェクト ($GuestBook) を作成します

// <classname>HTML_QuickForm</classname> オブジェクトを作成します
$form =& $GuestBook->getForm(); // "=&" に注意 -- 重要です

// フォームを表示します
$form->display();
?>

カラムの指定

表示するフィールドを絞り込んだり表示順を変更したりするには、 カラム名を指定した数値添字配列を getForm() の最初のパラメータに指定します。

例 39-2getForm() でのカラム名の指定

<?php

// [省略] GuestBook_Table オブジェクト ($GuestBook) を作成します

// 姓、名、メールアドレスのみをフォームに表示します
$cols = array('fname', 'lname', 'email');

// <classname>HTML_QuickForm</classname> オブジェクトを作成します
$form =& $GuestBook->getForm($cols);

// フォームを表示します
$form->display();

?>

ボタンの追加

残念ながら、このフォームには入力フィールドしかありません。"送信" ボタンや "リセット" ボタンは自動的には生成されないのです。

例 39-3 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_*' というキーと値を追加します。

要素のラベル

あるカラムをフォームに表示させる際に、同時にラベルを表示させることができます。 最大 32 文字までの文字列であるカラム "other" があるとしましょう。 もしフォーム上でこの項目のラベルとして "その他の情報" と表示させたければ 'qf_label' キーを次のように使用します。

例 39-4'qf_label' の設定

<?php

class GuestBook_Table extends DB_Table
{
 
    var $col = array( 
        // ...  
        'example' => array( 
            // テーブルのカラムの定義
            'type' => 'varchar', 
            'size' => 32, 
             
            // フォームの要素の定義
            'qf_label' => 'その他の情報'
        )
    ); 
} 
?>

要素の型

デフォルトで、DB_Table はカラムの型に応じてフォームの入力フィールドの型を決めようとします。 大半のカラム型はテキストフィールドとなりますが、いくつか例外があります。

特定のカラムに対する HTML_QuickForm の要素の型を指定して上のデフォルトより優先させたい場合は、 'qf_type' 要素をカラム定義に追加します。 DB_Table に対して、 HTML_QuickForm がサポートする任意の要素型を指定することができます。 'qf_type' 要素には、これらの文字列値を指定します。

その他の要素名を指定した場合、DB_Table はそれを適切な HTML_QuickForm 要素に関連付けようとします (Moritz Heidkamp のパッチに感謝します) が、動作保証はできません。

この例では、'example' カラムをテキストフィールドに指定しています。

例 39-5要素の型の設定

<?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' 要素で行います。

例 39-6チェックボックスの値の設定

チェックボックスの場合は、ふたつの要素からなる数値添字配列を使用します。 最初の要素はチェックされていないときの値、 次の要素がチェックされているときの値となります。

この例では、チェックされていないときの値が 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)
        )
    );
}
?>

例 39-7ラジオボタンおよび 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 要素の行数と列数を指定するには次のようにします。

例 39-8テキストエリアの行数と列数の設定

<?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 を使う際に常に意識しておくことが大切です。

使用できる規則は次のとおりです。

DB_Table は、たいていの場合は自動的に HTML_QuickForm の規則を追加します。

フォーム内に登場するカラムに対して特定の HTML_QuickForm の規則を適用したい場合は、'qf_rules' キーに規則の名前を指定し、 規則の内容をその値に設定します。たいていの場合は、値にはエラーメッセージを設定することになるでしょう。 しかし、場合によっては配列を値に指定することもあります。 さまざまな規則をお好みに応じて追加することができますが、 同じ型の規則はひとつづつしか追加できません。

例 39-9QuickForm の規則

<?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() をコールする際に、 カラム名の配列ではなく連装配列を渡すようにします。 カラム名が連装配列のキー、そしてその値が連装配列の値となります。

例 39-10フォームのフィールドへのデフォルト値の設定

<?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' という配列のキーとしたい場合は、このようにします。

例 39-11フォームの値を配列形式で返す

<?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 オブジェクトに追加することができます。

実際の使用例を見てみましょう。

例 39-12独自の 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);

?>
前のページホーム次のページ
DB_Table クラスのチュートリアル上に戻るDB_Table_Database クラスのチュートリアル