HTML_QuickForm_Renderer_ITStatic
Description
レンダラの名前にある 'static' の意味は、実際のフォームの配置は スクリプトが開始する前に決まっているということです。また、 このレンダラを使用する際には各フォームについて独自のテンプレートを用意する必要があります。
IT Dynamic レンダラとは異なり、IT Static レンダラはより柔軟な方法でフォームを表示することができます。 その代わり、(IT Dynamic レンダラと比べて) 実装するのには少し時間がかかることになるでしょう。 もし常に同じようなパターンで要素ラベルやフォーム要素の html を出力するのなら、 動的レンダラを使用するほうがお勧めです。一方、もしいろいろなパターンでフォーム要素を出力するのなら (例えばテキストやフォーム要素の出力方法を切り替えたいのなら)、静的レンダラの使用を推奨します。
使用例
ITStatic レンダラを使用するには、どの要素 (あるあいは要素グループ) を使用してフォームを作成するのかを事前に知っている必要があります。 そこで、まずは要素を定義するところからはじめることにしましょう。
要素の定義
<?php
require_once ("HTML/QuickForm.php");
$form = new HTML_QuickForm('myform', 'POST');
$form->addElement('header', 'myheader', 'Registration form');
$form->addElement('hidden', 'session', '123456');
$name['last'] = &HTML_QuickForm::createElement('text', 'first', 'First', array('size' => 10));
$name['first'] = &HTML_QuickForm::createElement('text', 'last', 'Last', array('size' => 10));
$form->addGroup($name, 'name', 'Name:', '-');
$form->addElement('text', 'email', 'Your email:');
$select = array('' => 'Please select...',
'AU' => 'Australia',
'FR' => 'France',
'DE' => 'Germany',
'IT' => 'Italy');
$form->addElement('select', 'country', 'Country:', $select);
$form->addElement('reset', 'reset', 'Reset');
$form->addElement('submit', 'submit', 'Register');
$form->addElement('checkbox', 'news', '', " Check this box if you don't want to receive our newsletter.");
?>
このフォームには、これらの要素が含まれることになります。
header: 'Registration form'
hidden フィールド
firstname および lastname のふたつの text フィールドからなる group
E-Mail アドレス用の text フィールド
国を指定する selectbox (デフォルト値は空白)
リセットおよび登録の、ふたつの button
ニュースレターの購読を申し込むための checkbox
これで、フォームを構成する要素がわかりました。HTML エディタを使用するなりして、 このフォームの配置を WYSIWYG で作成するのは簡単なことでしょう。 そうやって作成したフォームについて、ラベルや要素の html の部分にプレースホルダを使用するようにします。 プレースホルダの名前はフォーム名および要素名 (グループ名) によって決まり、 formName_elementName あるいは formName_groupName_elementName のようになります。そしてそこに _label または _html を追加します。次のようなコードを template.html という名前のファイルに保存してください。
テンプレート
<html>
<head><title>My Form</title>
{myform_javascript}
</head>
<body>
<form {myform_attributes}>
{myform_session_html}
<table>
<tr><th colspan="2">{myform_myheader}</th></tr>
<tr><td>{myform_name_label}</td><td>{myform_name_html}</td></tr>
<tr><td>{myform_email_label}</td><td>{myform_email_html}</td></tr>
<tr><td>{myform_country_label}</td><td>{myform_country_html}</td></tr>
<tr><td colspan="2" align="right">{myform_reset_html} {myform_submit_html}</td></tr>
</table>
<br /><br />
{myform_news_html}
</form>
</body>
</html>
お気づきのように、このレイアウトは静的なものです。 つまり、実行時にフォームが変更されることがない場合に限り、 静的なレンダラが有用になるということです。しかし、 HTML_Template_IT / HTML_Template_Sigma の removeEmptyBlocks オプションを使用することで、 ブロックを非表示にすることができます。 これで要素とテンプレートの準備ができました。それでは静的レンダラを使用してみましょう。
レンダラの使用
<?php
require_once 'HTML/Template/Sigma.php';
require_once 'HTML/QuickForm/Renderer/ITStatic.php';
$tpl =& new HTML_Template_Sigma('.');
$tpl->loadTemplateFile('template.html'); // or whatever you called it
$renderer =& new HTML_QuickForm_Renderer_ITStatic($tpl);
$renderer->setRequiredTemplate('{label}<font color="red" size="1">*</font>');
$renderer->setErrorTemplate('<font color="red">{error}</font><br />{html}');
$form->accept($renderer);
$tpl->show();
?>
必須要素の表示方法や検証エラーの表示方法について指定することも可能です。 それには、それぞれ setRequiredTemplate() および setErrorTemplate() を使用します。 与えられた文字列中のお望みの場所に、プレースホルダ {label} あるいは {html} を配置することができます。 エラーメッセージをひとまとめにして同じ場所に表示したい場合は、 setErrorTemplate() には空の文字列を渡し、 テンプレート内のお望みの場所にこのブロックを追加します。
<!-- BEGIN myform_error_loop -->
<font color="red">{myform_error}</font><br />
<!-- END myform_error_loop -->
静的レンダラを使用して、グループのレンダリング方法をカスタマイズすることもできます。 単にグループ全体に対してプレースホルダを使用した場合には、そのグループは HTML_QuickForm のデフォルトレンダラでレンダリングされます。 つまり、セパレータ文字列 (あるいはセパレータの配列) が指定されていた場合は それが通常通りに使用されるということです。今回のフォームでは、グループ 'name' がこの方式でレンダリングされています。要素の区切り文字として - が使用されています。
ここで問題なのは、グループ内の要素についてはラベルが表示されないということです。 そのため、2 つのテキストフィールドのうちどちらが苗字でどちらが名前なのかがわかりません。 要素 'name' のレイアウトをこれらの新しいプレースホルダで置き換えることで、 グループの表示方法を変更することができます。
(...)
<tr>
<td>{myform_name_label}</td>
<td>
<!-- BEGIN myform_name_error -->{myform_name_error}<!-- END myform_name_error -->
<table>
<tr><td>{myform_name_first_html}</td><td>{myform_name_last_html}</td></tr>
<tr><td>{myform_name_first_label}</td><td>{myform_name_last_label}</td></tr>
</table>
</td>
</tr>
(...)
新しいブロックとプレースホルダを追加して、 このグループに関連するエラーの表示場所を指定する必要があります。 お気づきのように、プレースホルダの名前はグループ名と要素名から構成されています。
また、同じ名前の複数の要素を使用している場合 (例えばグループに属さないラジオボタンなど)、 プレースホルダの名前に 0 から始まるインデックスを追加しなければならないことにも注意しましょう。 例えば {myform_myradio_0_html}, {myform_myradio_1_html}... のようになります。
静的レンダラを使用して、標準的な要素や要素グループを扱う方法について見てきました。 またエラー表示や必須要素の表示方法についても説明しました。今回のフォームでは 検証規則を何も設定していないため、これらの内容は表示されません。 練習問題として、検証規則を追加することを試してみるとよいでしょう。 特別なプレースホルダ {myform_required_note} をテンプレート内で指定すると、必須要素であることを示す注意書きをそこに表示させることができます。 このレンダラの使用法はとても簡単です。もしこのレンダラが気に入ったのなら、 動的レンダラについても確認してみましょう。 場合によってはこちらのほうがあなたのお望みの動作をするかもしれません。
忘却曲線を使ってこの知識を確実に記憶に残す
