cvs: peardoc /ja/package/database/db-table intro-forms.xml
[email protected] ("TAKAGI Masahiro")
| Newsgroups | php.pear.doc |
|---|---|
| Message-ID | <cvstakagi1190592590@cvsserver> |
takagi Mon Sep 24 00:09:50 2007 UTC
Added files:
/peardoc/ja/package/database/db-table intro-forms.xml
Log:
added Japanese translation.
takagi-20070924000950.txt
(text/plain, 27.2 KB)
http://cvs.php.net/viewvc.cgi/peardoc/ja/package/database/db-table/intro-forms.xml?view=markup&rev=1.1
Index: peardoc/ja/package/database/db-table/intro-forms.xml
+++ peardoc/ja/package/database/db-table/intro-forms.xml
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 1.1 $ -->
<!-- EN-Revision: 1.2 Maintainer: takagi Status: ready -->
<refentry id="package.database.db-table.intro-forms">
<refnamediv>
<refname><classname>DB_Table</classname> フォームのチュートリアル</refname>
<refpurpose>
<classname>HTML_QuickForm</classname> のフォームの作成
</refpurpose>
</refnamediv>
<refsect1 id="package.database.db-table.intro-forms.desc">
&title.desc;
<para>
このページでは、<classname>DB_Table</classname> クラスを使って
<classname>HTML_QuickForm</classname> のフォーム要素を作成する方法を説明します。
これは、テーブルのカラムを表示したり新たな行を作成したりするときのために使用できます。
<classname>DB_Table</classname> を使用すると、
カラム定義から自動的にデフォルトのフォーム要素を作成してくれます。
ごく普通のカラム定義でもそれなりのフォームが作成できますが、
独自のラベルやオプションを指定したいこともあるでしょう。
その場合は、カラム定義の中に 'qf_*' というキーを追加します。
</para>
<para>
注意: <classname>HTML_QuickForm</classname> は非常に強力なパッケージで、
さまざまなオプションを持っています。一方 <classname>DB_Table</classname>
では複雑なところは無視してシンプルなフォームを自動生成するようにしています。
<classname>HTML_QuickForm</classname> の強力な機能を活用するには、
<classname>DB_Table</classname> で自動生成した要素を
<classname>HTML_QuickForm</classname> で作成した独自のフォームと
うまく組み合わせることが大切です。<classname>DB_Table</classname>
はとりあえず <classname>HTML_QuickForm</classname> を使いたい場合に
手始めに用いるには便利ですが、完全に
<classname>HTML_QuickForm</classname> に取って代わるものではありません。
</para>
</refsect1>
<refsect1 id="package.database.db-table.intro-forms.default">
<title>デフォルトの要素にもとづくシンプルなフォーム</title>
<para>
カラムを定義してオブジェクトのインスタンスを作成したら、
<function>getForm</function> メソッドを用いて完全な
<classname>HTML_QuickForm</classname> オブジェクトを生成することができます。
<function>getForm</function> に何もパラメータを指定せずにコールすると、
$GuestBook オブジェクトのすべてのカラムを入力フィールドとするフォームを返します。
</para>
<example>
<title>すべてのカラムを使用するデフォルトのフォーム</title>
<programlisting role="php">
<![CDATA[
<?php
// [省略] GuestBook_Table オブジェクト ($GuestBook) を作成します
// <classname>HTML_QuickForm</classname> オブジェクトを作成します
$form =& $GuestBook->getForm(); // "=&" に注意 -- 重要です
// フォームを表示します
$form->display();
?>
]]>
</programlisting>
</example>
<refsect2 id="package.database.db-table.intro-forms.default.columns">
<title>カラムの指定</title>
<para>
表示するフィールドを絞り込んだり表示順を変更したりするには、
カラム名を指定した数値添字配列を getForm() の最初のパラメータに指定します。
</para>
<example>
<title><function>getForm</function> でのカラム名の指定</title>
<programlisting role="php">
<![CDATA[
<?php
// [省略] GuestBook_Table オブジェクト ($GuestBook) を作成します
// 姓、名、メールアドレスのみをフォームに表示します
$cols = array('fname', 'lname', 'email');
// <classname>HTML_QuickForm</classname> オブジェクトを作成します
$form =& $GuestBook->getForm($cols);
// フォームを表示します
$form->display();
?>
]]>
</programlisting>
</example>
</refsect2>
<refsect2 id="package.database.db-table.intro-forms.default.buttons">
<title>ボタンの追加</title>
<para>
残念ながら、このフォームには入力フィールドしかありません。"送信"
ボタンや "リセット" ボタンは自動的には生成されないのです。
</para>
<example>
<title>
<function>getForm</function> での "送信" および "リセット" ボタンの追加
</title>
<programlisting role="php">
<![CDATA[
<?php
// [省略] GuestBook_Table オブジェクト ($GuestBook) を作成します
// HMTL_QuickForm オブジェクトを作成します
$form =& $GuestBook->getForm($cols);
// "op" という名前で "Go!" と表示する送信ボタンを追加します
$form->addElement('submit', 'op', 'Go!');
// リセットボタンを追加します
$form->addElement('reset');
// フォームを表示します
$form->display();
?>
]]>
</programlisting>
</example>
</refsect2>
</refsect1>
<refsect1 id="package.database.db-table.intro-forms.custom">
<title>独自の要素を使用したシンプルなフォーム</title>
<para>
基本のフォームもよくできていますが、これはほんとうに標準的なものでしかありません。
入力フィールドの説明用のラベルもないし、
入力フィールドはすべてテキストボックスだし、といった具合です。
このセクションでは、カラム定義の中にフォーム要素のプロパティを含めることで、
もう少ししっかりした独自のフォームを作成する方法を説明します。
</para>
<para>
ここでは、$col プロパティに 'qf_*' というキーと値を追加します。
<itemizedlist>
<listitem>
<simpara>
'qf_label' (文字列) フィールドにテキストラベルを追加する
</simpara>
</listitem>
<listitem>
<simpara>
'qf_type' (文字列) 入力フィールドの形式 (text、hidden、select、checkbox など) を設定する
</simpara>
</listitem>
<listitem>
<simpara>
'qf_vals' (配列) select、radio および checkbox の value の一覧を設定する
elements
</simpara>
</listitem>
<listitem>
<simpara>
'qf_attrs' (配列) 入力要素の HTML 属性を追加で指定する
</simpara>
</listitem>
<listitem>
<simpara>
'qf_opts' (配列) 日付要素 (date、time、timestamp、jscalendar) のオプションを設定する
</simpara>
</listitem>
</itemizedlist>
</para>
<refsect2 id="package.database.db-table.intro-forms.custom.label">
<title>要素のラベル</title>
<para>
あるカラムをフォームに表示させる際に、同時にラベルを表示させることができます。
最大 32 文字までの文字列であるカラム "other" があるとしましょう。
もしフォーム上でこの項目のラベルとして "その他の情報"
と表示させたければ 'qf_label' キーを次のように使用します。
</para>
<example>
<title>'qf_label' の設定</title>
<programlisting role="php">
<![CDATA[
<?php
class GuestBook_Table extends DB_Table
{
var $col = array(
// ...
'example' => array(
// テーブルのカラムの定義
'type' => 'varchar',
'size' => 32,
// フォームの要素の定義
'qf_label' => 'その他の情報'
)
);
}
?>
]]>
</programlisting>
</example>
</refsect2>
<refsect2 id="package.database.db-table.intro-forms.custom.type">
<title>要素の型</title>
<para>
デフォルトで、<classname>DB_Table</classname>
はカラムの型に応じてフォームの入力フィールドの型を決めようとします。
大半のカラム型はテキストフィールドとなりますが、いくつか例外があります。
<itemizedlist>
<listitem>
<simpara>
Boolean 型のカラムは <classname>HTML_QuickForm</classname> の
'advcheckbox' フィールドとなり、チェックされていないときの値が 0、
チェックされているときの値が 1 となります。
</simpara>
</listitem>
<listitem>
<simpara>
CLOB 型のカラムは <classname>HTML_QuickForm</classname> の 'textarea' フィールドとなります。
</simpara>
</listitem>
<listitem>
<simpara>
Date 型のカラムは <classname>HTML_QuickForm</classname> の 'date'
選択フィールド ('Y-m-d' 形式) となります。
</simpara>
</listitem>
<listitem>
<simpara>
Time 型のカラムは <classname>HTML_QuickForm</classname> の 'date'
選択フィールド ('H:i:s' 形式) となります。
</simpara>
</listitem>
<listitem>
<simpara>
Timestamp 型のカラムは <classname>HTML_QuickForm</classname> の 'date'
選択フィールド ('Y-m-d H:i:s' 形式) となります。
</simpara>
</listitem>
</itemizedlist>
</para>
<para>
特定のカラムに対する <classname>HTML_QuickForm</classname>
の要素の型を指定して上のデフォルトより優先させたい場合は、
'qf_type' 要素をカラム定義に追加します。
<classname>DB_Table</classname> に対して、
<classname>HTML_QuickForm</classname> がサポートする任意の要素型を指定することができます。
'qf_type' 要素には、これらの文字列値を指定します。
<itemizedlist>
<listitem>
<simpara>
'checkbox' は単一のチェックボックスとなり、
<classname>HTML_QuickForm</classname> の
'advcheckbox' に対応します。
</simpara>
</listitem>
<listitem>
<simpara>
'hidden' は hidden 要素となります。
</simpara>
</listitem>
<listitem>
<simpara>
'password' はパスワードテキストボックスとなります。
</simpara>
</listitem>
<listitem>
<simpara>
'radio' はラジオボタンのセットとなります。
</simpara>
</listitem>
<listitem>
<simpara>
'select' は select メニューとなります。
</simpara>
</listitem>
<listitem>
<simpara>
'text' はテキストボックスとなります。
</simpara>
</listitem>
<listitem>
<simpara>
'textarea' はテキストエリアとなります。
</simpara>
</listitem>
<listitem>
<simpara>
'date' は日付選択要素で 'Y-m-d' 形式となります。
</simpara>
</listitem>
<listitem>
<simpara>
'time' は時刻選択要素です。'date' 型で 'H:i:s' 形式となります。
</simpara>
</listitem>
<listitem>
<simpara>
'timestamp' はタイムスタンプ選択要素です。'date' 型で
'Y-m-d H:i:s' 形式となります。
</simpara>
</listitem>
</itemizedlist>
その他の要素名を指定した場合、<classname>DB_Table</classname>
はそれを適切な <classname>HTML_QuickForm</classname> 要素に関連付けようとします
(Moritz Heidkamp のパッチに感謝します) が、動作保証はできません。
</para>
<para>
この例では、'example' カラムをテキストフィールドに指定しています。
</para>
<example>
<title>要素の型の設定</title>
<programlisting role="php">
<![CDATA[
<?php
class GuestBook_Table extends DB_Table
{
var $col = array(
// ...
'example' => array(
// テーブルのカラムの定義
'type' => 'varchar',
'size' => 32,
// フォームの要素の定義
'qf_label' => 'その他の情報',
'qf_type' => 'text'
)
);
}
?>
]]>
</programlisting>
</example>
</refsect2>
<refsect2 id="package.database.db-table.intro-forms.custom.values">
<title>要素の値</title>
<para>
カラムに対応するフォーム要素が 'checkbox'、'radio' あるいは 'select'
の場合は、フォーム要素の選択肢の値を設定することができます。
これは、対応するカラム定義の 'sq_vals' 要素で行います。
</para>
<example id="package.database.db-table.intro-forms.custom.values.checkbox">
<title>チェックボックスの値の設定</title>
<para>
チェックボックスの場合は、ふたつの要素からなる数値添字配列を使用します。
最初の要素はチェックされていないときの値、
次の要素がチェックされているときの値となります。
</para>
<para>
この例では、チェックされていないときの値が 0、
チェックされているときの値が 1 となります。
これらの値がこのカラムに保存されます。
</para>
<programlisting role="php">
<![CDATA[
<?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)
)
);
}
?>
]]>
</programlisting>
</example>
<example id="package.database.db-table.intro-forms.custom.values.radio">
<title>ラジオボタンおよび select 要素の値</title>
<para>
ラジオボタンや select メニューでは、連想配列を使用します。
カラムに保存される値が連想配列のキー、
そしてユーザに対して表示されるテキストが連想配列の値となります。
</para>
<para>
この例は、3 つの値 ('a'、'b' および 'c')
とそれに対応するラベルを持つ select メニューを作成します。
</para>
<programlisting role="php">
<![CDATA[
<?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" が正解さ'
)
)
);
}
?>
]]>
</programlisting>
</example>
</refsect2>
<refsect2 id="package.database.db-table.intro-forms.custom.html-attributes">
<title>要素の HTML 属性</title>
<para>
もしお望みなら、フォームの要素の HTML に属性を追加することもできます。
そうするには 'qf_attrs' キーを使用します。追加する属性は、
キーと値の組み合わせで連装配列として指定します。
属性の名前が連装配列のキー、属性の値が連装配列の値となります。
たとえば、textarea 要素の行数と列数を指定するには次のようにします。
</para>
<example>
<title>テキストエリアの行数と列数の設定</title>
<programlisting role="php">
<![CDATA[
<?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
)
)
);
}
?>
]]>
</programlisting>
</example>
<para>
DB_Table は、text 要素と password 要素の "maxlength"
属性はカラムの定義にもとづいて自動的に設定します。
したがって、カラムのサイズより大きな値は入力することができません。
</para>
</refsect2>
<refsect2 id="package.database.db-table.intro-forms.custom.rules">
<title>要素の規則</title>
<para>
<classname>HTML_QuickForm</classname> では、
入力フォームの検証規則を追加することができます。
この規則は <classname>DB_Table</classname>
が自動的に行う検証とは異なります。
<classname>HTML_QuickForm</classname> の規則はフォームに関連する値にのみ適用され、
テーブルに関連する値には適用されません。
この点は、<classname>HTML_QuickForm</classname>
を使う際に常に意識しておくことが大切です。
</para>
<para>
使用できる規則は次のとおりです。
<itemizedlist>
<listitem>
<simpara>
email - 入力はメールアドレスのみでなければならない
</simpara>
</listitem>
<listitem>
<simpara>
lettersonly -- 入力は文字のみでなければならない
</simpara>
</listitem>
<listitem>
<simpara>
maxlength -- 入力の文字数をこれより多くすることはできない
</simpara>
</listitem>
<listitem>
<simpara>
maxlength -- 入力の文字数をこれより少なくすることはできない
</simpara>
</listitem>
<listitem>
<simpara>
nonzero -- 入力はゼロより大きいかゼロより小さいかのいずれかでなければならない
</simpara>
</listitem>
<listitem>
<simpara>
nopunctuation -- 入力に記号を含んではいけない
</simpara>
</listitem>
<listitem>
<simpara>
numeric -- 入力は数値形式 (文字以外) でなければならない
</simpara>
</listitem>
<listitem>
<simpara>
regex -- 入力が正規表現にマッチしなければならない
</simpara>
</listitem>
<listitem>
<simpara>
required -- 必ず入力しなければならない (たとえ空白ひとつでも)
</simpara>
</listitem>
</itemizedlist>
DB_Table は、たいていの場合は自動的に <classname>HTML_QuickForm</classname>
の規則を追加します。
<itemizedlist>
<listitem>
<simpara>
必須カラム ('require' => true) の場合は、
<classname>DB_Table</classname> は
<classname>HTML_QuickForm</classname> の規則 'required'
を追加します。
</simpara>
</listitem>
<listitem>
<simpara>
数値型のカラム ('smallint'、'integer'、'bigint'、'single'、
'double' あるいは 'timestep') の場合は、<classname>DB_Table</classname> は
<classname>HTML_QuickForm</classname> の規則 'numeric'
を追加します。
</simpara>
</listitem>
<listitem>
<simpara>
カラムにサイズ ('size') が指定されている場合は、
<classname>DB_Table</classname> は規則 'maxlength' を追加します。
</simpara>
</listitem>
</itemizedlist>
フォーム内に登場するカラムに対して特定の <classname>HTML_QuickForm</classname>
の規則を適用したい場合は、'qf_rules' キーに規則の名前を指定し、
規則の内容をその値に設定します。たいていの場合は、値にはエラーメッセージを設定することになるでしょう。
しかし、場合によっては配列を値に指定することもあります。
さまざまな規則をお好みに応じて追加することができますが、
同じ型の規則はひとつづつしか追加できません。
</para>
<example>
<title>QuickForm の規則</title>
<programlisting role="php">
<![CDATA[
<?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_]+$/'
)
);
)
)
}
?>
]]>
</programlisting>
<para>
<classname>HTML_QuickForm</classname>
ではグループに対する規則やフォーム全体に対する規則もサポートしていますが、
<classname>DB_Table</classname> はこれらの自動生成には対応していません。
必要に応じて自分で追加してください。
</para>
</example>
</refsect2>
</refsect1>
<refsect1 id="package.database.db-table.intro-forms.default-values">
<title>デフォルト値の設定</title>
<para>
入力フォームにデフォルト値を表示させたいこともあるでしょう。
たとえば現在データベースに登録されている値を表示させるなどです。
これを行うのは簡単です。
</para>
<para>
<function>getForm</function> をコールする際に、
カラム名の配列ではなく連装配列を渡すようにします。
カラム名が連装配列のキー、そしてその値が連装配列の値となります。
</para>
<example>
<title>フォームのフィールドへのデフォルト値の設定</title>
<programlisting role="php">
<![CDATA[
<?php
// [省略] GuestBook_Table オブジェクト ($GuestBook) を作成します
// 姓、名、メールアドレスのみをフォームに表示します
// フォーム要素のデフォルト値を設定します
$cols = array(
'fname' => 'トーマス',
'lname' => 'アンダーソン',
'email' => '[email protected]'
);
// HTML_QuickForm オブジェクトを作成します
$form =& $GuestBook->getForm($cols);
// フォームを表示します
$form->display();
?>
]]>
</programlisting>
</example>
</refsect1>
<refsect1 id="package.database.db-table.intro-forms.element-names">
<title>配列のキーで指定する要素名</title>
<para>
デフォルトでは、<function>getForm</function>
をコールする際のフォーム要素の名前はカラム名となります。
たとえば、カラム 'fname' に対応するフォーム項目の名前は 'fname'
となります。
<programlisting role="screen">
<![CDATA[
<!-- [省略] フォームここから -->
<input type="text" name="fname" ... />
<!-- [省略] フォームここまで -->
]]>
</programlisting>
しかし、時にはフォームの要素を個別の変数で管理するのではなく
配列のキーで管理したいこともあるでしょう。
これは、たとえばその値を <classname>DB_Table</classname> の
<function>insert</function> や <function>update</function>
のコールで使用したい場合に便利です。
</para>
<para>
これを行うには、名前の配列を <function>getForm</function>
の 2 番目の引数 (フォームで使用するカラムの一覧を渡したあとの引数)
として渡します。たとえば、カラム名を 'new_row'
という配列のキーとしたい場合は、このようにします。
</para>
<example>
<title>フォームの値を配列形式で返す</title>
<programlisting role="php">
<![CDATA[
<?php
// [省略] GuestBook_Table クラスのオブジェクト $GuestBook を作成します
// フォームに表示するカラムを選択します
$cols = array('fname', 'lname', 'email');
// HTML_QuickForm オブジェクトを作成します
// 要素命は 'new_row' という配列で指定します
$form = $GuestBook->getForm($cols, 'new_row');
// フォームを表示します
$form->display()
?>
]]>
</programlisting>
</example>
</refsect1>
<refsect1 id="package.database.db-table.intro-forms.custom-objects">
<title>独自の <classname>HTML_QuickForm</classname> オブジェクト</title>
<para>
<function>getForm</function> メソッドはすべての
<classname>HTML_QuickForm</classname> パラメータ (フォームの名前、
メソッド、アクションなど) をサポートしてはいますが、
<classname>DB_Table</classname> だけでフォーム全体を作成する必要はありません。
もしそうしたいなら、まず自分で <classname>HTML_QuickForm</classname>
オブジェクトを作成し、そこに <classname>DB_Table</classname>
のカラムをひとつづつ (あるいはグループで) 追加していくといいでしょう。
</para>
<para>
<classname>DB_Table</classname> には以下のようなメソッドがあり、
これらを使用すると自動定義された要素を既存の
<classname>HTML_QuickForm</classname> オブジェクトに追加することができます。
<itemizedlist>
<listitem>
<simpara>
<function>addFormElements</function>
はひとつあるいは複数の自動定義されたフォーム要素オブジェクトを
既存の <classname>HTML_QuickForm</classname> オブジェクトに追加し、
<classname>DB_Table</classname> で定義された規則も関連付けます。
</simpara>
</listitem>
<listitem>
<simpara>
<function>getFormGroup</function>
は、自動定義されたフォーム要素オブジェクトの
<classname>HTML_QuickForm</classname> グループ配列を取得します。
</simpara>
</listitem>
<listitem>
<simpara>
<function>getFormElement</function>
は自動定義された要素オブジェクトを取得します。
</simpara>
</listitem>
</itemizedlist>
実際の使用例を見てみましょう。
</para>
<example>
<title>独自の HTML 要素</title>
<programlisting role="php" >
<![CDATA[
<?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);
?>
]]>
</programlisting>
</example>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"../../../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->