Zend Framework入門（12）：
フォームのカスタマイズ - Zend_Form -（後編）

Zend Frameworkによる実践的なPHPアプリケーション開発 12

標準で添付されているデコレータ

　ここでは標準で添付されているデコレータについて説明します。なお、各デコレータの名前に「Zend_Form_Decorator_」をつけたものがデコレータのクラス名になります。

Callback

　コールバックを呼び出して、内容を加工するデコレータです。コールバックは通常のPHPのコールバックで、$content, $element, $optionsの３つの引数を取ります。定義されたコールバックを登録するにはCallbackデコレータのオプションにコールバック名を与えます：

リスト7 Callbackデコレータ（サンプルのIndexController.phpより）

class TestCallback
{
    public static function decorate($content, $element, array $options)
    {
        return '---- append';
    }
}
...
$user = $form->getElement('user');
$user->addDecorator('callback',
                    array('callback' =>
                    array('TestCallBack', 'decorate')));

Captcha

　Zend Framework 1.6.0 から追加された機能で、同じくZend Framework1.6.0から追加されたフォーム要素のZend_Form_Element_Captchaから使われることを想定してます。なので、このデコレータを明示的に使うことはあまりないと思われます。

　このデコレータを利用する要素にgetCaptchaメソッドがなければ特に何もしませんが、getCaptchaメソッドがあった場合にはCAPTCHAを描画します。

CAPTCHAとは

　CAPTCHA はボット等によるフォームへの送信を防ぐための仕組みです。人間には簡単だがコンピュータには難しい問題を表示し、その問題への解答の正否によって人間かどうかを判断します（ねじ曲がった文字列が何であるかを判別する問題を見たこともある方が多いでしょう）。

Description

　フォーム要素に説明がある場合（getDescriptionメソッドがある場合）に、その説明を描画します。

　下の例ではtextフォーム要素に説明を追加しています。なお、説明は通常フォーム要素本体の後に、class属性が'hint'であるpタグで囲まれますが、このclass属性はオプションの'class'で変更可能です。また標準では説明内容にはエスケープ処理が行われますが、これもオプションの'escape'で変更可能です。

リスト7 Descriptionデコレータ（サンプルのIndexController.phpより）

    //Description
    $form->addElement('text', 'desc');
    $desc = $form->getElement('desc');
    $desc->setDescription('<b>この説明フォーム要素の説明</b>');
    $desc->addDecorator('description',
                         array('class' => 'descrition_class',
                       'escape' => false));

DtDdWrapper

　Zend_Formは標準ではdlタグを利用して要素を描画します。このとき、表示グループやサブフォームの中身は描画の順番によっては離れ離れになってしまう可能性があります。DtDdWrapperデコレータは、これら表示グループやサブフォームをddタグで囲うことでこれを防ぎます。

　これも表示グループやサブフォームで自動的に使われるものなので、明示的に利用する必要はあまりないと思われます。

Errors

　フォームへの入力に誤りがあった場合に表示されるエラーを描画するためのデコレータです。実際にはこのデコレータはエラーの内容をビューヘルパのFormErrorsに渡し、描画もFormErrorビューヘルパに任せます。

　このデコレータは標準でフォーム要素に付加されるものの一つになっています。

Fieldset

　表示グループやサブフォームを囲うためのfieldsetタグを生成するデコレータです。フォーム要素にlegendがあった場合（getLegendメソッドの返り値が空でなかったりlegendオプションが指定されていた場合）には、legendも表示します。

　これも表示グループやサブフォームで自動的に使われるものなので、明示的に利用する必要はあまりないと思われます。

Form

　formタグを描画するためのデコレータです。実際にはFormビューヘルパに描画を任せます。Formビューヘルパは『Zend Framework入門（9）』で説明したとおり、formタグを出力してくれるビューヘルパです。

　このデコレータはZend_Formのインスタンスに自動的に付加されるものの一つになっています。

Zend_Form_Decorator_FormElements

　フォーム等（フォーム、描画グループ、サブフォーム）が中身を描画するためのデコレータです。フォーム等に含まれる各要素に対し、実際の描画結果を返すrenderメソッドを呼び出し、その結果を結合して返します。

　このデコレータはZend_Formのインスタンスに自動的に付加されるものの一つになっています。

HtmlTag

　指定されたタグで与えられた内容を囲います。タグが指定されない場合にはdivタグを利用します。

　このデコレータについては decoratorAction の例で扱っています：

リスト7 HtmlTagデコレータ（サンプルのIndexController.phpより）

    $form->setElementDecorators(array('ViewHelper',
                      'Label',
                      array('HtmlTag', array('tag' => 'li'))));

Image

　imageタイプのinputタグを描画するためのデコレータです。このデコレータはimageフォーム要素から自動的に呼ばれるため、明示的に利用する必要はないと思われます。

Label

　フォーム要素のlabelタグを描画するためのデコレータです。実際にはFormLabelビューヘルパに描画を任せます。

　また、ラベルの前と後に描画する文字列を指定することもできます：

リスト8 Labelデコレータ（サンプルのIndexController.phpより）

//Label
$form->addElement('text', 'label');
$label = $form->getElement('label');
$label->setLabel('ラベルテスト');
$label->addDecorator('label',
                     array('optionalPrefix' => '-->',
                   'optionalSuffix' => '<--',
                   'requiredPrefix' => '!!>',
                   'requiredSuffix' => '<!!'));

ViewHelper

　ビューヘルパを利用してフォーム要素を描画します。標準ではフォーム要素のクラス名から利用するビューヘルパを推測しようとします（クラス名の最後の部分にformをつけたビューヘルパを探します）。また、明示的にhelperオプションを渡すことでどのビューヘルパを利用するのか指定することもできます。

ViewScript

　ビュースクリプトを利用してフォーム要素を描画します。このデコレータを利用する際にはviewScriptオプションで利用するスクリプト名を指定する必要があります。

　ビュースクリプトはパーシャルスクリプトとして処理されます（つまり、名前空間が親のスクリプトと独立となります）。このビュースクリプトにはオプションで指定された引数の他に、次のビュー変数が渡されます。

ビュースクリプトに渡される変数

変数名	概要
element	ViwScriptデコレータが付加されているフォーム要素
content	デコレータに渡された、今までのデコレータが描画した内容
decorator	処理を行っているViewScriptデコレータのインスタンス