repo_zf1/documentation/manual/ja/module_specs/Zend_Form-Elements.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<!-- EN-Revision: 24249 -->
<sect1 id="zend.form.elements">
    <title>Zend_Form_Element を用いたフォーム要素の作成</title>

    <para>
        フォームは、いくつかの要素から構成されています。
        これらの要素は、<acronym>HTML</acronym> フォームの入力項目に対応します。
        <classname>Zend_Form_Element</classname> は個々のフォーム要素をカプセル化し、
        以下の機能を提供します。
    </para>

    <itemizedlist>
        <listitem>
            <para>
                バリデーション (入力されたデータが妥当か?)
            </para>

            <itemizedlist>
                <listitem><para>検証エラーのコードやメッセージの取得</para></listitem>
            </itemizedlist>
        </listitem>

        <listitem><para>
            フィルタリング (出力用のエスケープや検証前後の正規化をどうするか?)
        </para></listitem>

        <listitem><para>
            レンダリング (要素をどのように表示するか?)
        </para></listitem>

        <listitem><para>
            メタデータおよび属性 (その要素についての詳細な情報は?)
        </para></listitem>
    </itemizedlist>

    <para>
        基底クラスである <classname>Zend_Form_Element</classname> は、
        ほとんどの場合にうまく利用できるデフォルトを定義しています。
        しかし、よく使われる特別な要素については
        それを継承したクラスを作成するほうがいいでしょう。
        さらに、Zend Framework には数多くの標準 <acronym>XHTML</acronym> 要素が同梱されています。
        <link linkend="zend.form.standardElements">標準の要素についての章</link>
        を参照ください。
    </para>

    <sect2 id="zend.form.elements.loaders">
        <title>プラグインローダー</title>

        <para>
            <classname>Zend_Form_Element</classname> は、<link
                linkend="zend.loader.pluginloader">Zend_Loader_PluginLoader</link>
            を使用しており、バリデータやフィルタ、デコレータの場所を指定できます。
            それぞれに独自のプラグインローダーが関連付けられており、
            アクセサを使用して個別に取得したり変更したりできます。
        </para>

        <para>
            プラグインローダーのメソッドで使用できるローダーの型は
            'validate'、'filter' と 'decorator' です。
            この型名は大文字小文字を区別しません。
        </para>

        <para>
            プラグインローダーを使用するためのメソッドを以下にまとめます。
        </para>

        <itemizedlist>
            <listitem><para>
                <code>setPluginLoader($loader, $type)</code>:
                <code>$loader</code> はプラグインローダーオブジェクト、
                <code>$type</code> は上であげた型名のいずれかを指定します。
                これは、指定した型に対応するプラグインローダーを新しく設定します。
            </para></listitem>

            <listitem><para>
                <code>getPluginLoader($type)</code>:
                <code>$type</code> に対応するプラグインローダーを取得します。
            </para></listitem>

            <listitem><para>
                <code>addPrefixPath($prefix, $path, $type = null)</code>:
                プレフィックスとパスの関連を、
                <code>$type</code> で指定したローダーに追加します。
                <code>$type</code> が <constant>NULL</constant> の場合は、すべてのローダーにパスを追加します。
                その際には、それぞれプレフィックスに
                "_Validate"、"_Filter" そして "_Decorator" を追加し、
                パスには "Validate/"、"Filter/" そして
                "Decorator/" を追加します。
                追加するフォーム要素クラス群をすべて共通の階層に配置する場合は、
                このメソッドでベースプレフィックスを設定すると便利です。
            </para></listitem>

            <listitem><para>
                <code>addPrefixPaths(array $spec)</code>:
                複数のパスを、ひとつあるいは複数のプラグインローダーに追加します。
                配列の各要素は、キー 'path'、'prefix' および
                'type' を含む配列とします。
            </para></listitem>
        </itemizedlist>

        <para>
            独自のバリデータやフィルタ、デコレータを作成すると、
            複数のフォームで機能を共有したり独自の機能をカプセル化したりすることが簡単になります。
        </para>

        <example id="zend.form.elements.loaders.customLabel">
            <title>独自のラベル</title>

            <para>
                プラグインの使用例としてよくあるのは、
                既存の標準クラス群のかわりとして使用することです。
                たとえば、'Label' デコレータの実装を変更し、
                最後に常にコロンを追加するようにしたくなったとしましょう。
                そんな場合は、独自の 'Label' デコレータを
                クラスプレフィックスつきで作成し、
                それをプレフィックスパスに追加します。
            </para>

            <para>
                では、独自の Label デコレータを作ってみましょう。
                ここではクラスプレフィックスを "My_Decorator" とします。
                このクラスは、"My/Decorator/Label.php" というファイルで定義されることになります。
            </para>

            <programlisting language="php"><![CDATA[
class My_Decorator_Label extends Zend_Form_Decorator_Abstract
{
    protected $_placement = 'PREPEND';

    public function render($content)
    {
        if (null === ($element = $this->getElement())) {
            return $content;
        }
        if (!method_exists($element, 'getLabel')) {
            return $content;
        }

        $label = $element->getLabel() . ':';

        if (null === ($view = $element->getView())) {
            return $this->renderLabel($content, $label);
        }

        $label = $view->formLabel($element->getName(), $label);

        return $this->renderLabel($content, $label);
    }

    public function renderLabel($content, $label)
    {
        $placement = $this->getPlacement();
        $separator = $this->getSeparator();

        switch ($placement) {
            case 'APPEND':
                return $content . $separator . $label;
            case 'PREPEND':
            default:
                return $label . $separator . $content;
        }
    }
}
]]></programlisting>

            <para>
                では、デコレータを探す際にこのプラグインパスを考慮するように
                要素に指定してみましょう。
            </para>

            <programlisting language="php"><![CDATA[
$element->addPrefixPath('My_Decorator', 'My/Decorator/', 'decorator');
]]></programlisting>

            <para>
                あるいは、フォームレベルでこれを設定してしまうべ、
                すべてのデコレータがこのパスを考慮するようになります。
            </para>

            <programlisting language="php"><![CDATA[
$form->addElementPrefixPath('My_Decorator', 'My/Decorator/', 'decorator');
]]></programlisting>

            <para>
                このパスにデコレータを追加すれば
                'My/Decorator/' にあるデコレータがまず最初に見つけられることになります。
                つまり、'Label' デコレータが必要となる場面ではそのかわりに
                'My_Decorator_Label' が使われることになるわけです。
            </para>
        </example>
    </sect2>

    <sect2 id="zend.form.elements.filters">
        <title>フィルタ</title>

        <para>
            バリデーションの前に、入力の正規化を行えると便利です。
            あるいはそれが必要となることもあるでしょう。
            たとえば、<acronym>HTML</acronym> タグを除去した後の内容を検証したりといった場合です。
            あるいは、入力の前後に含まれるスペースを取り除いてから検証を行わないと
            StringLength バリデータが正しい判断をできないなどという場合もあります。
            これらの操作は
            <classname>Zend_Filter</classname> が行います。
            <classname>Zend_Form_Element</classname> はフィルタチェインをサポートしているので、
            複数のフィルタを順に適用できます。
            フィルタリングは、バリデーションの際や要素の値を <code>getValue()</code>
            で取得する際に行われます。
        </para>

        <programlisting language="php"><![CDATA[
$filtered = $element->getValue();
]]></programlisting>

        <para>
            フィルタをチェインに追加する方法は、次のふたつです。
        </para>

        <itemizedlist>
            <listitem><para>
                フィルタのインスタンスを渡す
            </para></listitem>

            <listitem><para>
                フィルタの名前 (短い名前、あるいは完全なクラス名)
                を渡す
            </para></listitem>
        </itemizedlist>

        <para>
            では、例を見てみましょう。
        </para>

        <programlisting language="php"><![CDATA[
// フィルタのインスタンス
$element->addFilter(new Zend_Filter_Alnum());

// 完全なクラス名
$element->addFilter('Zend_Filter_Alnum');

// 短い形式のフィルタ名
$element->addFilter('Alnum');
$element->addFilter('alnum');
]]></programlisting>

        <para>
            短い形式の名前とは、通常はフィルタ名からプレフィックスを除いた部分のことです。
            デフォルトでは、'Zend_Filter_' を除いた部分を表します。
            また、最初の文字は大文字でも小文字でもかまいません。
        </para>

        <note>
            <title>独自のフィルタクラスの使用</title>

            <para>
                自作のフィルタクラスを使う場合は、
                <code>addPrefixPath()</code> を用いてそれを
                <classname>Zend_Form_Element</classname> に教えます。
                たとえば、'My_Filter' プレフィックス配下のフィルタを使う場合は
                <classname>Zend_Form_Element</classname> に次のように通知します。
            </para>

            <programlisting language="php"><![CDATA[
$element->addPrefixPath('My_Filter', 'My/Filter/', 'filter');
]]></programlisting>

            <para>
                (3 番目の引数が、このアクションを行う際のプラグインローダーであったことを思い出しましょう)
            </para>
        </note>

        <para>
            フィルタリング前の値がほしい場合は
            <code>getUnfilteredValue()</code> メソッドを使用します。
        </para>

        <programlisting language="php"><![CDATA[
$unfiltered = $element->getUnfilteredValue();
]]></programlisting>

        <para>
            フィルタについての詳細な情報は <link
                linkend="zend.filter.introduction">Zend_Filter
                のドキュメント</link> を参照ください。
        </para>

        <para>
            フィルタ関係のメソッドを以下にまとめます。
        </para>

        <itemizedlist>
            <listitem><para>
                <code>addFilter($nameOfFilter, array $options = null)</code>
            </para></listitem>

            <listitem><para>
                <code>addFilters(array $filters)</code>
            </para></listitem>

            <listitem><para>
                <code>setFilters(array $filters)</code> (すべてのフィルタを上書きします)
            </para></listitem>

            <listitem><para>
                <code>getFilter($name)</code> (指定した名前のフィルタオブジェクトを取得します)
            </para></listitem>

            <listitem><para>
                <code>getFilters()</code> (すべてのフィルタを取得します)
            </para></listitem>

            <listitem><para>
                <code>removeFilter($name)</code> (指定した名前のフィルタを削除します)
            </para></listitem>

            <listitem><para>
                <code>clearFilters()</code> (すべてのフィルタを削除します)
            </para></listitem>
        </itemizedlist>
    </sect2>

    <sect2 id="zend.form.elements.validators">
        <title>バリデータ</title>

        <para>
            セキュリティ界で有名なお言葉 "入力はフィルタリングせよ。
            出力はエスケープせよ。" に賛同する人なら、フォームの入力を検証
            ("入力のフィルタリング") したくなるでしょう。
            <classname>Zend_Form</classname> では、各要素が個別にバリデータチェインを保持しています。
            これは <classname>Zend_Validate_*</classname> のバリデータでできています。
        </para>

        <para>
            バリデータをチェインに追加する方法は、次のふたつです。
        </para>

        <itemizedlist>
            <listitem><para>
                バリデータのインスタンスを渡す
            </para></listitem>

            <listitem><para>
                短いフィルタ名を渡す
            </para></listitem>
        </itemizedlist>

        <para>
            では、例を見てみましょう。
        </para>

        <programlisting language="php"><![CDATA[
// バリデータのインスタンス
$element->addValidator(new Zend_Validate_Alnum());

// 短い形式の名前
$element->addValidator('Alnum');
$element->addValidator('alnum');
]]></programlisting>

        <para>
            短い形式の名前とは、通常はバリデータ名からプレフィックスを除いた部分のことです。
            デフォルトでは、バリデータ名から 'Zend_Validate_' を除いた部分を表します。
            また、最初の文字は大文字でも小文字でもかまいません。
        </para>

        <note>
            <title>独自のバリデータクラスの使用</title>

            <para>
                自作のバリデータクラスを使う場合は、
                <code>addPrefixPath()</code> を用いてそれを
                <classname>Zend_Form_Element</classname> に教えます。
                たとえば、'My_Validator' プレフィックス配下のバリデータを使う場合は
                <classname>Zend_Form_Element</classname> に次のように通知します。
            </para>

            <programlisting language="php"><![CDATA[
$element->addPrefixPath('My_Validator', 'My/Validator/', 'validate');
]]></programlisting>

            <para>
                (3 番目の引数が、このアクションを行う際のプラグインローダーであったことを思い出しましょう)
            </para>
        </note>

        <para>
            どれかひとつのバリデーションに失敗したときに
            それ以降のバリデータを実行しないようにさせるには、2 番目のパラメータに
            <constant>TRUE</constant> を渡します。
        </para>

        <programlisting language="php"><![CDATA[
$element->addValidator('alnum', true);
]]></programlisting>

        <para>
            バリデータの名前を指定して追加する場合で
            そのバリデータクラスのコンストラクタが引数を受け付ける場合は、
            <code>addValidator()</code> の 3 番目のパラメータに配列形式で指定します。
        </para>

        <programlisting language="php"><![CDATA[
$element->addValidator('StringLength', false, array(6, 20));
]]></programlisting>

        <para>
            この方式で引数を渡す場合は、コンストラクタで定義されているとおりの順で指定する必要があります。
            上の例では、<classname>Zend_Validate_StringLenth</classname>
            クラスのインスタンスを作成する際にパラメータ
            <code>$min</code> と <code>$max</code> を指定しています。
        </para>

        <programlisting language="php"><![CDATA[
$validator = new Zend_Validate_StringLength(6, 20);
]]></programlisting>

        <note>
            <title>独自のバリデートエラーメッセージの指定</title>

            <para>
                バリデータのエラーメッセージをカスタマイズしたいこともあるでしょう。
                その場合は、<methodname>Zend_Form_Element::addValidator()</methodname> の引数
                <code>$options</code> で、キー 'messages' にメッセージテンプレートを指定します。
                これは キー/値 のペアの配列となります。
                これを使用するには、そのバリデータのさまざまな検証エラーに対応する
                エラーコードを知っておく必要があります。
            </para>

            <para>
                もっとよいやりかたは、<classname>Zend_Translate_Adapter</classname>
                をフォームで使用することでしょう。エラーコードは、
                デフォルトのエラーデコレータが自動的にアダプタに渡します。
                そこで、バリデータのエラーコードに対応する翻訳文字列を設定すればいいのです。
            </para>
        </note>

        <para>
            複数のバリデータを一度に設定するには
            <code>addValidators()</code> を使用します。
            このメソッドには、配列の配列を渡します。
            各配列の要素は 1 から 3 となり、これが
            <code>addValidator()</code> に渡されます。
        </para>

        <programlisting language="php"><![CDATA[
$element->addValidators(array(
    array('NotEmpty', true),
    array('alnum'),
    array('stringLength', false, array(6, 20)),
));
]]></programlisting>

        <para>
            もうすこし詳しくはっきりと書きたい場合は、キー
            'validator'、'breakChainOnFailure' そして 'options'
            を持つ配列を使用することもできます。
        </para>

        <programlisting language="php"><![CDATA[
$element->addValidators(array(
    array(
        'validator'           => 'NotEmpty',
        'breakChainOnFailure' => true),
    array('validator' => 'alnum'),
    array(
        'validator' => 'stringLength',
        'options'   => array(6, 20)),
));
]]></programlisting>

        <para>
            この使用法は、設定ファイルを用いてバリデータを設定する場合に便利です。
        </para>

        <programlisting language="ini"><![CDATA[
element.validators.notempty.validator = "NotEmpty"
element.validators.notempty.breakChainOnFailure = true
element.validators.alnum.validator = "Alnum"
element.validators.strlen.validator = "StringLength"
element.validators.strlen.options.min = 6
element.validators.strlen.options.max = 20
]]></programlisting>

        <para>
            それが必要か否かにかかわらず、すべての項目がキーを持つことに注意しましょう。
            これは、設定ファイルを使用する場合の制限事項となります。
            しかし、これにより、その引数がどういう意味なのかをきちんと明示できるようになります。
            バリデータのオプションは、正しい順で指定しなければならないことに注意しましょう。
        </para>

        <para>
            要素を検証するには、その値を
            <code>isValid()</code> に渡します。
        </para>

        <programlisting language="php"><![CDATA[
if ($element->isValid($value)) {
    // 有効
} else {
    // 無効
}
]]></programlisting>

        <note>
            <title>フィルタリング後の値の検証</title>

            <para>
                <methodname>Zend_Form_Element::isValid()</methodname> は、
                フィルタチェインを通した後の値を検証します。
                詳細は <link
                linkend="zend.form.elements.filters">フィルタの説明
                </link> を参照ください。
            </para>
        </note>

        <note>
            <title>バリデーションコンテキスト</title>

            <para>
                <methodname>Zend_Form_Element::isValid()</methodname> は、
                追加の引数 <code>$context</code> をサポートしています。
                <methodname>Zend_Form::isValid()</methodname> は、
                フォームをバリデートする際にデータの配列を
                <code>$context</code> に渡します。一方、
                <methodname>Zend_Form_Element::isValid()</methodname>
                はそれを個々のバリデータに渡します。
                つまり、他の要素に渡された内容を使用するバリデータも作成できるということです。
                たとえば、パスワードの確認用の入力欄を持つ登録フォームを考えてみましょう。
                この場合、「パスワード」欄と「パスワード (確認)」
                欄の内容が一致するかどうかを確認することになります。
                このようなバリデータは、次のように書きます。
            </para>

            <programlisting language="php"><![CDATA[
class My_Validate_PasswordConfirmation extends Zend_Validate_Abstract
{
    const NOT_MATCH = 'notMatch';

    protected $_messageTemplates = array(
        self::NOT_MATCH => 'パスワード (確認) の内容がパスワードと一致しません'
    );

    public function isValid($value, $context = null)
    {
        $value = (string) $value;
        $this->_setValue($value);

        if (is_array($context)) {
            if (isset($context['password_confirm'])
                && ($value == $context['password_confirm']))
            {
                return true;
            }
        } elseif (is_string($context) && ($value == $context)) {
            return true;
        }

        $this->_error(self::NOT_MATCH);
        return false;
    }
}
]]></programlisting>
        </note>

        <para>
            バリデータは、順番どおりに処理されます。
            すべてのバリデータが実行されますが、
            <varname>$breakChainOnFailure</varname> が true
            の場合はどれかひとつのバリデータが検証に失敗した時点で処理を終了します。
            バリデータは、適切な順で指定するようにしましょう。
        </para>

        <para>
            検証に失敗したときは、バリデータチェインから
            エラーコードとメッセージを取得できます。
        </para>

        <programlisting language="php"><![CDATA[
$errors   = $element->getErrors();
$messages = $element->getMessages();
]]></programlisting>

        <para>
            (注意: 返されるエラーメッセージは連想配列形式で、
            エラーコードとエラーメッセージのペアとなります)
        </para>

        <para>
            バリデータに加えて、ある要素が必須である場合は
            <methodname>setRequired($flag)</methodname> を使用できます。
            デフォルトではこのフラグは <constant>FALSE</constant> です。
            <!-- TODO : to be translated -->
            In combination with
            <methodname>setAllowEmpty($flag)</methodname> (<constant>TRUE</constant>
            by default) and <methodname>setAutoInsertNotEmptyValidator($flag)</methodname>
            (<constant>TRUE</constant> by default), the behavior of your validator chain
            can be modified in a number of ways:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    Using the defaults, validating an Element without passing a value, or
                    passing an empty string for it, skips all validators and validates to
                    <constant>TRUE</constant>.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>setAllowEmpty(false)</methodname> leaving the two other
                    mentioned flags untouched, will validate against the validator chain
                    you defined for this Element, regardless of the value passed
                    to <methodname>isValid()</methodname>.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>setRequired(true)</methodname> leaving the two other
                    mentioned flags untouched, will add a 'NotEmpty' validator
                    on top of the validator chain (if none was already set)), with the
                     <varname>$breakChainOnFailure</varname> flag set.
                    これにより、必須フラグがその意味どおりに動作するようになります。
                    入力が渡されなかった場合は検証がその時点で失敗し、
                    結果をユーザに返します。それ以降のバリデータは実行されません。
                    値が空である時点で無効な内容であることが確定しているからです。
                </para>

                <para>
                    この振る舞いが気に入らない場合は、
                    <code>setAutoInsertNotEmptyValidator($flag)</code>
                    に <constant>FALSE</constant> を渡せばこの機能を無効にできます。
                    この場合、 <code>isValid()</code>
                    がバリデータチェインに勝手に
                    'NotEmpty' バリデータを追加することはなくなります。
                </para>
            </listitem>
        </itemizedlist>

        <para>
            バリデータについての詳細な情報は <link
                linkend="zend.validate.introduction">Zend_Validate
                のドキュメント</link> を参照ください。
        </para>

        <note>
            <title>Zend_Form_Elements の汎用バリデータとしての使用法</title>

            <para>
                <classname>Zend_Form_Element</classname> は
                <classname>Zend_Validate_Interface</classname> を実装しています。
                つまり、フォーム以外のバリデータチェインでも
                フォーム要素を使用できるということです。
            </para>
        </note>

        <!-- TODO : to be translated -->
        <note>
            <title>When is an element detected as empty?</title>

            <para>
                As mentioned the 'NotEmpty' validator is used to detect if an element is empty
                or not. But <classname>Zend_Validate_NotEmpty</classname> does, per default, not
                work like <acronym>PHP</acronym>'s method <methodname>empty()</methodname>.
            </para>

            <para>
                This means when an element contains an integer <emphasis>0</emphasis> or an string
                <emphasis>'0'</emphasis> then the element will be seen as not empty. If you want to
                have a different behaviour you must create your own instance of
                <classname>Zend_Validate_NotEmpty</classname>. There you can define the behaviour of
                this validator. See <ulink
                    url="zend.validate.set.notempty">Zend_Validate_NotEmpty</ulink> for details.
            </para>
        </note>

        <para>
            検証関係のメソッドを以下にまとめます。
        </para>

        <itemizedlist>
            <listitem><para>
                    <code>setRequired($flag)</code> および
                    <code>isRequired()</code> は、'required' フラグの状態を設定あるいは取得します。
                    これを <constant>TRUE</constant> に設定すると、
                    <classname>Zend_Form</classname> が処理したデータにその要素が必須であるものとします。
            </para></listitem>

            <listitem><para>
                    <code>setAllowEmpty($flag)</code> および
                    <code>getAllowEmpty()</code> は、オプション要素
                    (required フラグが <constant>FALSE</constant> に設定されている要素)
                    の挙動を変更します。'allow empty' フラグが <constant>TRUE</constant> の場合、
                    値が未入力のときはバリデータチェインに渡しません。
            </para></listitem>

            <listitem><para>
                    <code>setAutoInsertNotEmptyValidator($flag)</code> は、
                    その要素が必須項目であるときに
                    'NotEmpty' バリデータをバリデータチェインの先頭に追加するかどうかを指定します。
                    デフォルトでは、このフラグは <constant>TRUE</constant> です。
            </para></listitem>

            <listitem><para>
                <methodname>addValidator($nameOrValidator, $breakChainOnFailure = false, array $options = null)</methodname>
            </para></listitem>

            <listitem><para>
                <methodname>addValidators(array $validators)</methodname>
            </para></listitem>

            <listitem><para>
                <methodname>setValidators(array $validators)</methodname> (すべてのバリデータを上書きします)
            </para></listitem>

            <listitem><para>
                <methodname>getValidator($name)</methodname> (指定した名前のバリデータオブジェクトを取得します)
            </para></listitem>

            <listitem><para>
                <methodname>getValidators()</methodname> (すべてのバリデータを取得します)
            </para></listitem>

            <listitem><para>
                <methodname>removeValidator($name)</methodname> (指定した名前のバリデータを削除します)
            </para></listitem>

            <listitem><para>
                <methodname>clearValidators()</methodname> (すべてのバリデータを削除します)
            </para></listitem>
        </itemizedlist>

        <sect3 id="zend.form.elements.validators.errors">
            <title>独自のエラーメッセージ</title>

            <para>
                時には、要素にアタッチされたバリデータが生成するエラーメッセージではなく
                独自のエラーメッセージを指定したくなることもあるでしょう。
                さらに、時には自分自身でフォームを無効だとマークしたいこともあるでしょう。
                1.6.0 以降、次のメソッドでこの機能を使用できるようになりました。
            </para>

            <itemizedlist>
                <listitem><para>
                    <code>addErrorMessage($message)</code>:
                    フォームの検証エラーの際に表示するエラーメッセージを追加します。
                    複数回コールすると、新しいメッセージはスタックに追加されます。
                </para></listitem>

                <listitem><para>
                    <code>addErrorMessages(array $messages)</code>:
                    フォームの検証エラーの際に表示する複数のエラーメッセージを追加します。
                </para></listitem>

                <listitem><para>
                    <code>setErrorMessages(array $messages)</code>:
                    フォームの検証エラーの際に表示する複数のエラーメッセージを追加します。
                    それまでに設定されていたすべてのメッセージを上書きします。
                </para></listitem>

                <listitem><para>
                    <code>getErrorMessages()</code>:
                    定義済みのカスタムエラーメッセージの一覧を取得します。
                </para></listitem>

                <listitem><para>
                    <code>clearErrorMessages()</code>:
                    定義済みのカスタムエラーメッセージをすべて削除します。
                </para></listitem>

                <listitem><para>
                    <code>markAsError()</code>:
                    検証に失敗したものとしてフォームにマークします。
                </para></listitem>

                <listitem><para>
                    <code>hasErrors()</code>:
                    要素が、検証失敗か無効とマークのいずれかの状態になっているかどうかを取得します。
                </para></listitem>

                <listitem><para>
                    <code>addError($message)</code>:
                    エラーメッセージをカスタムエラーメッセージスタックに追加し、
                    要素を無効とマークします。
                </para></listitem>

                <listitem><para>
                    <code>addErrors(array $messages)</code>:
                    複数のエラーメッセージをカスタムエラーメッセージスタックに追加し、
                    要素を無効とマークします。
                </para></listitem>

                <listitem><para>
                    <code>setErrors(array $messages)</code>:
                    指定したメッセージでカスタムエラーメッセージスタックを上書きし、
                    要素を無効とマークします。
                </para></listitem>
            </itemizedlist>

            <para>
                この方式で設定したすべてのエラーは翻訳されることになります。
                さらに、プレースホルダ "%value%" を使用して要素の値を表すこともできます。
                エラーメッセージを取得する際に、この部分が現在の要素の値に置き換えられます。
            </para>
        </sect3>
    </sect2>

    <sect2 id="zend.form.elements.decorators">
        <title>デコレータ</title>

        <para>
            多くのウェブ開発者にとって、<acronym>XHTML</acronym>
            のフォームを作成することは悩みの種です。
            フォームの要素ひとつひとつに対して
            ラベルなどのマークアップが必要ですし、
            ユーザの使いやすさを考慮して検証エラーメッセージも表示させなければなりません。
            要素の数が増えれば増えるほど、この作業量は無視できなくなります。
        </para>

        <para>
            <classname>Zend_Form_Element</classname> は、この問題を解決するために
            "デコレータ" を使用します。デコレータは、
            要素にアクセスしてその中身をレンダリングするためのメソッドを持つクラスです。
            デコレータの動作原理については、<link
                linkend="zend.form.decorators">Zend_Form_Decorator</link>
            のセクションを参照ください。
        </para>

        <para>
            <classname>Zend_Form_Element</classname> がデフォルトで使用するデコレータは次のとおりです。
        </para>

        <itemizedlist>
            <listitem><para>
                <emphasis>ViewHelper</emphasis>: 要素のレンダリング用のビューヘルパーを指定します。
                要素の 'helper' 属性を使用して、どのヘルパーを使用するのかを指定します。
                デフォルトで <classname>Zend_Form_Element</classname> は
                'formText' ビューヘルパーを使用しますが、
                サブクラスで別のヘルパーを指定することもできます。
            </para></listitem>

            <listitem><para>
                <emphasis>Errors</emphasis>:
                <classname>Zend_View_Helper_FormErrors</classname>
                を用いて要素の後にエラーメッセージを追加します。
                エラーが発生していない場合は何も行いません。
            </para></listitem>

            <listitem><para>
                <emphasis>Description</emphasis>: 要素の後に説明を追加します。
                説明が存在しない場合は何も追加されません。デフォルトでは、
                クラス 'description' を指定した &lt;p&gt; タグでレンダリングされます。
            </para></listitem>

            <listitem><para>
                <emphasis>HtmlTag</emphasis>:
                ラベルや要素、そしてエラーメッセージを <acronym>HTML</acronym> の
                &lt;dd&gt; タグで囲みます。
            </para></listitem>

            <listitem><para>
                <emphasis>Label</emphasis>:
                <classname>Zend_View_Helper_FormLabel</classname>
                を用いて要素の前にラベルを追加し、それを
                &lt;dt&gt; タグで囲みます。
                ラベルが存在しない場合は、用語定義タグのみをレンダリングします。
            </para></listitem>
        </itemizedlist>

        <note>
            <title>読み込み不要なデフォルトのデコレータ</title>

            <para>
                デフォルトのデコレータは、
                オブジェクトの初期化時に読み込まれるようになっています。
                この機能を無効にするには、コンストラクタでオプション
                'disableLoadDefaultDecorators' を指定します。
            </para>

            <programlisting language="php"><![CDATA[
$element = new Zend_Form_Element('foo',
                                 array('disableLoadDefaultDecorators' =>
                                      true)
                                );
]]></programlisting>

            <para>
                このオプションは、他のオプションと混用することもできます。
                その場合はオプションの配列や <classname>Zend_Config</classname>
                オブジェクトを使用します。
            </para>
        </note>

        <para>
            デコレータの実行順序は登録された順によって決まります。
            つまり、最初に登録したデコレータから順に実行することになります。
            したがって、デコレータを登録するときにはその順番に気をつけなければなりません。
            あるいは、placement オプションを明示的に指定して順序を決めることもできます。
            例として、デフォルトのデコレータを登録するコードを示します。
        </para>

        <programlisting language="php"><![CDATA[
$this->addDecorators(array(
    array('ViewHelper'),
    array('Errors'),
    array('Description', array('tag' => 'p', 'class' => 'description')),
    array('HtmlTag', array('tag' => 'dd')),
    array('Label', array('tag' => 'dt')),
));
]]></programlisting>

        <para>
            最初のコンテンツを作成するのは 'ViewHelper'
            デコレータで、これはフォーム要素そのものを作成します。
            次に 'Errors' デコレータがその要素のエラーメッセージを取得し、
            もしエラーが発生していた場合はそれをビューヘルパー
            'FormErrors' に渡してレンダリングさせます。
            説明が存在する場合は、'Description' デコレータがクラス 'description'
            の段落を追加します。ここには、そのコンテンツの内容を説明するテキストが書き込まれます。
            その次のデコレータである 'HtmlTag' は、要素とエラーと説明文を
            <acronym>HTML</acronym> の &lt;dd&gt; タグで囲みます。最後に、'label'
            が要素のラベルを取得します。それをビューヘルパー 'FormLabel'
            に渡し、<acronym>HTML</acronym> の &lt;dt&gt; で囲みます。
            ラベルの内容は、デフォルトでコンテンツの前に付加されます。
            出力結果は、基本的にはこのようになります。
        </para>

        <programlisting language="html"><![CDATA[
<dt><label for="foo" class="optional">Foo</label></dt>
<dd>
    <input type="text" name="foo" id="foo" value="123" />
    <ul class="errors">
        <li>"123" is not an alphanumeric value</li>
    </ul>
    <p class="description">
        This is some descriptive text regarding the element.
    </p>
</dd>
]]></programlisting>

        <para>
            デコレータについての詳細な情報は <link
                linkend="zend.form.decorators">Zend_Form_Decorator
                のセクション</link> を参照ください。
        </para>

        <note>
            <title>同じ型の複数のデコレータの使用法</title>

            <para>
                内部的には、<classname>Zend_Form_Element</classname>
                はデコレータのクラス名をもとにしてデコレータを取得しています。
                つまり、同じ型のデコレータを複数登録することはできないということです。
                複数回登録すると、それまでに登録されていたデコレータを上書きします。
            </para>

            <para>
                これを回避するには、<emphasis>エイリアス</emphasis> を使用します。
                デコレータやデコレータ名を <code>addDecorator()</code>
                の最初の引数として渡すのではなく、ひとつの要素からなる配列を渡します。
                この配列には、デコレータオブジェクトあるいはデコレータ名を指すエイリアスを指定します。
            </para>

            <programlisting language="php"><![CDATA[
// 'FooBar' へのエイリアス
$element->addDecorator(array('FooBar' => 'HtmlTag'),
                       array('tag' => 'div'));

// 後で、このように取得できます
$decorator = $element->getDecorator('FooBar');
]]></programlisting>

            <para>
                <code>addDecorators()</code> メソッドおよび
                <code>setDecorators()</code> メソッドでは、
                デコレータを表す配列を 'decorator' オプションに渡す必要があります。
            </para>

            <programlisting language="php"><![CDATA[
// ふたつの 'HtmlTag' デコレータを使用するため、片方に 'FooBar' というエイリアスを指定します
$element->addDecorators(
    array('HtmlTag', array('tag' => 'div')),
    array(
        'decorator' => array('FooBar' => 'HtmlTag'),
        'options' => array('tag' => 'dd')
    ),
);

// 後で、このように取得できます
$htmlTag = $element->getDecorator('HtmlTag');
$fooBar  = $element->getDecorator('FooBar');
]]></programlisting>
        </note>

        <para>
            デコレータ関連のメソッドを以下にまとめます。
        </para>

        <itemizedlist>
            <listitem><para>
                <code>addDecorator($nameOrDecorator, array $options = null)</code>
            </para></listitem>

            <listitem><para>
                <code>addDecorators(array $decorators)</code>
            </para></listitem>

            <listitem><para>
                <code>setDecorators(array $decorators)</code> (すべてのデコレータを上書きします)
            </para></listitem>

            <listitem><para>
                <code>getDecorator($name)</code> (指定した名前のデコレータオブジェクトを取得します)
            </para></listitem>

            <listitem><para>
                <code>getDecorators()</code> (すべてのデコレータを取得します)
            </para></listitem>

            <listitem><para>
                <code>removeDecorator($name)</code> (指定した名前のデコレータを削除します)
            </para></listitem>

            <listitem><para>
                <code>clearDecorators()</code> (すべてのデコレータを削除します)
            </para></listitem>
        </itemizedlist>

        <para>
            <classname>Zend_Form_Element</classname> は、
            オーバーロードを使用して特定のデコレータをレンダリングすることもできます。
            'render' で始まる名前のメソッドを <code>__call()</code>
            で捕捉し、メソッド名の残りの部分にもとづいてデコレータを探します。
            見つかった場合は、そのデコレータ
            <emphasis>だけ</emphasis> をレンダリングします。
            引数を渡すと、それがデコレータの
            <code>render()</code> メソッドにコンテンツとして渡されます。次の例を参照ください。
        </para>

        <programlisting language="php"><![CDATA[
// ViewHelper デコレータのみをレンダリングします
echo $element->renderViewHelper();

// HtmlTag デコレータにコンテンツを渡してレンダリングします
echo $element->renderHtmlTag("This is the html tag content");
]]></programlisting>

        <para>
            デコレータが存在しない場合は、例外が発生します。
        </para>
    </sect2>

    <sect2 id="zend.form.elements.metadata">
        <title>メタデータおよび属性</title>

        <para>
            <classname>Zend_Form_Element</classname> は、
            要素の属性やメタデータを処理できます。
            基本的な属性には次のようなものがあります。
        </para>

        <itemizedlist>
            <listitem><para>
                <emphasis>name</emphasis>:
                要素名。
                <code>setName()</code> および <code>getName()</code>
                でアクセスします。
            </para></listitem>

            <listitem><para>
                <emphasis>label</emphasis>:
                要素のラベル。
                <code>setLabel()</code> および <code>getLabel()</code>
                でアクセスします。
            </para></listitem>

            <listitem><para>
                <emphasis>order</emphasis>:
                要素がフォーム内で登場する際のインデックス。
                <code>setOrder()</code> および
                <code>getOrder()</code> でアクセスします。
            </para></listitem>

            <listitem><para>
                <emphasis>value</emphasis>:
                現在の要素の値。
                <code>setValue()</code> および <code>getValue()</code>
                でアクセスします。
            </para></listitem>

            <listitem><para>
                <emphasis>description</emphasis>: 要素の説明。
                ツールチップや javascript のコンテキストヒントで用いられるもので、
                その要素の使用目的などを説明します。
                <code>setDescription()</code> および <code>getDescription()</code>
                でアクセスします。
            </para></listitem>

            <listitem><para>
                <emphasis>required</emphasis>:
                バリデーション時にその要素を必須とみなすかどうか。
                <code>setRequired()</code> および <code>isRequired()</code>
                でアクセスします。このフラグはデフォルトでは <constant>FALSE</constant> です。
            </para></listitem>

            <listitem><para>
                <emphasis>allowEmpty</emphasis>:
                必須でない (オプションの) 要素が未入力のときに検証を行うかどうか。
                このフラグが <constant>TRUE</constant> で required フラグが <constant>FALSE</constant> の場合は、
                値が未入力ならバリデータチェインにその要素を渡さず、
                検証に成功したものとみなします。
                <code>setAllowEmpty()</code> および <code>getAllowEmpty()</code>
                でアクセスします。このフラグはデフォルトでは <constant>TRUE</constant> です。
            </para></listitem>

            <listitem><para>
                <emphasis>autoInsertNotEmptyValidator</emphasis>:
                要素が必須であるときに 'NotEmpty' バリデータを追加するかどうかを表すフラグ。
                デフォルトではこのフラグは <constant>TRUE</constant> です。フラグを設定するには
                <code>setAutoInsertNotEmptyValidator($flag)</code>、
                値を調べるには <code>autoInsertNotEmptyValidator()</code> を使用します。
            </para></listitem>
        </itemizedlist>

        <para>
            フォームの要素の中にはメタデータを要するものもあります。たとえば
            <acronym>XHTML</acronym> のフォーム要素では、class や id といった属性を指定することになるでしょう。
            これは、次のメソッドで行います。
        </para>

        <itemizedlist>
            <listitem><para>
                <emphasis>setAttrib($name, $value)</emphasis>: 属性を追加します。
            </para></listitem>

            <listitem><para>
                <emphasis>setAttribs(array $attribs)</emphasis>:
                addAttribs() と似ていますが、すべて上書きします。
            </para></listitem>

            <listitem><para>
                <emphasis>getAttrib($name)</emphasis>:
                特定の属性の値を取得します。
            </para></listitem>

            <listitem><para>
                <emphasis>getAttribs()</emphasis>:
                すべての属性を キー/値 のペアで取得します。
            </para></listitem>
        </itemizedlist>

        <para>
            しかし、たいていの場合はもっとシンプルにオブジェクトのプロパティとしてアクセスすることになるでしょう。
            <classname>Zend_Form_Element</classname> はオーバーロードを使用してこの機能を実現しています。
        </para>

        <programlisting language="php"><![CDATA[
// $element->setAttrib('class', 'text') と同じ意味です
$element->class = 'text;
]]></programlisting>

        <para>
            デフォルトでは、すべての属性がビューヘルパーに渡され、
            要素の描画時に使用します。これらの属性は、要素タグの
            <acronym>HTML</acronym> 属性として設定されます。
        </para>
    </sect2>

    <sect2 id="zend.form.elements.standard">
        <title>標準の要素</title>

        <para>
            <classname>Zend_Form</classname> には、標準的な要素が同梱されています。詳細は
            <link linkend="zend.form.standardElements">標準要素</link>
            の章を参照ください。
        </para>
    </sect2>

    <sect2 id="zend.form.elements.methods">
        <title>Zend_Form_Element のメソッド</title>

        <para>
            <classname>Zend_Form_Element</classname> には非常にたくさんのメソッドがあります。
            以下に、それらのシグネチャを種類別に分けて簡単にまとめました。
        </para>

        <itemizedlist>
            <listitem><para>設定</para>
                <itemizedlist>
                    <listitem><para><methodname>setOptions(array $options)</methodname></para></listitem>
                    <listitem><para><methodname>setConfig(Zend_Config $config)</methodname></para></listitem>
                </itemizedlist>
            </listitem>

            <listitem><para>I18n</para>
                <itemizedlist>
                    <listitem><para><methodname>setTranslator(Zend_Translate_Adapter $translator = null)</methodname></para></listitem>
                    <listitem><para><methodname>getTranslator()</methodname></para></listitem>
                    <listitem><para><methodname>setDisableTranslator($flag)</methodname></para></listitem>
                    <listitem><para><methodname>translatorIsDisabled()</methodname></para></listitem>
                </itemizedlist>
            </listitem>

            <listitem><para>プロパティ</para>
                <itemizedlist>
                    <listitem><para><methodname>setName($name)</methodname></para></listitem>
                    <listitem><para><methodname>getName()</methodname></para></listitem>
                    <listitem><para><methodname>setValue($value)</methodname></para></listitem>
                    <listitem><para><methodname>getValue()</methodname></para></listitem>
                    <listitem><para><methodname>getUnfilteredValue()</methodname></para></listitem>
                    <listitem><para><methodname>setLabel($label)</methodname></para></listitem>
                    <listitem><para><methodname>getLabel()</methodname></para></listitem>
                    <listitem><para><methodname>setDescription($description)</methodname></para></listitem>
                    <listitem><para><methodname>getDescription()</methodname></para></listitem>
                    <listitem><para><methodname>setOrder($order)</methodname></para></listitem>
                    <listitem><para><methodname>getOrder()</methodname></para></listitem>
                    <listitem><para><methodname>setRequired($flag)</methodname></para></listitem>
                    <listitem><para><methodname>isRequired()</methodname></para></listitem>
                    <listitem><para><methodname>setAllowEmpty($flag)</methodname></para></listitem>
                    <listitem><para><methodname>getAllowEmpty()</methodname></para></listitem>
                    <listitem><para><methodname>setAutoInsertNotEmptyValidator($flag)</methodname></para></listitem>
                    <listitem><para><methodname>autoInsertNotEmptyValidator()</methodname></para></listitem>
                    <listitem><para><methodname>setIgnore($flag)</methodname></para></listitem>
                    <listitem><para><methodname>getIgnore()</methodname></para></listitem>
                    <listitem><para><methodname>getType()</methodname></para></listitem>
                    <listitem><para><methodname>setAttrib($name, $value)</methodname></para></listitem>
                    <listitem><para><methodname>setAttribs(array $attribs)</methodname></para></listitem>
                    <listitem><para><methodname>getAttrib($name)</methodname></para></listitem>
                    <listitem><para><methodname>getAttribs()</methodname></para></listitem>
                </itemizedlist>
            </listitem>

            <listitem><para>プラグインローダーとパス</para>
                <itemizedlist>
                    <listitem><para><methodname>setPluginLoader(Zend_Loader_PluginLoader_Interface $loader, $type)</methodname></para></listitem>
                    <listitem><para><methodname>getPluginLoader($type)</methodname></para></listitem>
                    <listitem><para><methodname>addPrefixPath($prefix, $path, $type = null)</methodname></para></listitem>
                    <listitem><para><methodname>addPrefixPaths(array $spec)</methodname></para></listitem>
                </itemizedlist>
            </listitem>

            <listitem><para>検証</para>
                <itemizedlist>
                    <listitem><para><methodname>addValidator($validator, $breakChainOnFailure = false, $options = array())</methodname></para></listitem>
                    <listitem><para><methodname>addValidators(array $validators)</methodname></para></listitem>
                    <listitem><para><methodname>setValidators(array $validators)</methodname></para></listitem>
                    <listitem><para><methodname>getValidator($name)</methodname></para></listitem>
                    <listitem><para><methodname>getValidators()</methodname></para></listitem>
                    <listitem><para><methodname>removeValidator($name)</methodname></para></listitem>
                    <listitem><para><methodname>clearValidators()</methodname></para></listitem>
                    <listitem><para><methodname>isValid($value, $context = null)</methodname></para></listitem>
                    <listitem><para><methodname>getErrors()</methodname></para></listitem>
                    <listitem><para><methodname>getMessages()</methodname></para></listitem>
                </itemizedlist>
            </listitem>

            <listitem><para>フィルタ</para>
                <itemizedlist>
                    <listitem><para><methodname>addFilter($filter, $options = array())</methodname></para></listitem>
                    <listitem><para><methodname>addFilters(array $filters)</methodname></para></listitem>
                    <listitem><para><methodname>setFilters(array $filters)</methodname></para></listitem>
                    <listitem><para><methodname>getFilter($name)</methodname></para></listitem>
                    <listitem><para><methodname>getFilters()</methodname></para></listitem>
                    <listitem><para><methodname>removeFilter($name)</methodname></para></listitem>
                    <listitem><para><methodname>clearFilters()</methodname></para></listitem>
                </itemizedlist>
            </listitem>

            <listitem><para>レンダリング</para>
                <itemizedlist>
                    <listitem><para><methodname>setView(Zend_View_Interface $view = null)</methodname></para></listitem>
                    <listitem><para><methodname>getView()</methodname></para></listitem>
                    <listitem><para><methodname>addDecorator($decorator, $options = null)</methodname></para></listitem>
                    <listitem><para><methodname>addDecorators(array $decorators)</methodname></para></listitem>
                    <listitem><para><methodname>setDecorators(array $decorators)</methodname></para></listitem>
                    <listitem><para><methodname>getDecorator($name)</methodname></para></listitem>
                    <listitem><para><methodname>getDecorators()</methodname></para></listitem>
                    <listitem><para><methodname>removeDecorator($name)</methodname></para></listitem>
                    <listitem><para><methodname>clearDecorators()</methodname></para></listitem>
                    <listitem><para><methodname>render(Zend_View_Interface $view = null)</methodname></para></listitem>
                </itemizedlist>
            </listitem>
        </itemizedlist>
    </sect2>

    <sect2 id="zend.form.elements.config">
        <title>設定</title>

        <para>
            <classname>Zend_Form_Element</classname> のコンストラクタには、配列あるいは
            <classname>Zend_Config</classname> オブジェクトでオプションを指定できます。
            また、<methodname>setOptions()</methodname> や
            <methodname>setConfig()</methodname> で設定を変更することもできます。
            一般に、キーの名前は次のようになります。
        </para>

        <itemizedlist>
            <listitem><para>
                'set' + キーの名前のメソッドが <classname>Zend_Form_Element</classname>
                にあれば、値をそのメソッドに渡します。
            </para></listitem>

            <listitem><para>
                それ以外の場合は、属性を使用して値を設定します。
            </para></listitem>
        </itemizedlist>

        <para>
            このルールには、次のような例外があります。
        </para>

        <itemizedlist>
            <listitem><para>
                <property>prefixPath</property> は
                <methodname>addPrefixPaths()</methodname> に渡されます。
            </para></listitem>

            <listitem>
                <para>
                    以下のセッターはこの方式では設定できません。
                </para>

                <itemizedlist>
                    <listitem><para>
                            <property>setAttrib</property> (ただし、
                            <property>setAttribs</property> は
                            <emphasis>動作します</emphasis>)
                    </para></listitem>

                    <listitem><para><property>setConfig</property></para></listitem>

                    <listitem><para><property>setOptions</property></para></listitem>

                    <listitem><para><property>setPluginLoader</property></para></listitem>

                    <listitem><para><property>setTranslator</property></para></listitem>

                    <listitem><para><property>setView</property></para></listitem>
                </itemizedlist>
            </listitem>
        </itemizedlist>

        <para>
            例として、すべての型の設定データを渡すファイルを見てみましょう。
        </para>

        <programlisting language="ini"><![CDATA[
[element]
name = "foo"
value = "foobar"
label = "Foo:"
order = 10
required = true
allowEmpty = false
autoInsertNotEmptyValidator = true
description = "Foo elements are for examples"
ignore = false
attribs.id = "foo"
attribs.class = "element"
; sets 'onclick' attribute
onclick = "autoComplete(this, '/form/autocomplete/element')"
prefixPaths.decorator.prefix = "My_Decorator"
prefixPaths.decorator.path = "My/Decorator/"
disableTranslator = 0
validators.required.validator = "NotEmpty"
validators.required.breakChainOnFailure = true
validators.alpha.validator = "alpha"
validators.regex.validator = "regex"
validators.regex.options.pattern = "/^[A-F].*/$"
filters.ucase.filter = "StringToUpper"
decorators.element.decorator = "ViewHelper"
decorators.element.options.helper = "FormText"
decorators.label.decorator = "Label"
]]></programlisting>
    </sect2>

    <sect2 id="zend.form.elements.custom">
        <title>カスタム要素</title>

        <para>
            独自の要素を作成するには <classname>Zend_Form_Element</classname>
            クラスを継承したクラスを作成します。
            独自の要素を作成することになるのは、たとえば次のような場合です。
        </para>

        <itemizedlist>
            <listitem><para>
                共通のバリデータやフィルタを持つ要素を作成する
            </para></listitem>

            <listitem><para>
                独自のデコレータ機能を持つ要素を作成する
            </para></listitem>
        </itemizedlist>

        <para>
            要素を継承する際に主に使用するメソッドは次の 2 つです。
            <methodname>init()</methodname> で独自の初期化ロジックをあなたの要素に追加し、
            <methodname>loadDefaultDecorators()</methodname>
            でデフォルトのデコレータのリストをあなたの要素に設定します。,
        </para>

        <para>
            たとえば、あなたが作成するフォーム上のテキストボックスでは、すべて
            <classname>StringTrim</classname> フィルタが必要で、
            かつ正規表現による入力検証を行うことになるとしましょう。
            ついでに、表示用に独自のデコレータ 'My_Decorator_TextItem'
            も使用するものとします。さらに、標準の属性
            'size' や 'maxLength'、そして 'class' なども設定します。
            このような要素は、次のように定義します。
        </para>

        <programlisting language="php"><![CDATA[
class My_Element_Text extends Zend_Form_Element
{
    public function init()
    {
        $this->addPrefixPath('My_Decorator', 'My/Decorator/', 'decorator')
             ->addFilters('StringTrim')
             ->addValidator('Regex', false, array('/^[a-z0-9]{6,}$/i'))
             ->addDecorator('TextItem')
             ->setAttrib('size', 30)
             ->setAttrib('maxLength', 45)
             ->setAttrib('class', 'text');
    }
}
]]></programlisting>

        <para>
            それから、フォームオブジェクトに対して
            この要素のプレフィックスパスを登録した上で要素を作成します。
        </para>

        <programlisting language="php"><![CDATA[
$form->addPrefixPath('My_Element', 'My/Element/', 'element')
     ->addElement('text', 'foo');
]]></programlisting>

        <para>
            'foo' 要素はこれで <classname>My_Element_Text</classname>
            型となりました。先ほど説明したような機能を持つテキストボックスです。
        </para>

        <para>
            <classname>Zend_Form_Element</classname> を継承したクラスでオーバーライドしたくなる
            その他のメソッドとして、<methodname>loadDefaultDecorators()</methodname>
            があります。このメソッドは、条件付きで
            要素にデフォルトのデコレータセットを読み込みます。
            継承したクラスで、このデコレータ群を置き換えることができます。
        </para>

        <programlisting language="php"><![CDATA[
class My_Element_Text extends Zend_Form_Element
{
    public function loadDefaultDecorators()
    {
        $this->addDecorator('ViewHelper')
             ->addDecorator('DisplayError')
             ->addDecorator('Label')
             ->addDecorator('HtmlTag',
                            array('tag' => 'div', 'class' => 'element'));
    }
}
]]></programlisting>

        <para>
            要素のカスタマイズにはさまざまな方法があります。
            <classname>Zend_Form_Element</classname> の <acronym>API</acronym> ドキュメントを熟読し、
            どんな機能が使用できるのかを覚えていきましょう。
        </para>
    </sect2>
</sect1>
<!--
vim:se ts=4 sw=4 tw=80 et:
-->