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

<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 按钮元素， <code>Zend_Form_Element_Button</code> 继承 <link linkend="zend.form.standardElements.submit">Zend_Form_Element_Submit</link>，并派生它的定制功能。它为装饰指定 'formButton' 视图助手。
        </para>

        <para>
            像提交元素一样，它使用元素的标签作为元素的值来显示，还句话说，通过设置元素的值来设置按钮上的文字。如果有翻译适配器，标签将显示翻译后的文字。
        </para>

        <para>
            因为标签用作元素的一部分，但按钮元素只用 <link linkend="zend.form.standardDecorators.viewHelper">ViewHelper</link> 和 <link linkend="zend.form.standardDecorators.dtDdWrapper">DtDdWrapper</link> 装饰器。
        </para>
    </sect2>

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

        <para>
            HTML checkboxes 让你返回一个特定的值，但基本上以布尔来操作：当它被 check，值就被提交；当没有 check，什么都不提交。在内部，<code>Zend_Form_Element_Checkbox</code> 强制这个状态。
        </para>

        <para>
            缺省地，已选的值是 '1'，未选的值是 '0'。你可以通过 <code>setCheckedValue()</code> 和 <code>setUncheckedValue()</code> 访问器分别来指定使用的值。在内部，任何时候你设置这个值，如果提供的值和已选的值匹配，那就是设置了，但是任何其它的值都可以使未选的值设置了。
        </para>

        <para>
            另外，设置 checkbox 的 <code>checked</code> 属性的值。你可以用 <code>isChecked()</code> 或 访问这个属性来查询它。使用 <code>setChecked($flag)</code> 方法将设置标志的状态和元素中合适的已选的和未选的值。当设置 checkbox 元素的已选的状态请使用这个方法以确保设置合适的值。
        </para>

        <para>
            <code>Zend_Form_Element_Checkbox</code> 使用 'formCheckbox' 视图助手。已选的值总用来组装它。
        </para>
    </sect2>

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

        <para>
            隐藏元素的数据只提交，用户不用处理。 <code>Zend_Form_Element_Hidden</code> 使用 'formHidden' 视图助手来完成它。
        </para>
    </sect2>

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

        <para>
            该元素提供保护以防止 CSRF 攻击表单，确保提交的数据来自于用户的会话，而不是流氓脚本。保护是通过添加一个哈希（hash）元素给表单并在表单提交时校验它来达成的。
        </para>

        <para>
            哈希（hash）元素名是唯一的。建议使用 <literal>salt</literal> 选项，两个哈希有相同的名字和不同的 salt 会有冲突的：
        </para>

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

        <para>
            你可以稍后使用 <code>setSalt($salt)</code> 方法设置 salt。
        </para>

        <para>
            在内部，元素用 <code>Zend_Session_Namespace</code> 存储一个独一无二的识别符，并在提交的时候检查它（检查 TTL 没有过期）。'Identical' 校验器用于确保提交和哈希和存储的哈希匹配。
        </para>

        <para>
            'formHidden' 视图助手用来解析在表单中的元素。
        </para>
    </sect2>

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

        <para>
            图像也可以用作表单元素，并允许你指定图形元素作为表单按钮。
        </para>

        <para>
            图像需要图像源文件。<code>Zend_Form_Element_Image</code> 让你用 <code>setImage()</code> 指定它（或 'image' 配置键）。当提交图像时，你也可以用 <code>setImageValue()</code> 访问器（或 'imageValue' 配置键）可选地指定一个值给它来用。当元素值匹配 <code>imageValue</code> 时，访问器 <code>isChecked()</code> 返回 true。
        </para>

        <para>
            图像元素使用 <link linkend="zend.form.standardDecorators.image"> 图像装饰器 </link> 来解析 （还有标准错误、 HtmlTag 和 Label 装饰器）。你可以可选地指定一个标签（tag）给<code> 图像 </code>装饰器，它将封装图像元素。
        </para>
    </sect2>

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

        <para>
            你经常会有一组相关的 checkboxes，并且想把结果组成组，这个很像 <link linkend="zend.form.standardElements.multiselect">Multiselect</link>，但是这个不是下拉列表，而是需要显示 checkbox/值对。
        </para>

        <para>
            <code>Zend_Form_Element_MultiCheckbox</code> makes this a snap。像其它继承基础多重元素的元素，你可以指定一个选项列表，并很容易依靠这个列表来校验。'formMultiCheckbox' 视图助手确保这些在表单提交后返回数组。
        </para>

        <para>
            你可以用下列方法操作各种 checkbox 选项：
        </para>

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

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

            <listitem><para><code>setMultiOptions(array $options)</code>
                    （重写已存在的选项）</para></listitem>

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

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

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

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

        <para>
            为了标记选中的条目，需要传递一个数组给 <code>setValue()</code> 。下面代码片段将检查 "bar" 和 "bat":
        </para>

        <programlisting role="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>
            XHTML <code>select</code> 元素允许一个 'multiple' 属性，表明可以提交多重选项，而不是一个。<code>Zend_Form_Element_Multiselect</code> 继承 <link linkend="zend.form.standardElements.select">Zend_Form_Element_Select</link> 并设置 <code>multiple</code> 属性为 'multiple' 。像其它从 <code>Zend_Form_Element_Multi</code> 基础类继承的类一样，你可以使用下列函数来处理选项的选择：
        </para>

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

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

            <listitem><para><code>setMultiOptions(array $options)</code>
                    （重写已存在的选项）</para></listitem>

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

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

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

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

        <para>
            如果翻译适配器随表单和/或元素注册，选项值将被翻译用于显示。
        </para>
    </sect2>

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

        <para>
            密码元素基本上是普通的文本元素 －－ 除了你不想它以错误消息的形式显示或重新显示表单的时候显示出来。
        </para>

        <para>
            <code>Zend_Form_Element_Password</code> 在每个校验器（确保密码在校验器错误消息上是不透明的）通过调用 <code>setObscureValue(true)</code> 和使用 'formPassword' 视图助手（它不显示传递给它的值）来完成它。
        </para>
    </sect2>

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

        <para>
            Radio 元素让你指定若干选项，而你只需要一个返回值。<code>Zend_Form_Element_Radio</code> 继承基础类  <code>Zend_Form_Element_Multi</code>，让你指定若干选项并使用 <code>formRadio</code> 视图助手来显示。
        </para>

        <para>
            像其它所有继承多重元素基础类的元素，下列方法可用来处理 radio 选项的显示：
        </para>

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

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

            <listitem><para><code>setMultiOptions(array $options)</code>
                    （重写已存在的选项）</para></listitem>

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

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

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

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

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

        <para>
            Reset 按钮一般用于清理表单，而不是要提交的数据。然而，因为它们用于显示，所以它们属于标准元素。
        </para>

        <para>
            <code>Zend_Form_Element_Reset</code> 继承 <link linkend="zend.form.standardElements.submit">Zend_Form_Element_Submit</link>。这样，标签（label）用于按钮显示，如果有翻译适配器，显示的内容就被翻译。它只使用 'ViewHelper' 和 'DtDdWrapper'装饰器，因为绝对不会有错误消息，也不会有标签（label）。
        </para>
    </sect2>

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

        <para>
            Select boxes 是限定从给定数据里选择的一个通用的办法。<code>Zend_Form_Element_Select</code> 让你迅速简便地完成它。
        </para>

        <para>
            因为它继承基础多重元素，下列方法可用来处理选择选项：
        </para>

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

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

            <listitem><para><code>setMultiOptions(array $options)</code>
                    (overwrites existing options)</para></listitem>

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

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

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

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

        <para>
            <code>Zend_Form_Element_Select</code> 使用 'formSelect' 视图助手来装饰。
        </para>
    </sect2>

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

        <para>
            提交按钮用于提交表单。你可以使用多个提交按钮，你可以使用按钮提交表单来决定哪个动作处理提交的数据。<code>Zend_Form_Element_Submit</code> 通过添加 <code>isChecked()</code>方法使决定变得容易。因为只有一个按钮由表单来提交，在处理和校验表单之后，你可以在每个提交按钮上调用这个方法来确定使用了哪个。
        </para>

        <para>
            <code>Zend_Form_Element_Submit</code> 使用标签作为提交按钮的 "value"，如果有翻译适配器就翻译它。<code>isChecked()</code>  为了确定是否使用了该按钮，依靠标签（label）来检查提交的值。
        </para>

        <para>
            <link linkend="zend.form.standardDecorators.viewHelper">ViewHelper</link> 和 <link linkend="zend.form.standardDecorators.dtDdWrapper">DtDdWrapper</link> 装饰器解析元素。没有使用标签（label）装饰器，因为当解析元素时使用了按钮标签，一般地，对于提交元素不需要错误（代码或消息）。
        </para>
    </sect2>

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

        <para>
            到目前为止，大部分流行的表单元素是文本元素，对于有限的文本输入，对大部分数据输入来说是个理想的元素。<code>Zend_Form_Element_Text</code> 使用 'formText' 视图助手来显示元素。
        </para>
    </sect2>

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

        <para>
            Textareas 用于大量的文本处理，对提交的文本的长度没有限制（除非你的服务器或PHP有限制）。<code>Zend_Form_Element_Textarea</code> 使用 'textArea' 视图助手来显示元素，值就是元素的内容。
        </para>
    </sect2>
</sect1>
<!--
vim:se ts=4 sw=4 tw=80 et:
-->