著者としては、このガイド、もしくはチュートリアル（好きに呼んでもらえれば良いです）が、 役に立ち、読者の皆さんの時間が節約できれば良いと願っています。 この文章が役に立つと感じたら、いくらかの寄付をいただけるとうれしいと思います。 （もし、役には立たないと感じたら、なぜかを メールで教えてください。）
Keith Edmunds
訳注： 寄付は 元サイト からお願いします。
この文章は、上記著者の PEAR HTML_QuickForm Getting Started Guide（2004/2/19版）を訳出したものです。 原著は、 Creative Commons - Attribution / Share Alike ライセンスで公開されています。したがって、本翻訳のライセンスも同様とします。 また、翻訳の誤りがあれば、お気楽に ご連絡ください。
2004/3/16： 瀬戸山 春輝
PHPおよびPEARがインストールされており、読者はPHPとHTMLに馴染んでいるものとします。 PEARについてのヘルプは PEARのサイトにあります。 PHPについては、PHPのサイトをご覧ください。 また、読者の使用するWEBサーバは、PHPスクリプトを正確に解釈するものとします。 以下のスクリプトは、WEBサーバが実行されている環境についての情報を表示します。
<?php
phpinfo();
?>もし、情報が表示されず、このコードそのままがブラウザに表示されるならば、 次に進む前に、その問題を解決しておく必要があります。 PHPのセットアップについてのチュートリアルは、インターネットに 数多くありますので、すこし検索してみれば適当なものが見つかるでしょう。
また、PEARのインストールを最新にしておくのも良い考えです。 以下のコマンドで行います。
# Optionally check for upgrades first
pear list-upgrades
# Upgrade PEAR
pear upgrade-all<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Testing PEAR HTML_QuickForm</title>
</head>
<body>
<?php
require_once "HTML/QuickForm.php";
$form = new HTML_QuickForm('frmTest', 'get');
$form->addElement('header', 'MyHeader', 'QuickFormのテスト');
$form->display();
?>
</body>
</html>このファイルをブラウザで読み込むと、シンプルに、 「QuickFormのテスト」の文字がグレイの背景の上に黒で表示されます。 特別面白い結果ではないですが、これは、PEARとQuickFormが 適切にインストールされ動作していることを示しています。
それでは、行ごとに考察していきましょう。
require_once "HTML/QuickForm.php";まず、QuickFormのクラス定義をロードします。
$form = new HTML_QuickForm('frmTest', 'get');次に、HTML_QuickFormのインスタンスを生成します。
ここでは、フォームの名前をfrmTestに、 フォーム変数をPHPスクリプトに渡すためのメソッドを GETとしています。 この例では、渡すべき変数はありません。 また、デフォルトでは、フォームのアクション、 つまりフォームが送信されるURIは、 そのフォームが最初に表示されたURIと同じになります。 このことは、はじめは奇妙に見えますが、 後で見るように実際はとても便利です。
$form->addElement('header', 'MyHeader', 'QuickFormのテスト');この行は、フォームに要素 (element) を作成します。 要素とは、フォーム中に表示されるアイテムのことです。 テキストボックスや、セレクトボックス、プレーンテキストなどなどがあります。 この例では、header要素 （表示を改善させるためのQuickFormに含まれている擬似要素）を作成しています。 この要素は、MyHeaderという名前と、 QuickFormのテストというテキスト値をもっています。
$form->display();この行は、フォームを表示し、ユーザがそれに入力できるようにします。 ただし、この例ではユーザができるところはありません。
それでは、（この例を出発点として）もうすこし複雑な例を作成してみましょう。
以下では、上記例のうち<?php>タグ内部のコードだけを示します。
次の例をみてください。
<?php
require_once "HTML/QuickForm.php";
$form = new HTML_QuickForm('frmTest', 'get');
$form->addElement('header', 'MyHeader', 'QuickFormのテスト');
$form->addElement('text', 'MyTextBox', 'あなたのお名前は？');
$form->addElement('reset', 'btnClear', 'クリア');
$form->addElement('submit', 'btnSubmit', '送信');
$form->display();
?>
新しく３つの要素を加えました。 label値が設定されたテキストボックス、リセットボタン、および送信ボタンです。 ユーザは、テキストボックスに入力でき、リセットボタンも動作します。 しかし、送信ボタンをクリックしても何も表示されません。 後で、この点を修正し、さらに、追加可能な各要素について、その完全な記法に ついて示します。
HTML_QuickFormは、フォーム要素の凍結 (freezing) というコンセプトを導入しています。 要素が凍結されると、ユーザがその要素を編集できなくなります。 HTML_QuickFormは、要素の描画方法を変えることで、 それを実装しています。 たとえば、テキストボックスの場合では、内容が単なるテキストで描画され、 編集ができなくなります。
HTML_QuickFormはまた、フォームの妥当性検証 (validating) というコンセプトも用いています。 フォームを表示するURIがコールされ、 (そのフォームが使っているGET あるいは POST メソッドに）一つ以上のパラメタがあり、 すべての（すぐこの後で述べる）ルールを満たしている場合、 そのフォームは妥当であるとみなされます。
それでは、これら２つのコンセプトを、実際のコードで見ていきましょう。
<?php
require_once "HTML/QuickForm.php";
$form = new HTML_QuickForm('frmTest', 'get');
$form->addElement('header', 'MyHeader', 'QuickFormのテスト');
$form->addElement('text', 'MyTextBox', 'あなたのお名前は？');
$form->addElement('reset', 'btnClear', 'クリア');
$form->addElement('submit', 'btnSubmit', '送信');
if ($form->validate()) {
// フォームの検証が成功したら、凍結する。
$form->freeze();
}
$form->display();
?>ここでは、フォームを表示する直前に、その検証を試みています。 検証が成功するためには、 いくつかのGETパラメータを URIの後に付け加えてページをコールすることが必要ですが、 初回のコールなので、 GETパラメータは付け加えられていないので 検証メソッドはFALSEを返し、 フォームは凍結されずに、フォームは表示されます。
ここで、送信ボタンを押すと何かが起こります。 フォームのaction属性値は、デフォルトでは、 そのフォームが最初に表示されたURIとなっており、 ?MyTextBox=mynameという GETパラメータが付け加えられています。 （満たすべき基準が今のところ与えられていませんので）検証は成功し、 再表示される前にフォームの要素は凍結されます。 試してみてください。名前を入力し送信をクリックすると、 フォームは再描画され、テキストボックスがなくなり、 普通のテキストと置き換えられるでしょう。
HTML_QuickFormは、 ユーザの入力の妥当性検証をおこなう機能を備えています。 デフォルトでは、"required"（必須）なフィールドは、 ユーザに対してその旨が表示され、 必須であるはずの入力が行われなかった場合は、 変更可能なエラーメッセージが表示されます。 以下をご覧ください。
<?php
require_once "HTML/QuickForm.php";
$form = new HTML_QuickForm('frmTest', 'get');
$form->addElement('header', 'MyHeader', 'QuickFormのテスト');
$form->addElement('text', 'MyTextBox', 'あなたのお名前は？');
$form->addElement('reset', 'btnClear', 'クリア');
$form->addElement('submit', 'btnSubmit', '送信');
$form->addRule('MyTextBox', '名前の入力が必要です', 'required');
if ($form->validate()) {
// フォームの検証が成功したら、凍結する。
$form->freeze();
}
$form->display();
?>$form->addRuleの行に注意してください。 これは、"MyTextBox" 要素が必須（つまり空とできない） であることを表しており、もし空のままであれば、 「名前の入力が必要です」とエラーメッセージが表示されます。
このフォームを表示させると、名前の欄が必須であることがユーザに表示されます。 名前欄を空白のまま送信ボタンをクリックすると、エラーメッセージが表示されます。 名前欄を埋めて送信すると、検証が行われ、凍結されて再表示されます。
上記の例では、検証はフォームが送信された後にサーバサイドで行われました。 Javascriptを使って、クライアントサイドでのルールの検証が可能です。 addRuleの行に少しだけ変更を加えます。
$form->addRule('MyTextBox', '名前の入力が必要です', 'required', '', 'client');この例では、検証ルールが満たされなかった場合には、 ユーザにエラーを知らせるダイアログボックスが表示されます。 これはサーバサイドでの検証よりも明確でないかもしれませんが、 ユーザに入力エラーを知らせる前にサーバに接続する必要がないという利点があります。
検証ルールとして、"Required" の他にも使用できるものがあります。 完全なリストは以下のとおり。
付加の引数が必要なルールもあります。 （たとえば、maxlength）
$form->addRule('postcode', '便番号は最大7文字です。', 'maxlength', 7, 'client');上記のリストに加え、ユーザ定義のルールを使うこともできます。
上記の例では、たとえばシングルスペースなど、どの様な入力でも検証ルールが満たされます。 これは、このルールが単に1文字以上テキストボックスに入力されているかどうかだけを 調べているからです。
前後のスペースを取り除いた文字列がほしい場合を考えます。 正規表現を書きルールを "regex" とすることでも可能ですが、 もっと簡単な方法があります。 組み込み関数のtrimが、まさしくほしい物です。 applyFilterメソッドを使うことで、 フォームが検証される前にテキストボックスの内容を trim関数に通すことができます。
<?php
require_once "HTML/QuickForm.php";
$form = new HTML_QuickForm('frmTest', 'get');
$form->addElement('header', 'MyHeader', 'QuickFormのテスト');
$form->addElement('text', 'MyTextBox', 'あなたのお名前は？');
$form->addElement('reset', 'btnClear', 'クリア');
$form->addElement('submit', 'btnSubmit', '送信');
$form->addRule('MyTextBox', '名前の入力が必要です', 'required');
$form->applyFilter('MyTextBox', 'trim');
if ($form->validate()) {
// フォームの検証が成功したら、凍結する。
$form->freeze();
}
$form->display();
?>スペースだけを入力し送信をクリックしても、スペースはルールがチェックされる前に 取り除かれているので、検証は失敗します。
applyFilterメソッドは２つの引数を取ります。 始めは、要素の名前です。ただし、'__ALL__'という文字列を与えると、 フォームのすべての要素にフィルタが適用されます。 ２つめの引数は、組み込みもしくはユーザ定義の関数名（文字列）、もしくは配列です。 （配列の形式はこのガイドでは扱いません。）
これまでの例では、フォームが表示されたときに、はじめの値は設定されていませんでた。 このセクションでは、はじめの値、つまりデフォルト値の設定方法について見ていきます。 データベースに保持された情報をフォームを使って編集することを想定して、 例にすこし変更を加えます。 ただし、データベース関連のコードで複雑になるのをさけるため、 データベースから取得したデータを静的な配列で表します。
以下の例では、データベース中の氏名および敬称を編集します。 まず始めに、デフォルト値を付加しないフォームについて見てみます。 （ルールとフィルタは簡単のために除いています。）
<?php
require_once "HTML/QuickForm.php";
##########################################################
# The user information would normally come from a database
$user = array("firstname"=>"Mickey",
"lastname"=>"Mouse",
"sal_id"=>4,
"user_id"=>7);
# 'Salutation' comes from a lookup table comprising
# sal_id, sal_text
$salutations = array("0"=>"Mr",
"1"=>"Miss",
"2"=>"Mrs",
"3"=>"Dr",
"4"=>"Sir");
# End of "database-retrieved" information
##########################################################
$form = new HTML_QuickForm('frmTest', 'get');
$form->addElement('header', 'MyHeader', 'ユーザ名の編集');
$form->addElement('hidden', 'user_id');
$form->addElement('select', 'sal_id', '敬称:', $salutations);
$form->addElement('text', 'firstname', '名:');
$form->addElement('text', 'lastname', '性:');
$form->addElement('reset', 'btnClear', 'クリア');
$form->addElement('submit', 'btnSubmit', '送信');
if ($form->validate()) {
// フォームの検証が成功したら、処理する
$form->freeze();
echo "\n<HR>\n";
}
$form->display();
?>require_once文のあとで、 ２つの配列 $userと$salutations を初期化しています。これらは、通常はデータベースから連想配列として得られるものです。 また、新しくhiddenおよびselect要素を使用しています。 hidden要素は、 user_id （推測できると思いますがデータベースのキー）という名称で作成されています。 ここでは、その値は設定されていません。 第3引数として値を設定することもできますが、後で見るように自動で値を設定することができます。 select要素の記法は、テキストボックスと似ていますが、 第4引数はセレクトボックス用の値の配列となります。
ここで、デフォルトとなるべき値は配列$userにセットされています。 先に述べたように、通常この配列はデータベースから得られます。 フォーム要素へのデフォルト値は、要素名=>値の組からなる 連想配列にセットします。 以下に示す様に、 setDefaultsメソッドの行を記述するだけで、 フォームの各要素にデフォルト値をセットできます。 （簡単のため前後の数行だけ示しています。）
// フォームの前半は、前の例のとおり
$form->addElement('reset', 'btnClear', 'クリア');
$form->addElement('submit', 'btnSubmit', '送信');
if ($form->validate()) {
// フォームの検証が成功したら、処理する
$form->freeze();
}
$form->setDefaults($user);
$form->display();
?>フォームが表示されると、デフォルト値が$user レコードからセットされています。
定数を、デフォルト値と同じような方法で、setConstants メソッドを使って設定することができます。 デフォルト値と定数との違いは、前者はユーザが編集できるのに対して、 後者はユーザもsetDefaultsコールでも変更することができない ところです。
これまでの例では、ユーザが送信をクリックすると、フォームが凍結状態で表示されるだけでした。 実際には、もちろん、送信された値に対して何らかの処理を行いたいわけです。 データ処理のためのコードを、 $form->validate()コールの直後に書くこともできます。 しかし、フォーム生成と関係のないコードが、フォーム生成の部分に混じってしまうことになります。 processメソッドを使って、 送信された値を引数にとるコールバック関数を呼び出すのが綺麗なやり方です。 以下に例を示します。
// フォームの前半は、前の例のとおり
$form->addElement('reset', 'btnClear', 'クリア');
$form->addElement('submit', 'btnSubmit', '送信');
if ($form->validate()) {
// フォームの検証が成功したら、処理する
$form->freeze();
$form->process('process_data', false);
}
else {
$form->setDefaults($user);
$form->display();
}
function process_data ($values) {
echo "<pre>";
foreach ($values as $key=>$value) {
echo $key."=".$value."<br>";
}
echo "</pre>";
}
?>いくつかの変更を行いました。 まず、else 節を検証の後に使うことで、 フォームの検証が成功していない場合だけ、 フォームが表示されます。 2番目に、検証が成功した場合に、フォームのデータを処理するための ユーザ定義関数 process_data を、 process メソッドを使って呼んでいます。 このコールバック関数は、引数を1つ取り、 その引数の型は要素名=>値という連想配列になります。 process メソッドの第2引数は、 ユーザがそのフォームでファイルをアップロードする場合のみ必要となります。 ここでは、この引数は無視します。 最後に、process_data 関数は、 渡されたデータをリスト表示します。 敬称のセレクトボックスは、選択肢のテキストではなく、 選択肢のインデックスが返されることに注意してください。 インデックスが返されるため、データベースを新しい値でアップデートすることが 容易です。 さらに、適切に hidden の値は user_id にセットされています。
この章は、前章の内容にフィットしないが、 HTML_QuickFormを使うにあたって便利な様々なアイテムについて扱います。
これまでに見たように、addElement メソッドの 第1引数は、フォームに追加する要素のタイプです。 残りの引数の数・型および意味は、追加した要素のタイプに拠るのですが、 「属性」を引数に取る要素が多くあります。 これにより、要素のHTML定義中に追加の属性値を加えることができます。 引数の型は文字列もしくは配列となります。 以下に2つの例を示し、属性の使用方法を明らかにします。
初めに例は、色付きの背景のテキストエリアを表示するものです。 この例では、スタイルの定義が必要ですので、 ファイル全体を以下に示します。
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Testing PEAR HTML_QuickForm</title>
<style type="text/css">
.ok { background: green; }
.warn { background: yellow; }
.error { background: red; }
</style>
</head>
<body>
<?php
require_once "HTML/QuickForm.php";
$form = new HTML_QuickForm('frmTest', 'get');
$form->addElement('textarea', 'MyTextArea', 'Details:', "class=warn");
if ($form->validate()) {
$form->freeze();
}
$form->display();
?>addElement メソッドのはじめの３つの引数は、 これまでに見たとおり、要素のタイプ、要素の名前、およびキャプションです。 4番目のパラメータが「属性」で、この場合、文字列を渡しており、 テキストエリアの背景を黄色にするようにclassを "warn" にセットしています。
2番目の例は、テキストエリアのclassだけでなく、height と width も変化させます。 この例では、複数の属性値を渡したいので、配列を使用します。
// First part of form as previous example
<?php
require_once "HTML/QuickForm.php";
$form = new HTML_QuickForm('frmTest', 'get');
$attrs = array("class"=>"error",
"rows"=>"10",
"cols"=>"50");
$form->addElement('textarea', 'MyTextArea', 'Details:', $attrs);
if ($form->validate()) {
// Form is validated, then processes the data
$form->freeze();
}
$form->display();
?>属性の別の使用法としては、Javascript のコードを渡すことがあります。 以下の（少し不自然な）例では、 ユーザが送信ボタンをクリックしなくても、 フォームのセレクトボックスの値を変化させます。 （ブラウザが Javascript をサポートしている場合。）
<?php
require_once "HTML/QuickForm.php";
define ("OK", 0);
define ("WARNING", 1);
define ("ERROR", 2);
$status_list = array(OK=>"All OK",
WARNING=>"Warning",
ERROR=>"Error");
$styles = array (OK=>"ok",
WARNING=>"warn",
ERROR=>"error");
if (array_key_exists("status", $_GET)) {
$style = $styles[$_GET['status']];
}
else {
$style = $styles[0];
}
$attrs = array('onchange' =>
"javascript:location.href=
'?status='+this.options[this.selectedIndex].value;");
$form = new HTML_QuickForm('frmTest', 'get', null, null, "class=$style");
$form->addElement('select', 'status', 'Select status:', $status_list, $attrs);
$form->display();
?>デフォルトでは、フォームの各要素は別々の行として描画されます。 合理的なデフォルトではありますが、 まとまりが無い感じになる要素もあります。 以下の簡単な例は、「クリア」と「送信」ボタンを１行に表示することで、 より美的にしたものです。
要素グループにより、複数の要素からなる複合要素を作成することができ、 この複合要素を１つの実体としてフォームに追加できます。 以下の例を考察してみてください。
<?php
require_once "HTML/QuickForm.php";
$form = new HTML_QuickForm('frmTest', 'get');
$form->addElement('header', 'MyHeader', 'QuickFormのテスト');
$form->addElement('text', 'MyTextBox', 'あなたの名前は？');
$buttons[] = &HTML_QuickForm::createElement('reset', 'btnClear', 'クリア');
$buttons[] = &HTML_QuickForm::createElement('submit', 'btnSubmit', '送信');
$form->addGroup($buttons, null, null, ' ');
$form->addRule('MyTextBox', '名前の入力が必要です。', 'required');
if ($form->validate()) {
# If the form validates then freeze the data
$form->freeze();
}
$form->display();
?>addGroupメソッドのはじめの引数は、 追加する要素の配列です。 その配列は、上の２行で生成されています。 ４番目の引数は、セパレータテキスト、つまり要素間に置かれるテキストです。 この例では、単に空白文字です。
注意: 要素グループと、ラジオボタンなどに使用される「HTMLグループ」とを混同しないでください。
この章では、各タイプの要素について簡単に大要を説明します。 完全なものではなく、ところによっては簡潔すぎるかもしれません。 また、ソースコードから表現を取って来たものもあります。 （addElementの第1引数に渡される） 要素のタイプ以外の引数はすべてオプショナルです。
通常、チェックボックスは、チェックされたときだけ、 値をフォームに渡します。 チェックされていないボックスは値を返さないだけでなく、 チェックボックスに対応する変数自体も(PHPの)プロセスに渡されません。 advcheckboxは、これを解決します。
addElement('advcheckbox',
string element-name, // advcheckboxの名称
string element-label, // advcheckboxの前に表示されるラベル
string text, // advcheckboxの後に表示されるラベル
mixed attributes, // 属性の文字列もしくは配列
mixed values); //下記参照valuesが省略された場合、 チェック無しの時は空の文字列が返されます。 文字列が渡された場合、空の文字列／渡された文字列が返されます。 ２つの文字列からなる配列が渡された場合、 チェック無し／チェック有りに対応して返されます。
addElement('button',
string element-name, // buttonの名称
string value, // buttonのテキスト
mixed attributes); // 属性の文字列もしくは配列addElement('checkbox',
string element-name, // checkboxの名称
string element-label, // checkboxの前に表示されるラベル
string text, // checkboxの後に表示されるラベル
mixed attributes); // 属性の文字列もしくは配列この擬似要素により、ユーザが日時および／または時刻を入力できる マルチセレクトボックスを作成できます。
addElement('date',
string element-name, // dateの名称
string element-label, // dateの前に表示されるラベル
array options, // 下記参照
mixed attributes); // 属性の文字列もしくは配列optionsは、言語、日付・時刻の形式、および セレクトボックスに表示される最小と最大の年からなる配列です。 この書式文字列によって、日付・時刻の形式を決めるだけでなく、 表示されるセレクトボックスの数も設定します。 返される時刻の値は、連想配列で、各要素のキーは対応する書式文字に、 値はユーザが選択したものになります。 次の例を見ると、はっきりと解るでしょう。
<?php
require_once "HTML/QuickForm.php";
$form = new HTML_QuickForm('frmTest', 'get');
$options = array(
'language' => 'en',
'format' => 'dMYHi',
'minYear' => 2001,
'maxYear' => 2005
);
$form->addElement('date', 'mydate', 'Choose date', $options);
$form->addElement('submit', 'btnSubmit', 'Submit');
if ($form->validate()) {
// Form is validated, then processes the data
$form->freeze();
$form->process('process_data', false);
}
else {
$form->display();
}
function process_data ($values) {
echo "<pre>";
var_dump($values);
echo "</pre>";
}
?>書式文字列に設定できる値は以下のとおり。
D = Short names of days l = Long names of days d = Day numbers M = Short names of months F = Long names of months m = Month numbers Y = Four digit year h = 12 hour format H = 23 hour format i = Minutes s = Seconds a = am/pm A = AM/PM
ユーザ定義の要素について。今後、記述する予定。
この'file'についても文章はLeonie Priceによる
addElement('file',
string element-name, // file要素の名称
string element_label, // file要素のラベル
mixed attributes); // 属性の文字列もしくは配列
この擬似要素は、テキストボックスとボタン、 およびファイルのアップロードを扱うのに必要な機能のすべてを提供します。
注意: 公式の文章では、この要素は廃止が予定されており、 将来のバージョンではサポートされない場合があることが示されています。
では、file要素を使った例を見てみましょう。
<?php
require_once "HTML/QuickForm.php";
$uploadForm = new HTML_QuickForm('upload_form', 'post');
$path = "e:/uploads";
$uploadForm->addElement('hidden', 'path', $path);
$file =& $uploadForm->addElement('file', 'filename', 'File:');
$uploadForm->addRule('filename', 'You must select a file', 'uploadedfile');
$uploadForm->addElement('submit', 'btnUpload', 'Upload');
if ($uploadForm->validate()) {
$uploadForm->process('process', true);
}
else {
$uploadForm->display();
}
function process($values) {
global $file;
if ($file->isUploadedFile()) {
$file->moveUploadedFile($values['path']);
}
else {
print "No file uploaded";
}
}
?>
いくつかのポイントがあります。
はじめに、
$file =& $uploadForm->addElement('file', 'filename', 'File:');
によって、
アップロードされたファイルへのリファレンスを、
$file という名前で生成している点です。
後ほど、process 関数でこのリファレンスが使用されます。
二番目は、file 要素に対して、 ファイルが選択されているかチェックするルール uploadedfile が、 存在することです。 file 要素に対しては、他にも専用のルールがあります。
maxfilesizeは、アップロードする最大のファイルサイズを設定します。
$uploadForm->addRule('filename', 'The file you selected is too large', 'maxfilesize', 524288);mimetypeは、アップロードするファイルのタイプを設定します。
$uploadForm->addRule('filename', 'Must be a jpeg', 'mimetype', array('image/jpeg', 'image/jpeg') );最後のポイントは、検証のあとにprocess関数がコールされるところです。 最後の引数のtrueは、 アップロードされたファイルが フォームによって処理されることを示しています。
addElement('header',
string element-name, // headerの名称
string text); // headerのテキストaddElement('hidden',
string element-name, // hidden要素の名称
string value, // hidden要素の値
mixed attributes); // 属性の文字列もしくは配列このセクションは今後完成させる予定。
この擬似要素は、複数のセレクト要素をダイナミックに生成します。 ２番目のセレクト要素で選択可能な値は、 １番目のセレクト要素で選択された値によって決まります。 たとえば、１番目のセレクトボックスが国で、２番目が都市だとします。 選択された国に存在する都市だけが選択可能になります。
addElement('hierselect',
string element-name, // hierselect要素の名称
string label, // ラベルのテキスト
mixed attributes); // 属性の文字列もしくは配列setMainOptions および setSecOptions メソッドを使って ２つのセレクトボックスを設定します。 setMainOptions の引数は、１次元の配列です。 setSecOptions の引数は、２次元の配列で、 はじめの次元は先の配列のキーで、 ２番目の選択肢を適切なメインの選択肢に関連付けるのに使われます。 返される値は、２つの要素からなる配列で、はじめの要素は メインの選択肢の値、２番目の要素は２番目の選択肢の値です。 hierselect 要素の使用方法を簡単に理解できるように、 以下に例を示します。
<?php
require_once "HTML/QuickForm.php";
$form = new HTML_QuickForm('frmTest', 'get');
$main = array();
$secondary = array();
$main[0] = "England";
$main[1] = "Scotland";
$main[2] = "USA";
$secondary[0][0] = "London";
$secondary[0][1] = "Manchester";
$secondary[0][2] = "Liverpool";
$secondary[1][3] = "Edinburgh";
$secondary[1][4] = "Glasgow";
$secondary[2][5] = "Fort Worth";
$secondary[2][6] = "Boston";
$secondary[2][7] = "Los Angles";
$sel =& $form->addElement('hierselect', 'location', 'Location:');
$sel->setMainOptions($main);
$sel->setSecOptions($secondary);
$form->addElement('submit', 'btnSubmit', 'Submit');
if ($form->validate()) {
// Form is validated, then processes the data
$form->freeze();
$form->process('process_data', false);
}
else {
$form->display();
}
function process_data ($values) {
echo "<pre>";
var_dump($values);
echo "</pre>";
}
?>注意: メインのセレクトボックスにデフォルト値がセットされている場合、 ２番目にセレクトボックスの内容は自動的に変更されません。
デフォルト値は以下のようにセットします。
// First part of form as previous example
$form->setDefaults(array('location'=>array(1,4)));
$sel =& $form->addElement('hierselect', 'location', 'Location:');
$sel->setMainOptions($main);
$sel->setSecOptions($secondary);
$form->addElement('submit', 'btnSubmit', 'Submit');
// Rest of form as previous example注意: setDefaultsは、addElementよりも先に記述する必要があります。
この擬似要素は、生のHTMLをフォームに追加します。
addElement('html',
string html-text;) // 追加するHTML画像をフォームに追加します。
addElement('image',
string element-name, // imageの名称
string src, // 画像ソースファイル
mixed attributes); // 属性の文字列もしくは配列リンクを作成します。
addElement('link',
string element-name, // linkの名称
string label, // fieldフィールドのラベル
string href, // リンク先のURI
string text, // 表示するテキスト
mixed attributes); // 属性の文字列もしくは配列addElement('password',
string element-name, // passwordの名称
string label, // passwordフィールドのラベル
mixed attributes); // 属性の文字列もしくは配列addElement('radio',
string element-name, // buttonの名称
string label, // buttonの前に表示されるテキスト
string text, // textの後に表示されるテキスト
int value, // 返り値
mixed attributes); // 属性の文字列もしくは配列注意: 同じ名称で複数のラジオボタンを加えると、 それらは１つのグループ（つまり、１つだけが選択できる）になります。
グループの中でデフォルトで選択しておくためには、次のようにします。
setDefaults(array(element-name, value));addElement('reset',
string element-name, // resetの名称
string value, // ボタンに表示されるテキスト
mixed attributes); // 属性の文字列もしくは配列addElement('select',
string element-name, // selectの名称
string label, // selectのラベル
mixed data, // selectのdata値。前述の説明を参照
mixed attributes); // 属性の文字列もしくは配列静的なテキストをフォームに表示します。
addElement('static',
string label, // 表示するラベル
string text); // 表示するテキストaddElement('submit',
string element-name, // submitの名称
string value, // ボタンに表示されるテキスト
mixed attributes); // 属性の文字列もしくは配列addElement('text',
string element-name, // text boxの名称
string label, // ラベル
mixed attributes); // 属性の文字列もしくは配列addElement('textarea',
string element-name, // textareaの名称
string label, // ラベル
mixed attributes); // 属性の文字列もしくは配列This work is licensed under the Creative Commons - Attribution / Share Alike license.
Copyright 2003 Keith Edmunds. Questions, Comments, Corrections? Email [email protected].
Japanese translation copyright 2004 Haruki Setoyama. Email [email protected].