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

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<!-- EN-Revision: 24835 -->
<sect1 id="zend.form.standardElements">
    <title>Zend Framework に同梱されている標準のフォーム要素</title>

    <para>
        Zend Framework には標準でいくつかの具象要素クラスが組み込まれており、
        <acronym>HTML</acronym> フォーム要素の大半を網羅しています。
        そのほとんどは特定のビューヘルパーを指定して要素をデコレートするだけのものですが、
        追加機能を提供しているものもあります。
        ここでは、標準の要素クラスとその機能についての説明をまとめます。
    </para>

    <sect2 id="zend.form.standardElements.button">
        <title>Zend_Form_Element_Button</title>

        <para>
            <acronym>HTML</acronym> の button 要素を作成する際に使用します。
            <classname>Zend_Form_Element_Button</classname> は <link
                linkend="zend.form.standardElements.submit">Zend_Form_Element_Submit</link>
            を継承して独自の機能を追加したものです。
            'formButton' ビューヘルパーでデコレートを行います。
        </para>

        <para>
            submit 要素と同様、要素のラベルを表示時の値として使用します。
            つまり、ボタンのテキストを設定するにはその要素の value を設定します。
            翻訳アダプタが存在するときは、ラベルも翻訳されます。
        </para>

        <para>
            ラベルも要素の一部なので、button 要素は
            <link
                linkend="zend.form.standardDecorators.viewHelper">ViewHelper</link>
            デコレータと <link
                linkend="zend.form.standardDecorators.dtDdWrapper">DtDdWrapper</link>
            デコレータのみを使用します。
        </para>

        <para>
            フォームの表示や検証の後で、
            そのボタンが押されたかどうかを調べたい場合は
            <methodname>isChecked()</methodname> メソッドを使用します。
        </para>
    </sect2>

    <sect2 id="zend.form.standardElements.captcha">
        <title>Zend_Form_Element_Captcha</title>

        <para>
            CAPTCHAs は、ボットやその他の自動処理プロセスからの自動送信を防ぐための仕組みです。
        </para>

        <para>
            Captcha フォーム要素は、フォームの captcha でどの <link
                linkend="zend.captcha.adapters">Zend_Captcha アダプタ</link>
            を使用するかを選択できます。
            それからこのアダプタをオブジェクトのバリデータとして設定し、
            CAPTCHA デコレータを使用してレンダリングを行います
            (CAPTCHA アダプタへのプロキシとなります)。
        </para>

        <para>
            アダプタとしては <classname>Zend_Captcha</classname>
            の任意のアダプタを使用でき、また別途定義したその他のアダプタも使用できます。
            そのためには、プラグインローダのプレフィックスパスを指定する際に
            追加のキー 'CAPTCHA' あるいは 'captcha' を指定します。
        </para>

        <programlisting language="php"><![CDATA[
$element->addPrefixPath('My_Captcha', 'My/Captcha/', 'captcha');
]]></programlisting>

        <para>
            CAPTCHA を登録するには <methodname>setCaptcha()</methodname>
            メソッドを使用します。ここには、具象インスタンスあるいは
            CAPTCHA アダプタの短い名前を指定します。
        </para>

        <programlisting language="php"><![CDATA[
// 具象インスタンス
$element->setCaptcha(new Zend_Captcha_Figlet());

// 短い名前
$element->setCaptcha('Dumb');
]]></programlisting>

        <para>
            設定経由で要素を読み込みたい場合は、キー 'captcha'
            の値に配列 (キー 'captcha' を含むもの) を指定するか、
            キー 'captcha' と 'captchaOptions' の両方を指定します。
        </para>

        <programlisting language="php"><![CDATA[
// 単一の captcha キーの使用
$element = new Zend_Form_Element_Captcha('foo', array(
    'label' => "あなたが人間かどうかを確認します",
    'captcha' => array(
        'captcha' => 'Figlet',
        'wordLen' => 6,
        'timeout' => 300,
    ),
));

// captcha と captchaOptions の使用
$element = new Zend_Form_Element_Captcha('foo', array(
    'label' => "あなたが人間かどうかを確認します",
    'captcha' => 'Figlet',
    'captchaOptions' => array(
        'captcha' => 'Figlet',
        'wordLen' => 6,
        'timeout' => 300,
    ),
));
]]></programlisting>

        <para>
            使用するデコレータは、captcha アダプタの設定によって決まります。
            デフォルトでは <link
                linkend="zend.form.standardDecorators.captcha">Captcha
                デコレータ</link> を使用しますが、
            <methodname>getDecorator()</methodname> メソッドで別のアダプタを指定することもできます。
        </para>

        <para>
            captcha アダプタそれ自体は、要素のバリデータとして動作することに注意しましょう。
            さらに、NotEmpty バリデータは用いず、
            その要素は必須指定となります。
            ほとんどの場合は、フォームに captcha
            を表示させるために特に何もする必要はないでしょう。
        </para>
    </sect2>

    <sect2 id="zend.form.standardElements.checkbox">
        <title>Zend_Form_Element_Checkbox</title>

        <para>
            <acronym>HTML</acronym> のチェックボックスは指定した値を返すことができます。
            しかし、基本的には boolean として扱います。
            チェックされている場合はその値が送信され、
            チェックされていない場合はなにも送信されません。
            内部的に、<classname>Zend_Form_Element_Checkbox</classname> はこの状態を強制します。
        </para>

        <para>
            デフォルトでは、チェックされているときの値は '1'
            でチェックされていないときの値は '0' です。
            使用する値を指定するには、アクセサ
            <methodname>setCheckedValue()</methodname> および <methodname>setUncheckedValue()</methodname>
            をそれぞれ使用します。内部的には、この値を設定すると、
            渡された値が checked
            値と一致する場合はその値を設定しますが、
            それ以外の値が渡された場合は
            unchecked 値を設定します。
        </para>

        <para>
            さらに、値を設定するとチェックボックスの
            <property>checked</property> プロパティも設定されます。
            この内容を確認するには、<methodname>isChecked()</methodname>
            を使用するか、単純にそのプロパティにアクセスします。
            <methodname>setChecked($flag)</methodname> メソッドを使用すると、
            フラグの状態を設定すると同時に checked 値あるいは
            unchecked 値のいずれか適切なほうを要素の値として設定します。
            チェックボックス要素のチェック状態を設定するときには、
            このメソッドを使用してプロパティが適切に設定されるようにしましょう。
        </para>

        <para>
            <classname>Zend_Form_Element_Checkbox</classname> は 'formCheckbox'
            ビューヘルパーを使用します。
            値としては常に checked 値を使用します。
        </para>
    </sect2>

    <sect2 id="zend.form.standardElements.file">
        <title>Zend_Form_Element_File</title>

        <para>
            File フォーム要素は、ファイルアップロード用のフィールドをフォームに用意します。
            <link
                linkend="zend.file.transfer.introduction">Zend_File_Transfer</link>
            を内部で使用してこの機能を実現しており、
            <classname>FormFile</classname> ビューヘルパーと
            <classname>File</classname> デコレータでフォーム要素を表示しています。
        </para>

        <para>
            デフォルトでは、<classname>Http</classname> 転送アダプタを使用します。
            これは <code>$_FILES</code> 配列の中身を読み取り、
            バリデータやフィルタを使用できるようにします。
            フォーム要素にアタッチされたバリデータおよびアダプタが、
            この転送アダプタにアタッチされます。
        </para>

        <example id="zend.form.standardElements.file.usage">
            <title>File フォーム要素の使用法</title>

            <para>
                上の説明だけでは File フォーム要素を使うのが難しく感じられるかもしれません。
                でも、実際に使ってみると比較的簡単なものです。
            </para>

            <programlisting language="php"><![CDATA[
$element = new Zend_Form_Element_File('foo');
$element->setLabel('Upload an image:')
        ->setDestination('/var/www/upload');
// ファイルはひとつだけ
$element->addValidator('Count', false, 1);
// 最大で 100K
$element->addValidator('Size', false, 102400);
// JPEG、PNG および GIF のみ
$element->addValidator('Extension', false, 'jpg,png,gif');
$form->addElement($element, 'foo');
]]></programlisting>

            <para>
                また、正しいエンコード形式をフォームに指定する必要があります。
                'multipart/form-data' を使用しなければなりません。
                これは、フォームの 'enctype' 属性で指定します。
            </para>

            <programlisting language="php"><![CDATA[
$form->setAttrib('enctype', 'multipart/form-data');
]]></programlisting>

            <para>
                フォームの検証が成功したら、<methodname>receive()</methodname>
                でファイルを受信して最終的な場所に保存しなければなりません。
                さらに、最終的な場所を取得するには <methodname>getFileName()</methodname> を使用します。
            </para>

            <programlisting language="php"><![CDATA[
if (!$form->isValid()) {
    print "あららら... 検証エラー";
}

if (!$form->foo->receive()) {
    print "ファイル受信エラー";
}

$location = $form->foo->getFileName();
]]></programlisting>

        </example>

        <note>
            <title>デフォルトのアップロード先</title>

            <para>
                デフォルトでは、システムの
                temp ディレクトリにファイルがアップロードされます。
            </para>
        </note>

        <note>
            <title>File の値</title>

            <para>
                <acronym>HTTP</acronym> 内で、file 要素は値を持ちません。
                したがって、またセキュリティ上の理由もあって、
                <methodname>getValue()</methodname> ではアップロードしたファイル名だけしか取得できません。
                完全パスを取得することはできません。完全な情報が欲しい場合は、
                <methodname>getFileName()</methodname> をコールすればパスおよびファイル名が得られます。
            </para>
        </note>

        <note>
            <title>getFileName() の返り値</title>

            <para>
                getFileName() メソッドによって返される結果は、
                <!-- TODO : to be translated -->
                how many files the Zend_Form_Element_File uploaded
                によって変わります。
            <itemizedlist>
                <listitem>
                    <para>
                        単一のファイル: 単一のファイル名を含む文字列。
                    </para>
                </listitem>
                <listitem>
                    <para>
                        複数のファイル: 配列。各要素は、単一のファイル名を含む文字列です。
                    </para>
                </listitem>
                <listitem>
                    <para>
                        ファイル無し: 空の配列
                    </para>
                </listitem>
            </itemizedlist>
            </para>
        </note>

        <para>
            デフォルトでは、フォーム上で
            <methodname>getValues()</methodname> をコールしたときにファイルが自動的に受信されます。
            このような挙動となる理由は、ファイルそのものが file 要素の値となるからです。
        </para>

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

        <note>
            <para>
                したがって、<methodname>getValues()</methodname> をコールした後に改めて
                <methodname>receive()</methodname> をコールしても何も影響を及ぼしません。また、
                <classname>Zend_File_Transfer</classname> のインスタンスを作成しても何も影響を及ぼしません。
                受信すべきファイルはもうないからです。
            </para>
        </note>

        <para>
            しかし、ファイルを受信せずに <methodname>getValues()</methodname> をコールしたい場合もあるかもしれません。
            そのような場合は <methodname>setValueDisabled(true)</methodname> をコールします。
            このフラグの値を取得するには <methodname>isValueDisabled()</methodname> をコールします。
        </para>

        <example id="zend.form.standardElements.file.retrievement">
            <title>明示的なファイルの取得</title>

            <para>
                まずは <methodname>setValueDisabled(true)</methodname> をコールします。
            </para>

            <programlisting language="php"><![CDATA[
$element = new Zend_Form_Element_File('foo');
$element->setLabel('Upload an image:')
        ->setDestination('/var/www/upload')
        ->setValueDisabled(true);
]]></programlisting>

            <para>
                これで、 <methodname>getValues()</methodname> をコールしてもファイルは取得されなくなります。
                したがって、file 要素上で <methodname>receive()</methodname> をコールするか、
                あるいは <classname>Zend_File_Transfer</classname> のインスタンスを自分で作成しなければなりません。
            </para>

            <programlisting language="php"><![CDATA[
$values = $form->getValues();

if ($form->isValid($form->getPost())) {
    if (!$form->foo->receive()) {
        print "Upload error";
    }
}
]]></programlisting>
        </example>

        <para>
            アップロードされたファイルの状態については、次のメソッドで調べることができます。
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <methodname>isUploaded()</methodname>:
                    file 要素がアップロード済みかどうかを調べます。
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>isReceived()</methodname>:
                    file 要素を既に受信済みかどうかを調べます。
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>isFiltered()</methodname>:
                    フィルタが file 要素に適用済みかどうかを調べます。
                </para>
            </listitem>
        </itemizedlist>

        <example id="zend.form.standardElements.file.isuploaded">
            <title>オプションのファイルがアップロードされたかどうかの確認</title>

            <programlisting language="php"><![CDATA[
$element = new Zend_Form_Element_File('foo');
$element->setLabel('Upload an image:')
        ->setDestination('/var/www/upload')
        ->setRequired(false);
$element->addValidator('Size', false, 102400);
$form->addElement($element, 'foo');

// file 要素 foo はオプションですが、もしアップロードされた場合はここに到達します
if ($form->foo->isUploaded()) {
    // foo がアップロードされたので、ここで何かをします
}
]]></programlisting>
        </example>

        <para>
            <classname>Zend_Form_Element_File</classname> は複数のファイルもサポートしています。
            <methodname>setMultiFile($count)</methodname> メソッドをコールすると、
            作成したい file 要素の数を設定できます。
            これを使えば、同じ設定を何度も行う手間が省けます。
        </para>

        <example id="zend.form.standardElements.file.multiusage">
            <title>複数のファイルの設定</title>

            <para>
                複数の要素を作成する方法は、単一の要素を作成する場合と同じで、
                作成した後にさらに <methodname>setMultiFile()</methodname> をコールするだけです。
            </para>

            <programlisting language="php"><![CDATA[
$element = new Zend_Form_Element_File('foo');
$element->setLabel('Upload an image:')
        ->setDestination('/var/www/upload');
// ファイルの数を最小で 1、最大で 3 とします
$element->addValidator('Count', false, array('min' => 1, 'max' => 3));
// 100K までに制限します
$element->addValidator('Size', false, 102400);
// JPEG, PNG, および GIF のみを有効とします
$element->addValidator('Extension', false, 'jpg,png,gif');
// 3 つの file 要素を作成します
$element->setMultiFile(3);
$form->addElement($element, 'foo');
]]></programlisting>

            <para>
                ビューにおいて、同じ設定のファイルアップロード要素が 3 つ取得できます。
                現在設定されている値を取得するには
                <methodname>getMultiFile()</methodname> をコールします。
            </para>

        </example>

        <note>
            <title>サブフォームにおける File 要素</title>

            <para>
                file 要素をサブフォーム内で使う場合は、一意な名前を設定する必要があります。
                subform1 の file 要素を "file" という名前にしたのなら、
                subform2 ではそれと違う名前にしなければなりません。
            </para>

            <para>
                同名の file 要素が複数存在した場合、
                後から登場した要素は表示 (送信) されません。
            </para>

            <para>
                さらに、file 要素はサブフォーム内ではレンダリングされません。
                file 要素をサブフォームに追加する場合は、
                要素のレンダリングをメインフォームで行うことになります。
            </para>
        </note>

        <para>
            アップロードされるファイルのサイズを制限するには、
            フォームで受け付けるファイルサイズの最大値も設定しなければなりません。
            受け付けるサイズをクライアント側で制限するには、form のオプション
            <constant>MAX_FILE_SIZE</constant> を設定します。この値を
            <methodname>setMaxFileSize($size)</methodname> メソッドで設定すると、
            それが file 要素のレンダリング時に用いられます。
        </para>

        <programlisting language="php"><![CDATA[
$element = new Zend_Form_Element_File('foo');
$element->setLabel('Upload an image:')
        ->setDestination('/var/www/upload')
        ->addValidator('Size', false, 102400) // 100K までに制限します
        ->setMaxFileSize(102400); // ファイルサイズをクライアント側で制限します
$form->addElement($element, 'foo');
]]></programlisting>

        <note>
            <title>複数の file 要素がある場合の MaxFileSize</title>

            <para>
                複数の file 要素をフォームで使用する場合は、
                <constant>MAX_FILE_SIZE</constant> を設定する必要があるのは一度だけです。
                複数回設定すると、後から設定した値がそれまでの値を上書きします。
            </para>

            <para>
                また、複数のフォームを使用する場合であってもこれがあてはまることに注意しましょう。
            </para>
        </note>
    </sect2>

    <sect2 id="zend.form.standardElements.hidden">
        <title>Zend_Form_Element_Hidden</title>

        <para>
            Hidden 要素はただ単にデータを送信するだけのもので、
            ユーザはその値を変更してはいけません。
            <classname>Zend_Form_Element_Hidden</classname>
            は、この機能を 'formHidden' ビューヘルパーで実現します。
        </para>
    </sect2>

    <sect2 id="zend.form.standardElements.hash">
        <title>Zend_Form_Element_Hash</title>

        <para>
            この要素は CSRF 攻撃からフォームを保護するものです。
            送信されたデータがもとのフォームのユーザセッションからのものである
            (悪意のあるスクリプトからのものではない) ことを保証できるようにします。
            これを実現するために、フォームにハッシュ要素を追加して
            あとでそのハッシュを検証するようにしています。
        </para>

        <para>
            ハッシュ要素の名前は一意なものでなければなりません。
            この要素ではオプション <literal>salt</literal> を使うことを推奨します。
            名前が同じでも salt が異なればハッシュは衝突しません。
        </para>

        <programlisting language="php"><![CDATA[
$form->addElement('hash', 'no_csrf_foo', array('salt' => 'unique'));
]]></programlisting>

        <para>
            salt は、後から <methodname>setSalt($salt)</methodname>
            メソッドを使って設定することもできます。
        </para>

        <para>
            内部的には、この要素は一意な ID を
            <classname>Zend_Session_Namespace</classname> を用いて保存しており、
            送信されたときにその内容
            (TTL が期限切れになっていないかどうか) をチェックしています
            そして、'Identical' バリデータを使用して、
            送信されたハッシュと保存されているハッシュを比較します。
        </para>

        <para>
            'formHidden' ビューヘルパーを使用して要素をフォームにレンダリングします。
        </para>

        <note>
            <title>Zend_Form_Element_Hash を含むフォームをテスト</title>

            <!-- TODO : to be translated -->
            <para>
                When unit testing a form containing a <classname>Zend_Form_Element_Hash</classname> 
                it is necessary to call <methodname>initCsrfToken</methodname> and 
                <methodname>initCsrfValidator</methodname> before attempting to
                validate the form.  The hash value of the <classname>Zend_Form_Element_Hash</classname> 
                element must also be injected into the array of values passed as the
                argument to <methodname>Zend_Form::isValid</methodname>
            </para>
            <example id="zend.form.standardElements.hash.unittesting">
                <title>Simple example of testing a CSRF-protected form</title>
                <programlisting language="php"><![CDATA[
public function testCsrfProtectedForm() 
{
    $form = new Zend_Form();
    $form->addElement(new Zend_Form_Element_Hash('csrf'));

    $csrf = $form->getElement('csrf');
    $csrf->initCsrfToken();
    $csrf->initCsrfValidator();

    $this->assertTrue($form->isValid(array(
        'csrf' => $csrf->getHash()
    )));
}]]></programlisting>

            </example>
        </note>

    </sect2>

    <sect2 id="zend.form.standardElements.Image">
        <title>Zend_Form_Element_Image</title>

        <para>
            画像もフォーム要素として使用できます。
            これを用いると、フォームのボタンにグラフィカルな要素を指定したりできます。
        </para>

        <para>
            この要素には、元となる画像が必要です。
            <classname>Zend_Form_Element_Image</classname> では、それを
            <methodname>setImage()</methodname> アクセサ
            (あるいは設定キー 'image') で設定します。
            また、画像を submit したときに使用する値は、
            <methodname>setImageValue()</methodname> アクセサ
            (あるいは設定キー 'imageValue') でオプションとして設定できます。
            その要素に設定された値が
            <property>imageValue</property> とマッチした場合、アクセサ
            <methodname>isChecked()</methodname> は <constant>TRUE</constant> を返します。
        </para>

        <para>
            Image 要素はその value を元画像として使用し、
            <link linkend="zend.form.standardDecorators.image">Image
            デコレータ</link> でレンダリングを行います
            (それ以外に標準のデコレータ Errors、HtmlTag および Label も使用します)。
            オプションのタグを <classname>Image</classname> デコレータに指定すると、
            それで image 要素をラップできます。
        </para>
    </sect2>

    <sect2 id="zend.form.standardElements.multiCheckbox">
        <title>Zend_Form_Element_MultiCheckbox</title>

        <para>
            関連する複数のチェックボックスをひとまとめにし、
            結果をグループ化して扱いたいこともあるでしょう。ちょうど
            <link
                linkend="zend.form.standardElements.multiselect">Multiselect</link>
            に似ていますが、ドロップダウンリストではなく
            チェックボックス形式で表示させたいのです。
        </para>

        <para>
            <classname>Zend_Form_Element_MultiCheckbox</classname> は
            それを行うためのものです。Multi 要素を継承したその他の要素を同様に、
            選択肢のリストを指定してそれらを同じ方法で検証できます。
            'formMultiCheckbox' ビューヘルパーを使用して、
            フォームの送信内容を配列で返すようにします。
        </para>

        <para>
            デフォルトでは、この要素は <classname>InArray</classname>
            バリデータを登録します。このバリデータは、
            登録されたオプションの配列のキーに対して検証を行います。
            この振る舞いを無効にするには
            <methodname>setRegisterInArrayValidator(false)</methodname>
            をコールするか、あるいは設定キー
            <property>registerInArrayValidator</property>
            に <constant>FALSE</constant> 値を渡します。
        </para>

        <para>
            チェックボックスのオプションを操作するには、
            次のメソッドを使用します。
        </para>

        <itemizedlist>
            <listitem><para><methodname>addMultiOption($option, $value)</methodname></para></listitem>

            <listitem><para><methodname>addMultiOptions(array $options)</methodname></para></listitem>

            <listitem><para><methodname>setMultiOptions(array $options)</methodname>
                    (既存のオプションを上書きします)</para></listitem>

            <listitem><para><methodname>getMultiOption($option)</methodname></para></listitem>

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

            <listitem><para><methodname>removeMultiOption($option)</methodname></para></listitem>

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

        <para>
            チェックされた項目を指定するには、値の配列を
            <methodname>setValue()</methodname> に渡す必要があります。
            次の例は、値 "bar" と "bat" をチェックします。
        </para>

        <programlisting language="php"><![CDATA[
$element = new Zend_Form_Element_MultiCheckbox('foo', array(
    'multiOptions' => array(
        'foo' => 'Foo Option',
        'bar' => 'Bar Option',
        'baz' => 'Baz Option',
        'bat' => 'Bat Option',
    )
));

$element->setValue(array('bar', 'bat'));
]]></programlisting>

        <para>
            値をひとつだけ指定する場合でも、配列形式でなければならないことに注意しましょう。
        </para>
    </sect2>

    <sect2 id="zend.form.standardElements.multiselect">
        <title>Zend_Form_Element_Multiselect</title>

        <para>
            <acronym>XHTML</acronym> の <emphasis>select</emphasis> 要素には 'multiple'
            属性を指定できます。
            これは、普通の要素ではなく複数項目を選択できる要素を表します。
            <classname>Zend_Form_Element_Multiselect</classname> は、
            <link
                linkend="zend.form.standardElements.select">Zend_Form_Element_Select</link>
            を継承して <property>multiple</property> 要素を 'multiple'
            に設定したものです。基底クラス <classname>Zend_Form_Element_Multi</classname>
            を継承したその他のクラスと同様、以下のメソッドでオプションを操作できます。
        </para>

        <itemizedlist>
            <listitem><para><methodname>addMultiOption($option, $value)</methodname></para></listitem>

            <listitem><para><methodname>addMultiOptions(array $options)</methodname></para></listitem>

            <listitem><para><methodname>setMultiOptions(array $options)</methodname>
                    (既存のオプションを上書きします)</para></listitem>

            <listitem><para><methodname>getMultiOption($option)</methodname></para></listitem>

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

            <listitem><para><methodname>removeMultiOption($option)</methodname></para></listitem>

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

        <para>
            フォームや要素に翻訳アダプタが登録されている場合は、
            表示時にオプションの値が翻訳されます。
        </para>

        <para>
            デフォルトでは、この要素は <classname>InArray</classname>
            バリデータを登録します。このバリデータは、
            登録されたオプションの配列のキーに対して検証を行います。
            この振る舞いを無効にするには
            <methodname>setRegisterInArrayValidator(false)</methodname>
            をコールするか、あるいは設定キー
            <property>registerInArrayValidator</property>
            に <constant>FALSE</constant> 値を渡します。
        </para>
    </sect2>

    <sect2 id="zend.form.standardElements.password">
        <title>Zend_Form_Element_Password</title>

        <para>
            Password 要素は、基本的には通常の text 要素と同じです。
            しかし、フォームの再描画時やエラーメッセージなどに
            入力内容を表示させないようにします。
        </para>

        <para>
            <classname>Zend_Form_Element_Password</classname> は、これを実現するために
            各バリデータ上で <methodname>setObscureValue(true)</methodname>
            (検証エラーの際のメッセージでパスワードを表示させない)
            をコールし、'formPassword' ビューヘルパー (渡された値を表示しない)
            を使用します。
        </para>
    </sect2>

    <sect2 id="zend.form.standardElements.radio">
        <title>Zend_Form_Element_Radio</title>

        <para>
            Radio 要素は、いくつかの選択肢を指定してその中から
            ひとつを選ばせるためのものです。
            <classname>Zend_Form_Element_Radio</classname> は規定クラス
            <classname>Zend_Form_Element_Multi</classname> を継承したもので、
            複数のオプションを指定できます。そして、それを表示するために
            <emphasis>formRadio</emphasis> ビューヘルパーを使用します。
        </para>

        <para>
            デフォルトでは、この要素は <classname>InArray</classname>
            バリデータを登録します。このバリデータは、
            登録されたオプションの配列のキーに対して検証を行います。
            この振る舞いを無効にするには
            <methodname>setRegisterInArrayValidator(false)</methodname>
            をコールするか、あるいは設定キー
            <property>registerInArrayValidator</property>
            に <constant>FALSE</constant> 値を渡します。
        </para>

        <para>
            Multi 要素基底クラスを継承したその他のクラスと同様、
            以下のメソッドでラジオボタンの表示オプションを操作できます。
        </para>

        <itemizedlist>
            <listitem><para><methodname>addMultiOption($option, $value)</methodname></para></listitem>

            <listitem><para><methodname>addMultiOptions(array $options)</methodname></para></listitem>

            <listitem><para><methodname>setMultiOptions(array $options)</methodname>
                    (既存のオプションを上書きします)</para></listitem>

            <listitem><para><methodname>getMultiOption($option)</methodname></para></listitem>

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

            <listitem><para><methodname>removeMultiOption($option)</methodname></para></listitem>

            <listitem><para><methodname>clearMultiOptions()</methodname></para></listitem>
        </itemizedlist>
    </sect2>

    <sect2 id="zend.form.standardElements.reset">
        <title>Zend_Form_Element_Reset</title>

        <para>
            Reset ボタンはフォームの入力内容をクリアするために使用します。
            データは送信されません。しかし、表示時の役割があるため、
            標準要素のひとつとして組み込まれています。
        </para>

        <para>
            <classname>Zend_Form_Element_Reset</classname> は <link
                linkend="zend.form.standardElements.submit">Zend_Form_Element_Submit</link>
            を継承しています。ボタンの表示時にはラベルを使用し、
            翻訳アダプタが存在する場合はそれが翻訳されます。
            この要素が使用するデコレータは
            'ViewHelper' と 'DtDdWrapper' のみです。
            この要素にはエラーメッセージがなく、またラベルも必須ではないからです。
        </para>
    </sect2>

    <sect2 id="zend.form.standardElements.select">
        <title>Zend_Form_Element_Select</title>

        <para>
            セレクトボックスは、指定したデータの中から選択させたいときに使用するものです。
            <classname>Zend_Form_Element_Select</classname> は、
            セレクトボックスをお手軽に作成します。
        </para>

        <para>
            デフォルトでは、この要素は <classname>InArray</classname>
            バリデータを登録します。このバリデータは、
            登録されたオプションの配列のキーに対して検証を行います。
            この振る舞いを無効にするには
            <methodname>setRegisterInArrayValidator(false)</methodname>
            をコールするか、あるいは設定キー
            <property>registerInArrayValidator</property>
            に <constant>FALSE</constant> 値を渡します。
        </para>

        <para>
            Multi 要素を継承したその他のクラスと同様、
            以下のメソッドでオプションを操作できます。
        </para>

        <itemizedlist>
            <listitem><para><methodname>addMultiOption($option, $value)</methodname></para></listitem>

            <listitem><para><methodname>addMultiOptions(array $options)</methodname></para></listitem>

            <listitem><para><methodname>setMultiOptions(array $options)</methodname>
                    (既存のオプションを上書きします)</para></listitem>

            <listitem><para><methodname>getMultiOption($option)</methodname></para></listitem>

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

            <listitem><para><methodname>removeMultiOption($option)</methodname></para></listitem>

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

        <para>
            <classname>Zend_Form_Element_Select</classname> は 'formSelect'
            ビューヘルパーでデコレートを行います。
        </para>
    </sect2>

    <sect2 id="zend.form.standardElements.submit">
        <title>Zend_Form_Element_Submit</title>

        <para>
            Submit ボタンはフォームの内容を送信するための要素です。
            複数の submit ボタンを使用することもできます。
            どの submit ボタンでデータを送信したかによって、
            どのアクションを実行するのかを切り替えることができます。
            <classname>Zend_Form_Element_Submit</classname> では、この判断をしやすくするために
            <methodname>isChecked()</methodname> メソッドを用意しています。
            フォームから送信される submit ボタンはひとつだけなので、
            各 submit 要素に対してこのメソッドをコールすることで
            どのボタンが押されたのかを判断できます。
        </para>

        <para>
            <classname>Zend_Form_Element_Submit</classname> はラベルを submit ボタンの
            "値" として使用します。翻訳アダプタが存在する場合はこれを翻訳します。
            <methodname>isChecked()</methodname> は、送信された値をこのラベルと比較し、
            そのボタンが押されたのかどうかを判断します。
        </para>

        <para>
            <link
                linkend="zend.form.standardDecorators.viewHelper">ViewHelper</link>
            デコレータと <link
                linkend="zend.form.standardDecorators.dtDdWrapper">DtDdWrapper</link>
            デコレータを使用して要素をレンダリングします。label
            デコレータは使用しません。要素のレンダリング時にはボタンのラベルを使用するからです。
            また、一般的には submit 要素にはエラーを関連付けません。
        </para>
    </sect2>

    <sect2 id="zend.form.standardElements.text">
        <title>Zend_Form_Element_Text</title>

        <para>
            最もよく用いられているフォーム要素は text 要素です。
            これはテキスト入力用の要素で、大半の入力項目に適しています。
            <classname>Zend_Form_Element_Text</classname> は、単純に
            'formText' ビューヘルパーを使用して要素を表示します。
        </para>
    </sect2>

    <sect2 id="zend.form.standardElements.textarea">
        <title>Zend_Form_Element_Textarea</title>

        <para>
            Textarea は大量のテキストを入力させるために使用します。
            テキストの量に制限を設けません (サーバや <acronym>PHP</acronym>
            の設定による制限は除きます)。
            <classname>Zend_Form_Element_Textarea</classname> は
            'textArea' ビューヘルパーを使用して要素とその値を表示します。
        </para>
    </sect2>
</sect1>
<!--
vim:se ts=4 sw=4 tw=80 et:
-->