HTML_QuickForm_Renderer_ITDynamic
Description
レンダラの名前にある 'dynamic' の意味は、実際のフォームの配置が スクリプトの実行時に決まるということです。また、すべての フォームに対して ひとつの テンプレートファイルを適用できるということでもあります。 このテンプレートには、フォーム中ののすべての要素の見た目を設定するための ブロックおよびいくつかの特別なブロックが含まれます。 ある要素に特別なブロックが設定されていない場合は、 デフォルトのブロックを使用してレンダリングを行います。
もしほとんどのフォームが同じ見た目になる場合は (バックエンドの管理用インターフェイスなど)、この動的なレンダラを使用するのが最適です。 個々のフォームがそれぞれ独特なレイアウトを使用するのなら、静的なレンダラを使用すべきです。
テンプレートの構造
この例は最小限の記述しかしていないテンプレートですが、 このパッケージで定義するあらゆるフォームをレンダリングするのに必要な要素はすべて含まれています。
{qf_javascript}
<form {qf_attributes}>
<!-- BEGIN qf_hidden_loop -->
{qf_hidden}
<!-- END qf_hidden_loop -->
<table>
<!-- BEGIN qf_errors -->
<tr>
<td>
Collected errors:
<ul>
<!-- BEGIN qf_error_loop -->
<li>{qf_error}</li>
<!-- END qf_error_loop -->
</ul>
</td>
</tr>
<!-- END qf_errors -->
<!-- BEGIN qf_main_loop -->
<!-- BEGIN qf_header -->
<tr>
<th colspan="2">{qf_header}</th>
</tr>
<!-- END qf_header -->
<!-- BEGIN qf_element -->
<tr valign="top">
<td align="right">
<!-- BEGIN qf_element_required --><span style="color: #FF0000;">*</span><!-- END qf_element_required -->
<b>{qf_label}</b>
</td>
<td>
<!-- BEGIN qf_element_error --><span style="color: #FF0000;">{qf_error}</span><br /><!-- END qf_element_error -->
{qf_element}
</td>
</tr>
<!-- END qf_element -->
<!-- BEGIN qf_group -->
<tr valign="top">
<td align="right">
<!-- BEGIN qf_group_required --><span style="color: #FF0000;">*</span><!-- END qf_group_required -->
<b>{qf_group_label}</b>
</td>
<td>
<!-- BEGIN qf_group_error --><span style="color: #FF0000;">{qf_error}</span><br /><!-- END qf_group_error -->
<!-- BEGIN qf_group_loop -->
<!-- BEGIN qf_group_element -->{qf_separator}{qf_label}{qf_element}<!-- END qf_group_element -->
<!-- END qf_group_loop -->
</td>
</tr>
<!-- END qf_group -->
<!-- END qf_main_loop -->
<!-- BEGIN qf_required_note -->
<tr>
<td> </td>
<td align="left" valign="top">{qf_required_note}</td>
</tr>
<!-- END qf_required_note -->
</table>
</form>
- qf_main_loop
このブロックは常に存在する必要があり、 すべての可視要素ブロックの親となります。 "流れ (flow)" を実装し、個々の要素を順にレンダリングするために使用されます。
- qf_element
フォーム要素をレンダリングするためのブロックです。 このブロックは常に存在する必要があります。 レンダラが要素の出力を行う際には、使用するブロックを次の手順で決めます。
要素に対して特別なブロックが設定されていれば、それを使用します。
qf_%要素の型% (例えば qf_password) というブロックが存在すれば、それを使用します。
qf_element を使用します。
- qf_element_required
要素が必須である場合に、ブロックは touch されます。
- qf_element_error
要素に関連付けられたエラーは、ここに出力されます。
- qf_header
ヘッダを出力する際に使用されるデフォルトのブロックです。 フォームにヘッダが存在する場合は必須です。
- qf_group
出力グループのデフォルトブロックです。 グループ化した要素が存在する場合は必須です。
- qf_group_loop
qf_main_loop に対応するもので、 グループの要素を順にレンダリングするために使用されます。 %グループのブロック%_loop は、常に %グループのブロック% の中に存在しなければなりません。
- qf_group_element
グループの要素をレンダリングするためのデフォルトのブロックです。 %グループのブロック%_element は、常に %グループのブロック%_loop の中に存在しなければなりません (qf_element が qf_main_loop の中に存在しなければならないのと同じ理由です)。
- qf_error_loop
要素に関するエラーのうち、%element's block%_error ブロックを持っていないものを出力するために使用されます。
- qf_hidden_loop
<input type="hidden" /> 要素がここにレンダリングされます。
- {qf_javascript}
クライアント側の検証に使用する Javascript がここに出力されます。
- {qf_required_note}
フォーム内に必須要素がある場合、注意書きがここに出力されます。
使用例
テンプレートが ./qform.html にあるものとします。
<?php
require_once 'HTML/QuickForm/Renderer/ITDynamic.php';
require_once 'HTML/Template/Sigma.php';
// テンプレートオブジェクトのインスタンスを作成し、テンプレートファイルを読み込みます
$tpl =& new HTML_Template_Sigma('.');
$tpl->loadTemplateFile('qform.html');
// レンダラのインスタンスを作成し、フォームを処理します
$renderer =& new HTML_QuickForm_Renderer_ITDynamic($tpl);
$form->accept($renderer);
// 結果を出力します
$tpl->show();
?>
フォームを作成する部分についてはここで示していないことに注意しましょう。この例は、 どんなフォームであっても動作するからです。
テンプレートクラスの互換性このレンダラは、 HTML_Template_Sigma を使用して開発およびテストを行っています。おそらく HTML_Template_IT でも動作するでしょうが、それを保証することはできません。
空のブロックの削除このレンダラは、テンプレートオブジェクト内の空のブロックが事前に取り除かれていることを想定しています (これはデフォルトの振る舞いです)。もしそうでない場合、期待通りの出力結果は得られないでしょう。
忘却曲線を使ってこの知識を確実に記憶に残す
