repo_zf1Php7/documentation/manual/ja/module_specs/Zend_Form-Forms.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<!-- EN-Revision: 17618 -->
<sect1 id="zend.form.forms">
    <title>Zend_Form によるフォームの作成</title>

    <para>
        <classname>Zend_Form</classname> クラスは、フォームの要素や
        表示グループ、そしてサブフォームの集約を行います。
        そして、その要素に対して次のような操作を行います。
    </para>

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

        <listitem><para>
            値の集約 (すべての項目についてのフィルタリング前/
            フィルタリング後の値の取得など)
        </para></listitem>

        <listitem><para>
            すべての項目についての反復処理。
            登録した順、あるいは各項目から取得した順序ヒントに従った順での処理
        </para></listitem>

        <listitem><para>
            フォーム全体のレンダリング。デコレータでレンダリング方法をカスタマイズしたり、
            フォームの各項目を順次処理したりなど
        </para></listitem>
    </itemizedlist>

    <para>
        <classname>Zend_Form</classname> で作成したフォームが複雑なものになることもありますが、
        シンプルなフォームで使用するのがもっともよくある使用例でしょう。
        手早いアプリケーション開発 (RAD) やプロトタイピングでの使用に最適です。
    </para>

    <para>
        もっとも基本的な使用法は、単にフォームオブジェクトを作成するものです。
    </para>

    <programlisting language="php"><![CDATA[
// 汎用的なフォームオブジェクト
$form = new Zend_Form();

// 独自のフォームオブジェクト
$form = new My_Form()
]]></programlisting>

    <para>
        <classname>Zend_Config</classname> のインスタンスあるいは配列で設定を渡すことができます。
        これを使用すると、オブジェクトの状態を設定したり新しい要素を作成したりすることができます。
    </para>

    <programlisting language="php"><![CDATA[
// 設定オプションを渡します
$form = new Zend_Form($config);
]]></programlisting>

    <para>
        <classname>Zend_Form</classname> は順次処理が可能です。
        各要素や表示グループ、サブフォームごとに処理することができます。
        処理順は、登録した順番および各項目に設定されている順番となります。
        これは、各要素のレンダリングを適切な順で行いたいときに便利です。
    </para>

    <para>
        <classname>Zend_Form</classname> は、要素や表示グループのファクトリとして使用できると同時に
        デコレータで自分自身をレンダリングすることもできます。
    </para>

    <sect2 id="zend.form.forms.plugins">
        <title>プラグインローダー</title>
        <para>
            <classname>Zend_Form</classname> では、
            <classname>Zend_Loader_PluginLoader</classname> を使用することで
            別の要素やデコレータの位置を指定することができます。
            それぞれにプラグインローダーを関連づけることができ、
            汎用的なアクセサを使用してそれを取得したり変更したりします。
        </para>

        <para>
            使用できるローダーの型は 'element' と 'decorator'
            です。さまざまなプラグインローダーメソッドが用意されています。
            型の名前は大文字小文字を区別しません。
        </para>

        <para>
            プラグインローダーで使用できるメソッドは、次のとおりです。
        </para>

        <itemizedlist>
            <listitem><para>
                <methodname>setPluginLoader($loader, $type)</methodname>:
                $loader はプラグインローダーオブジェクトで、type
                は先ほど説明した型のいずれかです。
                これは、指定した型のプラグインローダーを
                指定したローダーオブジェクトに設定します。
            </para></listitem>

            <listitem><para>
                <methodname>getPluginLoader($type)</methodname>:
                $type に関連づけられたプラグインローダーを取得します。
            </para></listitem>

            <listitem><para>
                <methodname>addPrefixPath($prefix, $path, $type = null)</methodname>:
                プレフィックスとパスの関連づけを、$type で指定したローダーに指定します。
                $type が null の場合はそのパスをすべてのローダーに追加します。この場合、
                プレフィックスの後に "_Element" および
                "_Decorator" を追加し、パスに "Element/" および
                "Decorator/" を追加します。追加のフォーム要素クラス群をすべて同じ階層に配置した場合は、
                このメソッドを使用すると簡単に基底プレフィックスを設定することができます。
            </para></listitem>

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

        <para>
            さらに、<classname>Zend_Form</classname>
            のインスタンスで作成したすべての要素や表示グループ用のプレフィックスパスを設定するには
            次のメソッドを使用します。
        </para>

        <itemizedlist>
            <listitem><para>
                <methodname>addElementPrefixPath($prefix, $path, $type = null)</methodname>:
                <methodname>addPrefixPath()</methodname> と同じですが、
                クラスのプレフィックスとパスを指定しなければなりません。
                <code>$type</code> を指定する場合は、それは
                <classname>Zend_Form_Element</classname>
                で指定したプラグインローダーの型のひとつでなければなりません。
                <code>$type</code> にどんな値が指定できるのかについては <link
                    linkend="zend.form.elements.loaders">要素のプラグインのセクション</link>
                を参照ください。<code>$type</code> を省略した場合は、
                すべての型で用いる全般的なプレフィックスとみなします。
            </para></listitem>

            <listitem><para>
                <methodname>addDisplayGroupPrefixPath($prefix, $path)</methodname>:
                <methodname>addPrefixPath()</methodname> と似ていますが、
                クラスのプレフィックスとパスを指定しなければなりません。
                しかし、表示グループではプラグインとして対応しているのはデコレータだけなので、
                <code>$type</code> は不要です。
            </para></listitem>
        </itemizedlist>

        <para>
            独自の要素やデコレータを使用すると、
            複数フォーム間で機能を共有したり
            独自の機能をカプセル化したりできるようになります。
            独自の要素を既存の標準クラスに置き換えて使用する例については、
            要素のドキュメントの中の
            <link linkend="zend.form.elements.loaders.customLabel">独自のラベルを作る例</link>
            を参照ください。
        </para>
    </sect2>

    <sect2 id="zend.form.forms.elements">
        <title>要素</title>
        <para>
            <classname>Zend_Form</classname> では、フォームに要素を追加したり
            フォームから要素を削除したりするためのアクセサを提供しています。
            これらは要素オブジェクトのインスタンスを受け取ることもできますし、
            ファクトリとして要素オブジェクトのインスタンスを作成させることもできます。
        </para>

        <para>
            要素を追加するもっとも基本的なメソッドが
            <methodname>addElement()</methodname> です。
            このメソッドは、 <classname>Zend_Form_Element</classname> 型
            (あるいは <classname>Zend_Form_Element</classname> を継承したクラス) のオブジェクト
            あるいは新しい要素を作成するための引数
            (要素の型や名前、設定オプション) を受け取ります。
        </para>

        <para>
            例を示します。
        </para>

        <programlisting language="php"><![CDATA[
// 要素のインスタンスを使用します
$element = new Zend_Form_Element_Text('foo');
$form->addElement($element);

// ファクトリを使用します
//
// Zend_Form_Element_Text 型で
// 'foo' という名前の要素を作成します
$form->addElement('text', 'foo');

// 要素の label オプションを渡します
$form->addElement('text', 'foo', array('label' => 'Foo:'));
]]></programlisting>

        <note>
            <title>addElement() における「流れるようなインターフェイス」の実装</title>

            <para>
                <methodname>addElement()</methodname> は「流れるようなインターフェイス」
                を実装しています。つまり、このメソッドは要素ではなく
                <classname>Zend_Form</classname> オブジェクトを返すということです。
                これによって、複数の addElement() メソッドやその他のフォームメソッド
                (<classname>Zend_Form</classname> のすべてのセッターは流れるようなインターフェイスを実装しています)
                を連結させることができます。
            </para>

            <para>
                単に要素を返してほしい場合は、
                <methodname>createElement()</methodname> を使いましょう。
                概要は以下で説明します。しかし、
                <methodname>createElement()</methodname> は要素をフォームにアタッチしないことに注意しましょう。
            </para>

            <para>
                内部的には、<methodname>addElement()</methodname> は実際には
                <methodname>createElement()</methodname> をコールして作成した要素をフォームにアタッチしています。
            </para>
        </note>

        <para>
            要素をフォームに追加したら、名前を指定してそれを取得することができます。
            取得するには、<methodname>getElement()</methodname> メソッドを使用するか
            オブジェクトのプロパティとして要素にアクセスします。
            property:
        </para>

        <programlisting language="php"><![CDATA[
// getElement():
$foo = $form->getElement('foo');

// オブジェクトのプロパティとして
$foo = $form->foo;
]]></programlisting>

        <para>
            時には、フォームにアタッチせずに要素を作成したいこともあるでしょう
            (フォームに登録されているさまざまなプラグインパスを使いたいけれど、
            そのオブジェクトは後でサブフォームにアタッチしたい場合など)。
            そんな場合は <methodname>createElement()</methodname> メソッドを使用します。
        </para>

        <programlisting language="php"><![CDATA[
// $username は Zend_Form_Element_Text オブジェクトとなります
$username = $form->createElement('text', 'username');
]]></programlisting>

        <sect3 id="zend.form.forms.elements.values">
            <title>値の設定と取得</title>

            <para>
                フォームの検証をすませたら、通常は値を取得することになるでしょう。
                その値を用いてデータベースの更新なりウェブサービスの操作なりといった作業を行います。
                すべての要素の値を取得するには <methodname>getValues()</methodname> を使用します。
                <methodname>getValue($name)</methodname> を使用すると、
                要素名を指定して特定の要素の値を取得することができます。
            </para>

            <programlisting language="php"><![CDATA[
// すべての値を取得します
$values = $form->getValues();

// 'foo' 要素の値のみを取得します
$value = $form->getValue('foo');
]]></programlisting>

            <para>
                レンダリング前に、フォームに特定の値を設定したいこともあるでしょう。
                これを行うには <methodname>setDefaults()</methodname> メソッドあるいは
                <methodname>populate()</methodname> メソッドを使用します。
            </para>

            <programlisting language="php"><![CDATA[
$form->setDefaults($data);
$form->populate($data);
]]></programlisting>

            <para>
                逆に、値を設定したり検証したりした後でフォームをクリアしたいこともあるでしょう。
                これを行うには <methodname>reset()</methodname> メソッドを使用します。
            </para>

            <programlisting language="php"><![CDATA[
$form->reset();
]]></programlisting>
        </sect3>

        <sect3 id="zend.form.forms.elements.global">
            <title>グローバルな操作</title>

            <para>
                時には、すべての要素に対して何らかの操作を行いたくなることもあります。
                ありがちな例としては、すべての要素に対してプラグインのプレフィックスを設定したり
                デコレータを設定したり、フィルタを設定したりといったものがあります。
                以下に例を示します。
            </para>

            <example id="zend.form.forms.elements.global.allpaths">
                <title>すべての要素に対するプレフィックスパスの設定</title>

                <para>
                    型を指定してすべての要素に対するプレフィックスパスを設定したり、
                    グローバルプレフィックスを使用したりする例です。
                </para>

                <programlisting language="php"><![CDATA[
// グローバルプレフィックスパスの設定:
// プレフィックス My_Foo_Filter、My_Foo_Validate、
// My_Foo_Decorator のパスを作成します。
$form->addElementPrefixPath('My_Foo', 'My/Foo/');

// フィルタのパスのみ:
$form->addElementPrefixPath('My_Foo_Filter',
                            'My/Foo/Filter',
                            'filter');

// バリデータのパスのみ:
$form->addElementPrefixPath('My_Foo_Validate',
                            'My/Foo/Validate',
                            'validate');

// デコレータのパスのみ:
$form->addElementPrefixPath('My_Foo_Decorator',
                            'My/Foo/Decorator',
                            'decorator');
]]></programlisting>
            </example>

            <example id="zend.form.forms.elements.global.decorators">
                <title>すべての要素に対するデコレータの設定</title>

                <para>
                    すべての要素に対するデコレータを設定することができます。
                    <methodname>setElementDecorators()</methodname> に
                    <methodname>setDecorators()</methodname>
                    と同じようなデコレータの配列を渡すと、
                    各要素にそれまで設定されていたすべてのデコレータを上書きします。
                    この例では、単純に ViewHelper デコレータと
                    Label デコレータを設定します。
                </para>

                <programlisting language="php"><![CDATA[
$form->setElementDecorators(array(
    'ViewHelper',
    'Label'
));
]]></programlisting>
            </example>

            <example id="zend.form.forms.elements.global.decoratorsFilter">
                <title>いくつかの要素に対するデコレータの設定</title>

                <para>
                    設定したい要素、あるいは設定したくない要素を指定することで、
                    一部の要素にだけデコレータを設定することもできます。
                    <methodname>setElementDecorators()</methodname> の 2 番目の引数に要素名の配列を指定します。
                    デフォルトでは、ここで指定した要素にのみデコレータが設定されます。
                    3 番目の引数を渡すこともできます。
                    これは、設定「したい」要素なのか設定「したくない」
                    要素なのかを表すフラグとなります。
                    false を渡すと、指定した
                    <emphasis>以外の</emphasis> すべての要素にデコレータを設定します。
                    このメソッドの標準的な使用法と同様、
                    各要素にそれまで設定されていたすべてのデコレータを上書きします。
                </para>

                <para>
                    次の例は、
                    ViewHelper デコレータと Label デコレータを
                    要素 'foo' および 'bar' に対してのみ使用するものです。
                </para>

                <programlisting language="php"><![CDATA[
$form->setElementDecorators(
    array(
        'ViewHelper',
        'Label'
    ),
    array(
        'foo',
        'bar'
    )
);
]]></programlisting>

                <para>
                    一方、この例では、ViewHelper デコレータと Label
                    デコレータを 'foo' と 'bar' <emphasis>以外の</emphasis>
                    すべての要素に対して使用します。
                </para>

                <programlisting language="php"><![CDATA[
$form->setElementDecorators(
    array(
        'ViewHelper',
        'Label'
    ),
    array(
        'foo',
        'bar'
    ),
    false
);
]]></programlisting>
            </example>

                <note>
                    <title>要素によっては不適切なデコレータもある</title>

                    <para>
                        <methodname>setElementDecorators()</methodname>
                        はよい方法に見えますが、時には予期せぬ結果を引き起こすこともあります。
                        たとえば、ボタン系の要素 (Submit, Button, Reset)
                        では現在ラベルをボタンの値として使用しています。
                        そして ViewHelper デコレータや DtDdWrapper デコレータは、
                        余計なラベルやエラー、ヒントをレンダリングしないためにのみ用います。
                        上の例ではいくつかのラベルが重複してしまいます。
                    </para>

                    <para>
                        先ほどの例に示したように、設定したい要素/したくない要素
                        を配列で指定するようにすれば、この問題を回避できます。
                    </para>

                    <para>
                        したがって、このメソッドは注意して使うようにしましょう。
                        場合によっては、いくつかの要素を除外するか、
                        そののデコレータを変更して予期せぬ結果を防ぐ必要があります。
                    </para>
                </note>

            <example id="zend.form.forms.elements.global.filters">
                <title>すべての要素に対するフィルタの設定</title>

                <para>
                    すべての要素に対して同じフィルタを適用したくなることもよくあります。
                    たとえば、すべての値を <methodname>trim()</methodname> するなどです。
                </para>

        <programlisting language="php"><![CDATA[
$form->setElementFilters(array('StringTrim'));
]]></programlisting>
            </example>
        </sect3>

        <sect3 id="zend.form.forms.elements.methods">
            <title>要素を操作するためのメソッド</title>

            <para>
                次のメソッドを使用して、要素を操作します。
            </para>

            <itemizedlist>
                <listitem><para>
                    <methodname>createElement($element, $name = null, $options = null)</methodname>
                </para></listitem>

                <listitem><para>
                    <methodname>addElement($element, $name = null, $options = null)</methodname>
                </para></listitem>

                <listitem><para>
                    <methodname>addElements(array $elements)</methodname>
                </para></listitem>

                <listitem><para>
                    <methodname>setElements(array $elements)</methodname>
                </para></listitem>

                <listitem><para>
                    <methodname>getElement($name)</methodname>
                </para></listitem>

                <listitem><para>
                    <methodname>getElements()</methodname>
                </para></listitem>

                <listitem><para>
                    <methodname>removeElement($name)</methodname>
                </para></listitem>

                <listitem><para>
                    <methodname>clearElements()</methodname>
                </para></listitem>

                <listitem><para>
                    <methodname>setDefaults(array $defaults)</methodname>
                </para></listitem>

                <listitem><para>
                    <methodname>setDefault($name, $value)</methodname>
                </para></listitem>

                <listitem><para>
                    <methodname>getValue($name)</methodname>
                </para></listitem>

                <listitem><para>
                    <methodname>getValues()</methodname>
                </para></listitem>

                <listitem><para>
                    <methodname>getUnfilteredValue($name)</methodname>
                </para></listitem>

                <listitem><para>
                    <methodname>getUnfilteredValues()</methodname>
                </para></listitem>

                <listitem><para>
                    <methodname>setElementFilters(array $filters)</methodname>
                </para></listitem>

                <listitem><para>
                    <methodname>setElementDecorators(array $decorators)</methodname>
                </para></listitem>

                <listitem><para>
                    <methodname>addElementPrefixPath($prefix, $path, $type = null)</methodname>
                </para></listitem>

                <listitem><para>
                    <methodname>addElementPrefixPaths(array $spec)</methodname>
                </para></listitem>
            </itemizedlist>
        </sect3>
    </sect2>

    <sect2 id="zend.form.forms.displaygroups">
        <title>表示グループ</title>

        <para>
            表示グループを使用すると、複数の要素を仮想的にグループ化して
            表示させることができます。
            フォーム内の各要素に対しては名前を指定してアクセスできますが、
            フォームの要素を順次処理したりレンダリングしたりするときは
            表示グループは一括して扱われます。
            表示グループのもっとも一般的な使用例は、
            フィールドセット内の要素をグループ化することです。
        </para>

        <para>
            表示グループの基底クラスは <classname>Zend_Form_DisplayGroup</classname> です。
            このクラスのインスタンスを直接作成することもできますが、
            一般的には <classname>Zend_Form</classname> の
            <methodname>addDisplayGroup()</methodname> メソッドでインスタンスを作成することになります。
            このメソッドの最初の引数には要素の配列を渡し、
            表示グループの名前を 2 番目の引数で指定します。
            オプションの 3 番目の引数で、設定の配列や
            <classname>Zend_Config</classname> オブジェクトを渡すこともできます。
        </para>

        <para>
            'username' と 'password' という要素がすでにフォームに登録済みである場合に、
            次のコードを使用するとそれらを表示グループ
            'login' にまとめることができます。
        </para>

        <programlisting language="php"><![CDATA[
$form->addDisplayGroup(array('username', 'password'), 'login');
]]></programlisting>

        <para>
            表示グループにアクセスするには、
            <methodname>getDisplayGroup()</methodname> メソッドを使用するか
            あるいは表示グループ名を指定します。
        </para>

        <programlisting language="php"><![CDATA[
// getDisplayGroup() の使用
$login = $form->getDisplayGroup('login');

// オーバーロードの使用
$login = $form->login;
]]></programlisting>

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

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

            <programlisting language="php"><![CDATA[
$form->addDisplayGroup(
    array('foo', 'bar'),
    'foobar',
    array('disableLoadDefaultDecorators' => true)
);
]]></programlisting>

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

        <sect3 id="zend.form.forms.displaygroups.global">
            <title>グローバルな操作</title>

            <para>
                要素と同様、表示グループに対しても全体に共通の操作があるでしょう。
                デコレータを設定したり、デコレータを探すプラグインパスを設定したりといったものです。
            </para>

            <example id="zend.form.forms.displaygroups.global.paths">
                <title>すべての表示グループに対するデコレータプレフィックスパスの設定</title>

                <para>
                    デフォルトでは、表示グループはフォームが使用しているデコレータパスを継承します。
                    別の場所を探すようにしたい場合は
                    <methodname>addDisplayGroupPrefixPath()</methodname> メソッドを使用します。
                </para>

                <programlisting language="php"><![CDATA[
$form->addDisplayGroupPrefixPath('My_Foo_Decorator', 'My/Foo/Decorator');
]]></programlisting>
            </example>

            <example id="zend.form.forms.displaygroups.global.decorators">
                <title>すべての表示グループに対するデコレータの設定</title>

                <para>
                    すべての表示グループに対するデコレータを設定することができます。
                    <methodname>setDisplayGroupDecorators()</methodname> に
                    <methodname>setDecorators()</methodname>
                    と同じようなデコレータの配列を渡すと、
                    各表示グループにそれまで設定されていたすべてのデコレータを上書きします。
                    この例では、単純に fieldset デコレータ
                    (FormElements デコレータは、要素を順次処理するために必須です)
                    を設定します。
                </para>

                <programlisting language="php"><![CDATA[
$form->setDisplayGroupDecorators(array(
    'FormElements',
    'Fieldset'
));
]]></programlisting>
            </example>
        </sect3>

        <sect3 id="zend.form.forms.displaygroups.customClasses">
            <title>独自の表示グループクラスの使用</title>

            <para>
                デフォルトでは、<classname>Zend_Form</classname> は
                表示グループ用に <classname>Zend_Form_DisplayGroup</classname>
                クラスを使用します。
                このクラスを継承すれば、独自の機能を持つクラスを作成することができます。
                <methodname>addDisplayGroup()</methodname>
                には具象インスタンスを渡すことはできませんが、
                どのクラスを使用するのかをオプションで指定することができます。
                このときに使用するキーは 'displayGroupClass' です。
            </para>

            <programlisting language="php"><![CDATA[
// 'My_DisplayGroup' クラスを使用します
$form->addDisplayGroup(
    array('username', 'password'),
    'user',
    array('displayGroupClass' => 'My_DisplayGroup')
);
]]></programlisting>

            <para>
                そのクラスがまだ読み込まれていない場合は、<classname>Zend_Form</classname>
                は <classname>Zend_Loader</classname> を使ってクラスを読み込みます。
            </para>

            <para>
                デフォルトの表示グループクラスを指定し、
                そのフォームオブジェクトで作成するすべての表示グループで
                同じクラスを使わせることもできます。
            </para>

            <programlisting language="php"><![CDATA[
// すべての表示グループで 'My_DisplayGroup' クラスを使用します
$form->setDefaultDisplayGroupClass('My_DisplayGroup');
]]></programlisting>

            <para>
                これは、設定項目
                'defaultDisplayGroupClass' で指定することもできます。
                そうすれば、事前にこのクラスが読み込まれて
                すべての表示グループでこのクラスを使うようになります。
            </para>
        </sect3>

        <sect3 id="zend.form.forms.displaygroups.interactionmethods">
            <title>表示グループを操作するためのメソッド</title>

            <para>
                次のメソッドを使用して、表示グループを操作します。
            </para>

            <itemizedlist>
                <listitem><para>
                    <methodname>addDisplayGroup(array $elements, $name, $options = null)</methodname>
                </para></listitem>

                <listitem><para>
                    <methodname>addDisplayGroups(array $groups)</methodname>
                </para></listitem>

                <listitem><para>
                    <methodname>setDisplayGroups(array $groups)</methodname>
                </para></listitem>

                <listitem><para>
                    <methodname>getDisplayGroup($name)</methodname>
                </para></listitem>

                <listitem><para>
                    <methodname>getDisplayGroups()</methodname>
                </para></listitem>

                <listitem><para>
                    <methodname>removeDisplayGroup($name)</methodname>
                </para></listitem>

                <listitem><para>
                    <methodname>clearDisplayGroups()</methodname>
                </para></listitem>

                <listitem><para>
                    <methodname>setDisplayGroupDecorators(array $decorators)</methodname>
                </para></listitem>

                <listitem><para>
                    <methodname>addDisplayGroupPrefixPath($prefix, $path)</methodname>
                </para></listitem>

                <listitem><para>
                    <methodname>setDefaultDisplayGroupClass($class)</methodname>
                </para></listitem>

                <listitem><para>
                    <methodname>getDefaultDisplayGroupClass($class)</methodname>
                </para></listitem>
            </itemizedlist>
        </sect3>

        <sect3 id="zend.form.forms.displaygroups.methods">
            <title>Zend_Form_DisplayGroup のメソッド</title>

            <para>
                <classname>Zend_Form_DisplayGroup</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>メタデータ</para>
                    <itemizedlist>
                        <listitem><para><methodname>setAttrib($key, $value)</methodname></para></listitem>

                        <listitem><para><methodname>addAttribs(array $attribs)</methodname></para></listitem>

                        <listitem><para><methodname>setAttribs(array $attribs)</methodname></para></listitem>

                        <listitem><para><methodname>getAttrib($key)</methodname></para></listitem>

                        <listitem><para><methodname>getAttribs()</methodname></para></listitem>

                        <listitem><para><methodname>removeAttrib($key)</methodname></para></listitem>

                        <listitem><para><methodname>clearAttribs()</methodname></para></listitem>

                        <listitem><para><methodname>setName($name)</methodname></para></listitem>

                        <listitem><para><methodname>getName()</methodname></para></listitem>

                        <listitem><para><methodname>setDescription($value)</methodname></para></listitem>

                        <listitem><para><methodname>getDescription()</methodname></para></listitem>

                        <listitem><para><methodname>setLegend($legend)</methodname></para></listitem>

                        <listitem><para><methodname>getLegend()</methodname></para></listitem>

                        <listitem><para><methodname>setOrder($order)</methodname></para></listitem>

                        <listitem><para><methodname>getOrder()</methodname></para></listitem>
                    </itemizedlist>
                </listitem>

                <listitem><para>要素</para>
                    <itemizedlist>
                        <listitem><para><methodname>createElement($type, $name, array $options = array())</methodname></para></listitem>

                        <listitem><para><methodname>addElement($typeOrElement, $name, array $options = array())</methodname></para></listitem>

                        <listitem><para><methodname>addElements(array $elements)</methodname></para></listitem>

                        <listitem><para><methodname>setElements(array $elements)</methodname></para></listitem>

                        <listitem><para><methodname>getElement($name)</methodname></para></listitem>

                        <listitem><para><methodname>getElements()</methodname></para></listitem>

                        <listitem><para><methodname>removeElement($name)</methodname></para></listitem>

                        <listitem><para><methodname>clearElements()</methodname></para></listitem>
                    </itemizedlist>
                </listitem>

                <listitem><para>プラグインローダー</para>
                    <itemizedlist>
                        <listitem><para><methodname>setPluginLoader(Zend_Loader_PluginLoader $loader)</methodname></para></listitem>

                        <listitem><para><methodname>getPluginLoader()</methodname></para></listitem>

                        <listitem><para><methodname>addPrefixPath($prefix, $path)</methodname></para></listitem>

                        <listitem><para><methodname>addPrefixPaths(array $spec)</methodname></para></listitem>
                    </itemizedlist>
                </listitem>

                <listitem><para>デコレータ</para>
                    <itemizedlist>
                        <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>
                    </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>render(Zend_View_Interface $view = null)</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>
            </itemizedlist>
        </sect3>
    </sect2>

    <sect2 id="zend.form.forms.subforms">
        <title>サブフォーム</title>

        <para>
            サブフォームの役割は、次のようなものです。
        </para>

        <itemizedlist>
            <listitem><para>
                論理的な要素グループの作成。
                サブフォームは単なるフォームであり、
                サブフォームを独立したエンティティとして検証することができます。
            </para></listitem>

            <listitem><para>
                複数ページにまたがるフォームの作成。
                サブフォームは単なるフォームなので、
                ページごとに別々のサブフォームを表示させて複数ページのフォームを作成し、
                各ページで独自のバリデーションを行うことができます。
                すべてのサブフォームの検証に成功した時点ではじめて
                フォームの検証が完了したことになります。
            </para></listitem>

            <listitem><para>
                表示のグループ化。
                表示グループと同様、サブフォームについても
                フォーム内でのレンダリングの際にはひとつの要素として扱われます。
                しかし注意しましょう。
                親フォームからはサブフォームの要素にはアクセスできません。
            </para></listitem>
        </itemizedlist>

        <para>
            サブフォームは <classname>Zend_Form</classname> のオブジェクトです。一般的には
            <classname>Zend_Form_SubForm</classname> のオブジェクトとなります。
            後者のクラスには、大きなフォームに含めるのに適したデコレータが含まれています
            (HTML の form タグをレンダリングせず、要素をグループ化するものです)。
            サブフォームをアタッチするには、単にそれを要素に追加して名前を指定するだけです。
        </para>

        <programlisting language="php"><![CDATA[
$form->addSubForm($subForm, 'subform');
]]></programlisting>

        <para>
            サブフォームを取得するには、
            <methodname>getSubForm($name)</methodname> を使用するかあるいはサブフォームの名前を使用します。
        </para>

        <programlisting language="php"><![CDATA[
// getSubForm() の使用
$subForm = $form->getSubForm('subform');

// オーバーロードの使用
$subForm = $form->subform;
]]></programlisting>

        <para>
            サブフォームは、親フォームの要素のひとつとして順次処理することができます。
            サブフォーム内の要素は処理できません。
        </para>

        <sect3 id="zend.form.forms.subforms.global">
            <title>グローバルな操作</title>

            <para>
                要素や表示グループと同様、サブフォームに対しても全体に共通の操作があるでしょう。
                しかし、表示グループや要素とは異なり、
                サブフォームは親フォームのほとんどの機能を継承しています。
                グローバルな操作として本当に必要なのは、サブフォーム用のデコレータの設定くらいです。
                そんな場合には <methodname>setSubFormDecorators()</methodname>
                メソッドを使用します。次の例では、すべてのサブフォームに対して
                単純に fieldset デコレータを設定します
                (FormElements デコレータは、要素を順次処理するために必須です)。
            </para>

            <programlisting language="php"><![CDATA[
$form->setSubFormDecorators(array(
    'FormElements',
    'Fieldset'
));
]]></programlisting>
        </sect3>

        <sect3 id="zend.form.forms.subforms.methods">
            <title>サブフォームを操作するためのメソッド</title>

            <para>
                次のメソッドを使用して、サブフォームを操作します。
            </para>

            <itemizedlist>
                <listitem><para>
                    <methodname>addSubForm(Zend_Form $form, $name, $order = null)</methodname>
                </para></listitem>

                <listitem><para>
                    <methodname>addSubForms(array $subForms)</methodname>
                </para></listitem>

                <listitem><para>
                    <methodname>setSubForms(array $subForms)</methodname>
                </para></listitem>

                <listitem><para>
                    <methodname>getSubForm($name)</methodname>
                </para></listitem>

                <listitem><para>
                    <methodname>getSubForms()</methodname>
                </para></listitem>

                <listitem><para>
                    <methodname>removeSubForm($name)</methodname>
                </para></listitem>

                <listitem><para>
                    <methodname>clearSubForms()</methodname>
                </para></listitem>

                <listitem><para>
                    <methodname>setSubFormDecorators(array $decorators)</methodname>
                </para></listitem>
            </itemizedlist>
        </sect3>
    </sect2>

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

        <para>
            フォームで一番大切なのはフォームが含む要素ですが、
            フォームにはそれ以外のメタデータも含まれます。たとえばフォームの名前
            (この名前は、HTML のマークアップ時に ID として用いられます)
            やアクション、そしてメソッドなどです。
            要素や表示グループ、サブフォームの数も含まれます。
            それ以外にも任意のメタデータを含めることができます
            (通常は、form タグで指定する HTML 属性などをここに含めます)。
        </para>

        <para>
            フォームの名前を設定したり取得したりするには name アクセサを使用します。
        </para>

        <programlisting language="php"><![CDATA[
// 名前を設定します
$form->setName('registration');

// 名前を取得します
$name = $form->getName();
]]></programlisting>

        <para>
            アクション (フォームを送信したときに進む URL)
            やメソッド (送信する方法。たとえば 'POST' あるいは 'GET')
            を設定するには、それぞれ action アクセサおよび
            method アクセサを使用します。
        </para>

        <programlisting language="php"><![CDATA[
// アクションとメソッドを設定します
$form->setAction('/user/login')
     ->setMethod('post');
]]></programlisting>

        <para>
            フォームのエンコード形式を設定するには
            enctype アクセサを使用します。
            <classname>Zend_Form</classname> では 2 つの定数
            <constant>Zend_Form::ENCTYPE_URLENCODED</constant> と
            <constant>Zend_Form::ENCTYPE_MULTIPART</constant> を定義しており、
            これらはそれぞれ 'application/x-www-form-urlencoded' と
            'multipart/form-data' に対応します。
            しかし、これ以外にも任意のエンコード形式を指定することができます。
        </para>

        <programlisting language="php"><![CDATA[
// アクションとメソッド、そして enctype を設定します
$form->setAction('/user/login')
     ->setMethod('post')
     ->setEnctype(Zend_Form::ENCTYPE_MULTIPART);
]]></programlisting>

        <note>
            <para>
                メソッドやアクション、enctype はレンダリングの際に内部的に使われるものであり、
                バリデーション用のものではありません。
            </para>
        </note>

        <para>
            <classname>Zend_Form</classname> は <code>Countable</code>
            インターフェイスを実装しており、count 関数の引数として使用することができます。
        </para>

        <programlisting language="php"><![CDATA[
$numItems = count($form);
]]></programlisting>

        <para>
            任意のメタデータを設定するには attribs アクセサを使用します。
            <classname>Zend_Form</classname> ではオーバーロードを使用して
            要素や表示グループそしてサブフォームにアクセスしているので、
            これがメタデータにアクセスするための唯一の方法となります。
        </para>

        <programlisting language="php"><![CDATA[
// 属性を設定します
$form->setAttrib('class', 'zend-form')
     ->addAttribs(array(
         'id'       => 'registration',
         'onSubmit' => 'validate(this)',
     ));

// 属性を取得します
$class = $form->getAttrib('class');
$attribs = $form->getAttribs();

// 属性を削除します
$form->removeAttrib('onSubmit');

// すべての属性を削除します
$form->clearAttribs();
]]></programlisting>
    </sect2>

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

        <para>
            フォームのマークアップを作成するのは手間のかかる作業です。
            特に、検証エラーの表示や値の送信などの決まりきった処理を何度も行うのは大変なことです。
            この問題に対する <classname>Zend_Form</classname>
            からの回答が <emphasis>デコレータ</emphasis> です。
        </para>

        <para>
            <classname>Zend_Form</classname> オブジェクトのデコレータを使用して、
            フォームをレンダリングします。
            FormElements デコレータは、フォームのすべての項目
            (要素、表示グループ、サブフォーム)
            を順次処理し、それらをレンダリングした結果を返します。
            それ以外のデコレータを使用して、コンテンツをラップしたり
            前後に何かを追加したりすることができます。
        </para>

        <para>
            <classname>Zend_Form</classname> のデフォルトのデコレータは、FormElements と
            HtmlTag (定義リストによるラッピングをします)、そして Form です。
            以下のコードと同様です。
        </para>

        <programlisting language="php"><![CDATA[
$form->setDecorators(array(
    'FormElements',
    array('HtmlTag', array('tag' => 'dl')),
    'Form'
));
]]></programlisting>

        <para>
            これは、次のような出力をします。
        </para>

        <programlisting language="html"><![CDATA[
<form action="/form/action" method="post">
<dl>
...
</dl>
</form>
]]></programlisting>

        <para>
            フォームオブジェクトに設定した任意の属性は、
            HTML の <code>&lt;form&gt;</code> タグの属性となります。
        </para>

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

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

            <programlisting language="php"><![CDATA[
$form = new Zend_Form(array('disableLoadDefaultDecorators' => true));
]]></programlisting>

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

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

            <para>
                内部的には、<classname>Zend_Form</classname>
                はデコレータのクラスをもとにデコレータを取得しています。
                その結果、同じ型のデコレータを複数使うことができなくなります。
                同じ型のデコレータを複数指定すると、
                後から指定したものが先に指定したものを上書きします。
            </para>

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

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

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

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

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

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

        <para>
            独自のデコレータを使用してフォームを作成することもできます。
            一般的な使用例としては、作成したい HTML が厳密に決まっている場合などがあります。
            デコレータでそれとまったく同じ HTML を作成し、単純にそれを返せばいいのです。
            個々の要素や表示グループに対してもそれぞれデコレータを使用することができます。
        </para>

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

        <itemizedlist>
                <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>
        </itemizedlist>

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

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

// fieldset デコレータのみ、コンテンツを渡してレンダリングします
echo $form->renderFieldset("<p>This is fieldset content</p>");
]]></programlisting>

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

    <sect2 id="zend.form.forms.validation">
        <title>バリデーション</title>

        <para>
            フォームの主な使用法は、送信されたデータを検証することです。
            <classname>Zend_Form</classname> は、フォーム全体あるいはその一部を一度に検証したり、
            XmlHttpRequests (AJAX) のレスポンスを自動的に検証したりすることができます。
            送信されたデータが無効な場合は、
            要素やサブフォームについて
            検証エラーのコードやメッセージを取得するメソッドが用意されています。
        </para>

        <para>
            フォーム全体のバリデーションを行うには <methodname>isValid()</methodname> メソッドを使用します。
        </para>

        <programlisting language="php"><![CDATA[
if (!$form->isValid($_POST)) {
    // 検証に失敗しました
}
]]></programlisting>

        <para>
            <methodname>isValid()</methodname> はすべての必須要素の検証を行います。
            また非必須要素の中で値が送信された要素についても検証します。
        </para>

        <para>
            時には一部のデータだけを検証したいこともあるでしょう。そんな場合には
            <methodname>isValidPartial($data)</methodname> を使用します。
        </para>

        <programlisting language="php"><![CDATA[
if (!$form->isValidPartial($data)) {
    // 検証に失敗しました
}
]]></programlisting>

        <para>
            <methodname>isValidPartial()</methodname> は、
            data の項目にマッチする要素についてのみ検証を行います。
            マッチする要素がなかった場合は処理をスキップします。
        </para>

        <para>
            <acronym>AJAX</acronym> リクエストの要素や要素グループを検証する際は、
            通常はフォームの一部を検証してその結果を <acronym>JSON</acronym> で返すことになります。
            <methodname>processAjax()</methodname> が、まさにその作業を行うメソッドです。
        </para>

        <programlisting language="php"><![CDATA[
$json = $form->processAjax($data);
]]></programlisting>

        <para>
            こうすれば、単純に <acronym>JSON</acronym> レスポンスをクライアントに返すことができます。
            フォームの検証に成功した場合は、この結果は true となります。
            失敗した場合は、キーとメッセージのペアを含む javascript
            オブジェクトを返します。個々の 'message'
            が検証エラーメッセージの配列となります。
        </para>

        <para>
            フォームの検証に失敗した場合は、エラーコードとエラーメッセージをそれぞれ
            <methodname>getErrors()</methodname> と
            <methodname>getMessages()</methodname> で取得することができます。
        </para>

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

        <note>
            <para>
                <methodname>getMessages()</methodname> が返すメッセージは エラーコード/エラーメッセージ
                の配列なので、<methodname>getErrors()</methodname> は通常は不要です。
            </para>
        </note>

        <para>
            個々の要素のコードとエラーメッセージを取得するには、
            それぞれのメソッドに要素名を渡します。
        </para>

        <programlisting language="php"><![CDATA[
$codes = $form->getErrors('username');
$messages = $form->getMessages('username');
]]></programlisting>

        <note>
            <para>
                注意: 要素を検証する際、<classname>Zend_Form</classname> は各要素の
                <methodname>isValid()</methodname> メソッドに 2 番目の引数を渡します。
                これは検証対象のデータの配列です。
                これを使用すると、他の要素の入力内容をもとにした検証を
                各要素で行うことができます。
                例としては、「パスワード」欄と「パスワード（確認）」
                があるユーザ登録フォームがあります。「パスワード」
                要素の検証には「パスワード（確認）」の入力内容を使用することになるでしょう。
            </para>
        </note>

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

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

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

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

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

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

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

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

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

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

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

            <para>
                この方式で設定したすべてのエラーは翻訳されることになります。
            </para>
        </sect3>
    </sect2>

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

        <para>
            以下の一覧は、<classname>Zend_Form</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>プラグインローダーおよびパス</para>
                <itemizedlist>
                    <listitem><para><methodname>setPluginLoader(Zend_Loader_PluginLoader_Interface $loader, $type = null)</methodname></para></listitem>

                    <listitem><para><methodname>getPluginLoader($type = null)</methodname></para></listitem>

                    <listitem><para><methodname>addPrefixPath($prefix, $path, $type = null) </methodname></para></listitem>

                    <listitem><para><methodname>addPrefixPaths(array $spec)</methodname></para></listitem>

                    <listitem><para><methodname>addElementPrefixPath($prefix, $path, $type = null)</methodname></para></listitem>

                    <listitem><para><methodname>addElementPrefixPaths(array $spec)</methodname></para></listitem>

                    <listitem><para><methodname>addDisplayGroupPrefixPath($prefix, $path)</methodname></para></listitem>
                </itemizedlist>
            </listitem>

            <listitem><para>メタデータ</para>
                <itemizedlist>
                    <listitem><para><methodname>setAttrib($key, $value)</methodname></para></listitem>

                    <listitem><para><methodname>addAttribs(array $attribs)</methodname></para></listitem>

                    <listitem><para><methodname>setAttribs(array $attribs)</methodname></para></listitem>

                    <listitem><para><methodname>getAttrib($key)</methodname></para></listitem>

                    <listitem><para><methodname>getAttribs()</methodname></para></listitem>

                    <listitem><para><methodname>removeAttrib($key)</methodname></para></listitem>

                    <listitem><para><methodname>clearAttribs()</methodname></para></listitem>

                    <listitem><para><methodname>setAction($action)</methodname></para></listitem>

                    <listitem><para><methodname>getAction()</methodname></para></listitem>

                    <listitem><para><methodname>setMethod($method)</methodname></para></listitem>

                    <listitem><para><methodname>getMethod()</methodname></para></listitem>

                    <listitem><para><methodname>setName($name)</methodname></para></listitem>

                    <listitem><para><methodname>getName()</methodname></para></listitem>
                </itemizedlist>
            </listitem>

            <listitem><para>要素</para>
                <itemizedlist>
                    <listitem><para><methodname>addElement($element, $name = null, $options = null)</methodname></para></listitem>

                    <listitem><para><methodname>addElements(array $elements)</methodname></para></listitem>

                    <listitem><para><methodname>setElements(array $elements)</methodname></para></listitem>

                    <listitem><para><methodname>getElement($name)</methodname></para></listitem>

                    <listitem><para><methodname>getElements()</methodname></para></listitem>

                    <listitem><para><methodname>removeElement($name)</methodname></para></listitem>

                    <listitem><para><methodname>clearElements()</methodname></para></listitem>

                    <listitem><para><methodname>setDefaults(array $defaults)</methodname></para></listitem>

                    <listitem><para><methodname>setDefault($name, $value)</methodname></para></listitem>

                    <listitem><para><methodname>getValue($name)</methodname></para></listitem>

                    <listitem><para><methodname>getValues()</methodname></para></listitem>

                    <listitem><para><methodname>getUnfilteredValue($name)</methodname></para></listitem>

                    <listitem><para><methodname>getUnfilteredValues()</methodname></para></listitem>

                    <listitem><para><methodname>setElementFilters(array $filters)</methodname></para></listitem>

                    <listitem><para><methodname>setElementDecorators(array $decorators)</methodname></para></listitem>
                </itemizedlist>
            </listitem>

            <listitem><para>サブフォーム</para>
                <itemizedlist>
                    <listitem><para><methodname>addSubForm(Zend_Form $form, $name, $order = null)</methodname></para></listitem>

                    <listitem><para><methodname>addSubForms(array $subForms)</methodname></para></listitem>

                    <listitem><para><methodname>setSubForms(array $subForms)</methodname></para></listitem>

                    <listitem><para><methodname>getSubForm($name)</methodname></para></listitem>

                    <listitem><para><methodname>getSubForms()</methodname></para></listitem>

                    <listitem><para><methodname>removeSubForm($name)</methodname></para></listitem>

                    <listitem><para><methodname>clearSubForms()</methodname></para></listitem>

                    <listitem><para><methodname>setSubFormDecorators(array $decorators)</methodname></para></listitem>
                </itemizedlist>
            </listitem>

            <listitem><para>表示グループ</para>
                <itemizedlist>
                    <listitem><para><methodname>addDisplayGroup(array $elements, $name, $options = null)</methodname></para></listitem>

                    <listitem><para><methodname>addDisplayGroups(array $groups)</methodname></para></listitem>

                    <listitem><para><methodname>setDisplayGroups(array $groups)</methodname></para></listitem>

                    <listitem><para><methodname>getDisplayGroup($name)</methodname></para></listitem>

                    <listitem><para><methodname>getDisplayGroups()</methodname></para></listitem>

                    <listitem><para><methodname>removeDisplayGroup($name)</methodname></para></listitem>

                    <listitem><para><methodname>clearDisplayGroups()</methodname></para></listitem>

                    <listitem><para><methodname>setDisplayGroupDecorators(array $decorators)</methodname></para></listitem>
                </itemizedlist>
            </listitem>

            <listitem><para>検証</para>
                <itemizedlist>
                    <listitem><para><methodname>populate(array $values)</methodname></para></listitem>

                    <listitem><para><methodname>isValid(array $data)</methodname></para></listitem>

                    <listitem><para><methodname>isValidPartial(array $data)</methodname></para></listitem>

                    <listitem><para><methodname>processAjax(array $data)</methodname></para></listitem>

                    <listitem><para><methodname>persistData()</methodname></para></listitem>

                    <listitem><para><methodname>getErrors($name = null)</methodname></para></listitem>

                    <listitem><para><methodname>getMessages($name = null)</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>

            <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>
        </itemizedlist>
    </sect2>

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

        <para>
            <classname>Zend_Form</classname> は、
            <methodname>setOptions()</methodname> や <methodname>setConfig()</methodname> を用いて
            (あるいはコンストラクタでオプションや
            <classname>Zend_Config</classname> オブジェクトを渡して)
            さまざまに設定することができます。
            これらのメソッドを使用して、フォームの要素や表示グループ、デコレータ、
            そしてメタデータを設定することができます。
        </para>

        <para>
            全般的なルールとして、もし 'set' + オプションのキー
            という名前のメソッドが <classname>Zend_Form</classname>
            にあった場合は、そのメソッドを使用するとオプションを設定することができます。
            アクセサが存在しない場合は
            キーが属性への参照とみなされ、
            <methodname>setAttrib()</methodname> に渡されます。
        </para>

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

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

            <listitem><para>
                <code>elementPrefixPaths</code> は
                <methodname>addElementPrefixPaths()</methodname> に渡されます。
            </para></listitem>

            <listitem><para>
                <code>displayGroupPrefixPaths</code> は
                <methodname>addDisplayGroupPrefixPaths()</methodname> に渡されます。
            </para></listitem>

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

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

                    <listitem><para><code>setConfig</code></para></listitem>

                    <listitem><para><code>setDefault</code></para></listitem>

                    <listitem><para><code>setOptions</code></para></listitem>

                    <listitem><para><code>setPluginLoader</code></para></listitem>

                    <listitem><para><code>setSubForms</code></para></listitem>

                    <listitem><para><code>setTranslator</code></para></listitem>

                    <listitem><para><code>setView</code></para></listitem>
                </itemizedlist>
            </listitem>
        </itemizedlist>

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

        <programlisting language="ini"><![CDATA[
[element]
name = "registration"
action = "/user/register"
method = "post"
attribs.class = "zend_form"
attribs.onclick = "validate(this)"

disableTranslator = 0

prefixPath.element.prefix = "My_Element"
prefixPath.element.path = "My/Element/"
elementPrefixPath.validate.prefix = "My_Validate"
elementPrefixPath.validate.path = "My/Validate/"
displayGroupPrefixPath.prefix = "My_Group"
displayGroupPrefixPath.path = "My/Group/"

elements.username.type = "text"
elements.username.options.label = "Username"
elements.username.options.validators.alpha.validator = "Alpha"
elements.username.options.filters.lcase = "StringToLower"
; more elements, of course...

elementFilters.trim = "StringTrim"
;elementDecorators.trim = "StringTrim"

displayGroups.login.elements.username = "username"
displayGroups.login.elements.password = "password"
displayGroupDecorators.elements.decorator = "FormElements"
displayGroupDecorators.fieldset.decorator = "Fieldset"

decorators.elements.decorator = "FormElements"
decorators.fieldset.decorator = "FieldSet"
decorators.fieldset.decorator.options.class = "zend_form"
decorators.form.decorator = "Form"
]]></programlisting>

        <para>
            これは、<acronym>XML</acronym> や <acronym>PHP</acronym>
            の配列形式の設定ファイルにも簡単に置き換えることができます。
        </para>
    </sect2>

    <sect2 id="zend.form.forms.custom">
        <title>カスタムフォーム</title>

        <para>
            独自の設定のフォームを使用するもうひとつの方法は、
            <classname>Zend_Form</classname> のサブクラスを作成することです。
            これには次のような利点があります。
        </para>

        <itemizedlist>
            <listitem><para>
                フォームのユニットテストを容易に行うことができ、
                検証やレンダリングが期待通りのものかを確認しやすくなる。
            </para></listitem>

            <listitem><para>
                個々の要素に対する決め細やかな制御ができる。
            </para></listitem>

            <listitem><para>
                フォームオブジェクトの再利用がしやすくなり、移植性が高まる
                (設定ファイルの内容を気にする必要がなくなる)。
            </para></listitem>

            <listitem><para>
                独自の機能を実装できる。
            </para></listitem>
        </itemizedlist>

        <para>
            一般的な使用法としては、<methodname>init()</methodname>
            メソッドでフォーム要素などの設定を行います。
        </para>

        <programlisting language="php"><![CDATA[
class My_Form_Login extends Zend_Form
{
    public function init()
    {
        $username = new Zend_Form_Element_Text('username');
        $username->class = 'formtext';
        $username->setLabel('Username:')
                 ->setDecorators(array(
                     array('ViewHelper',
                           array('helper' => 'formText')),
                     array('Label',
                           array('class' => 'label'))
                 ));

        $password = new Zend_Form_Element_Password('password');
        $password->class = 'formtext';
        $password->setLabel('Username:')
                 ->setDecorators(array(
                     array('ViewHelper',
                           array('helper' => 'formPassword')),
                     array('Label',
                           array('class' => 'label'))
                 ));

        $submit = new Zend_Form_Element_Submit('login');
        $submit->class = 'formsubmit';
        $submit->setValue('Login')
               ->setDecorators(array(
                   array('ViewHelper',
                   array('helper' => 'formSubmit'))
               ));

        $this->addElements(array(
            $username,
            $password,
            $submit
        ));

        $this->setDecorators(array(
            'FormElements',
            'Fieldset',
            'Form'
        ));
    }
}
]]></programlisting>

        <para>
            このフォームのインスタンスを作成するのは、次のように簡単です。
        </para>

        <programlisting language="php"><![CDATA[
$form = new My_Form_Login();
]]></programlisting>

        <para>
            そして、すべての機能はすでに準備済みの状態で、
            設定ファイルは不要です (この例はかなり単純化していることに注意しましょう。
            バリデーションや要素のフィルタなどは省略しています)。
        </para>

        <para>
            独自のフォームを作成する理由としてもうひとつよくあるのが、
            デフォルトのデコレータを定義したいというものです。
            この場合は <methodname>loadDefaultDecorators()</methodname> メソッドを上書きします。
        </para>

        <programlisting language="php"><![CDATA[
class My_Form_Login extends Zend_Form
{
    public function loadDefaultDecorators()
    {
        $this->setDecorators(array(
            'FormElements',
            'Fieldset',
            'Form'
        ));
    }
}
]]></programlisting>
    </sect2>
</sect1>
<!--
vim:se ts=4 sw=4 et:
-->