<commit_before><!-- EN-Revision: 8360 -->
<sect1 id="zend.form.standardElements">
    <title>Zend Framework に同梱されている標準のフォーム要素</title>

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

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

        <para>
            HTML の button 要素を作成する際に使用します。
            <code>Zend_Form_Element_Button</code> は <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>
            フォームの表示や検証の後で、
            そのボタンが押されたかどうかを調べたい場合は
            <code>isChecked()</code> メソッドを使用します。
        </para>
    </sect2>

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

        <para>
            HTML の checkbox は boolean 値を保持し、それぞれオン・オフを表します。
            <code>Zend_Form_Element_Checkbox</code> は、これを
            <code>setValue()</code> で保証します。null 値が渡された場合は
            その値を 0 として保存し、それ以外の場合は 1
            として保存します (HTML フォームのチェックボックスは、
            チェックされた場合にその要素のキーのみ (値は空) を送信します)。
            値が 0 の場合は <code>checked</code> 属性がオン、
            値が 1 の場合はその逆となります。デフォルトの値は 0
            です。
        </para>

        <para>
            <code>Zend_Form_Element_Checkbox</code> は 'formCheckbox'
            ビューヘルパーを使用します。
        </para>
    </sect2>

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

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

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

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

        <para>
            ハッシュ要素の名前は一意なものでなければなりません。
            この要素ではオプション <literal>salt</literal> を使うことを推奨します。
            名前が同じでも salt が異なればハッシュは衝突しません。<commit_msg>sync Japanese document with r8631.<commit_after><!-- EN-Revision: 8631 -->
<sect1 id="zend.form.standardElements">
    <title>Zend Framework に同梱されている標準のフォーム要素</title>

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

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

        <para>
            HTML の button 要素を作成する際に使用します。
            <code>Zend_Form_Element_Button</code> は <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>
            フォームの表示や検証の後で、
            そのボタンが押されたかどうかを調べたい場合は
            <code>isChecked()</code> メソッドを使用します。
        </para>
    </sect2>

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

        <para>
            HTML のチェックボックスは指定した値を返すことができます。
            しかし、基本的には boolean として扱います。
            チェックされている場合はその値が送信され、
            チェックされていない場合はなにも送信されません。
            内部的に、Zend_Form_Element_Checkbox はこの状態を強制します。
        </para>
            
        <para>
            デフォルトでは、チェックされているときの値は '1'
            でチェックされていないときの値は '0' です。
            使用する値を指定するには、アクセサ
            <code>setCheckedValue()</code> および <code>setUncheckedValue()</code>
            をそれぞれ使用します。内部的には、この値を設定すると、
            渡された値が checked
            値と一致する場合はその値を設定しますが、
            それ以外の値が渡された場合は
            unchecked 値を設定します。
        </para>

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

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

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

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

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

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

        <para>
            ハッシュ要素の名前は一意なものでなければなりません。
            この要素ではオプション <literal>salt</literal> を使うことを推奨します。
            名前が同じでも salt が異なればハッシュは衝突しません。
{'fraction_non_alphanumeric': 0.08737117366558991, 'fraction_numerical': 0.005383787109675435, 'mean_word_length': 2.034064395706953, 'pattern_counts': {'":': 0, '<': 131, '<?xml version=': 0, '>': 131, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2404776', 'n_tokens_mistral': 3373, 'n_tokens_neox': 3106, 'n_words': 290}