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

<sect1 id="zend.form.elements">
    <title> 使用 Zend_Form_Element 生成表单元素 </title>

    <para>
        表单由元素组成，它一般对应于 HTML 表单输入。Zend_Form_Element 封装了单个表单元素，并完成下列工作：
    </para>

    <itemizedlist>
        <listitem>
            <para>
                校验（提交的数据有效乎？）
            </para>

            <itemizedlist>
                <listitem><para> 抓取校验错误代码和消息 </para></listitem>
            </itemizedlist>
        </listitem>

        <listitem><para>
            过滤（在校验和/或输出之前元素如何转义或规范化？）
        </para></listitem>

        <listitem><para>
            解析（元素如何显示？）
        </para></listitem>

        <listitem><para>
            元数据和属性（什么信息进一步修饰元素？）
        </para></listitem>
    </itemizedlist>

    <para>
        基础类 <code>Zend_Form_Element</code> 对许多类有合理的缺省设置，但最好还是继承这个类来完成特殊意图的元素。另外，Zend Framework 带有许多标准的 XHTML 元素，请阅读 <link linkend="zend.form.standardElements"> 在标准元素一章 </link> 的有关文档。
    </para>

    <sect2 id="zend.form.elements.loaders">
        <title> 插件加载器 </title>

        <para>
            <code>Zend_Form_Element</code> 利用 <link linkend="zend.loader.pluginloader">Zend_Loader_PluginLoader</link> 来使开发者指定替代校验器、过滤器和装饰器的位置。每个都有它自己携带的插件加载器，并使用通用的访问器来读取或修改它们。
        </para>

        <para>
            下列加载器类型和各种各样的插件加载器方法一起使用：'validate'、 'filter' 和 'decorator'。类型名是大小写敏感的。
        </para>

        <para>
            和插件加载器交互使用的方法如下：
        </para>

        <itemizedlist>
            <listitem><para>
                <code>setPluginLoader($loader, $type)</code>：<code>$loader</code> 是插件加载器对象自己，而  <code>$type</code> 是上述类型之一。这个方法为给定类型的插件加载器设置为最新的特定的载器对象。
            </para></listitem>

            <listitem><para>
                <code>getPluginLoader($type)</code>: 用携带的 <code>$type</code> 来读取插件加载器。
            </para></listitem>

            <listitem><para>
                <code>addPrefixPath($prefix, $path, $type = null)</code>: 添加 prefix/path 联合给由 <code>$type</code> 指定的加载器。如果 <code>$type</code> 是 null，它将尝试通过追加前缀给 "_Validate"、"_Filter", 和 "_Decorator" 来添加路径到所有加载器，并用 "Validate/"、"Filter/" 和 "Decorator/".  追加路径。如果你在通用的等级下有所有额外的表单元素类，这是个用来设置基础前缀给它们的方便的方法。
            </para></listitem>

            <listitem><para>
                <code>addPrefixPaths(array $spec)</code>: 让你一次性添加许多路径给一个或多个插件加载器。它需要每个数组条目是个带有 'path'、'prefix' 和 'type'. 键的数组。
            </para></listitem>
        </itemizedlist>

        <para>
            定制的校验器、过滤器和装饰器是在表单和封装定制功能之间共享功能的简单的办法。
        </para>

        <example id="zend.form.elements.loaders.customLabel">
            <title> 定制标签 </title>

            <para>
                插件的一个普通用例是来为标准类提供替换。例如，如果想实现一个不同的 'Label' 装饰器 －－ 如总要追加冒号 －－你可以创建你自己的带有类前缀的 'Label' 装饰器，然后把它加到你的前缀路径。
            </para>

            <para>
                让我们从定制标签装饰器来开始，给它一个类前缀 "My_Decorator"，类文件就是 "My/Decorator/Label.php"。
            </para>

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

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

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

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

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

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

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

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

            <para>
                现在，当元素寻找装饰器时，就使用这个插件路径：
            </para>

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

            <para>
                另外，我们可以在表单一级来做以确保所有的装饰器使用这个路径：
            </para>

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

            <para>
                用这个添加的路径，当添加一个装饰器，将首先搜索 'My/Decorator/' 路径来检查是否存在装饰器。结果，如果请求 'Label' 装饰器，'My_Decorator_Label' 将被使用。
            </para>
        </example>
    </sect2>

    <sect2 id="zend.form.elements.filters">
        <title> 过滤器 </title>

        <para>
            在校验之前对输入执行规范化常常是有用的并/或必需的 － 例如，你可能想要剥离所有 HTML，在剩下的东东上运行校验来确保提交有效。或者你可能想把输入的数据两边的空格都消掉，这样 StringLength 校验器就不会返回失败。这些操作使用 <code>Zend_Filter</code> 来执行，并且 <code>Zend_Form_Element</code> 对过滤链有支持，让你指定多个连续的过滤器来用。在校验期间和通过 <code>getValue()</code> 读取元素值的时候都会发生校验：
        </para>

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

        <para>
            有两个办法添加过滤器：
        </para>

        <itemizedlist>
            <listitem><para>
                传递一个具体的过滤器实例
            </para></listitem>

            <listitem><para>
                提供过滤器名称 － 短名或完整的类名都可以
            </para></listitem>
        </itemizedlist>

        <para>
            看一些例子：
        </para>

        <programlisting role="php"><![CDATA[<?php
// 具体的过滤器实例：
$element->addFilter(new Zend_Filter_Alnum());

// 合格的全类名：
$element->addFilter('Zend_Filter_Alnum');

// 短过滤器名：
$element->addFilter('Alnum');
$element->addFilter('alnum');
?>]]></programlisting>

        <para>
            短名一般就是过滤器名去掉前缀，缺省就是去掉 'Zend_Filter_' 前缀。另外，首字母不需要大写。
        </para>

        <note>
            <title> 使用定制的过滤器类 </title>

            <para>
                如果你有自己的一组过滤器，可以通过 <code>addPrefixPath()</code> 来告诉 <code>Zend_Form_Element</code>。例如，如果你在 'My_Filter' 前缀下有过滤器，这样来告诉  <code>Zend_Form_Element</code>：
            </para>

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

            <para>
                （回忆一下第三个参数用来指示哪个是执行这个动作的插件加载器）
            </para>
        </note>

        <para>
            任何时候需要非过滤的数据，使用 <code>getUnfilteredValue()</code> 方法：
        </para>

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

        <para>
            参见 <link linkend="zend.filter.introduction">Zend_Filter 文档 </link> 有更多关于过滤器的信息。
        </para>

        <para>
            过滤器带有这些方法：
        </para>

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

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

            <listitem><para>
                <code>setFilters(array $filters)</code> （重写所有过滤器）
            </para></listitem>

            <listitem><para>
                <code>getFilter($name)</code> （按名字读取过滤器对象）
            </para></listitem>

            <listitem><para>
                <code>getFilters()</code> （读取所有过滤器）
            </para></listitem>

            <listitem><para>
                <code>removeFilter($name)</code> （按名字删除过滤器）
            </para></listitem>

            <listitem><para>
                <code>clearFilters()</code> （删除所有过滤器）
            </para></listitem>
        </itemizedlist>
    </sect2>

    <sect2 id="zend.form.elements.validators">
        <title> 校验器 </title>

        <para>
            如果你赞同安全咒语“过滤输入，转义输出”，你将会校验（“过滤输入”）你的表单输入。 在 <code>Zend_Form</code> 里，每个元素包含它自己的由 <code>Zend_Validate_*</code> 校验器组成的校验器链。
        </para>

        <para>
            两个办法添加校验器到校验器链：
        </para>

        <itemizedlist>
            <listitem><para>
                传递一个具体的校验器实例
            </para></listitem>

            <listitem><para>
                提供一个校验器名 － 短名或者完整的类名都可以
            </para></listitem>
        </itemizedlist>

        <para>
            看一些例子：
        </para>

        <programlisting role="php"><![CDATA[<?php
// Concrete validator instance:
$element->addValidator(new Zend_Validate_Alnum());

// Fully qualified class name:
$element->addValidator('Zend_Validate_Alnum');

// Short validator name:
$element->addValidator('Alnum');
$element->addValidator('alnum');
?>]]></programlisting>

        <para>
            短名一般就是校验器名去掉前缀，缺省就是去掉 'Zend_Validate_' 前缀。另外，首字母不需要大写。
        </para>

        <note>
            <title> 使用定制的校验器类 </title>

            <para>
                如果你有自己的一组校验器，可以通过 <code>addPrefixPath()</code> 来告诉 <code>Zend_Form_Element</code>。例如，如果你在 'My_Validator' 前缀下有校验器，这样来告诉  <code>Zend_Form_Element</code>：
            </para>

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

            <para>
                （回忆一下第三个参数用来指示哪个是执行这个动作的插件加载器）
            </para>
        </note>

        <para>
            如果特定的校验失败，为阻止后面的校验工作，传递第二个参数 <code>true</code> （布尔型）：
        </para>

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

        <para>
            如果你使用一个字符串名来添加一个校验器，并且这个校验器接受参数给构造器，你可以把这个第三个参数 <code>addValidator()</code> 作为数组传递：
        </para>

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

        <para>
            这样传递参数应该按照它们在构造器里定义的顺序进行。上述例子将带参数 <code>$min</code> 和 <code>$max</code> 实例化 <code>Zend_Validate_StringLenth</code> 类：
        </para>

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

        <note>
            <title> 提供定制的校验错误消息 </title>

            <para>
                有些开发者可能想为校验器提供定制的错误消息。 <code>Zend_Form_Element::addValidator()</code> 的 <code>$options</code> 参数让你通过提供 'messages' 键并把它设置为键/值对（用来设置消息模板）的数组来完成。你需要知道特定校验器的各种各样的校验错误类型的错误代码。
            </para>

            <para>
                稍好的选择是在表单中使用 <code>Zend_Translate_Adapter</code>。错误代码通过缺省的错误装饰器自动传递给适配器，然后你可以通过为你的校验器的各种错误代码设置翻译来指定自己的错误消息字符串。
            </para>
        </note>

        <para>
            你也可以使用 <code>addValidators()</code> 一次性设置许多校验器。基本的用法是传递数组的数组，每个数组包含 1 到 3 个匹配 <code>addValidator()</code> 的构造器的值：
        </para>

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

        <para>
            如果你想做的更明确和更详细，可以使用数组键 'validator'、 'breakChainOnFailure' 和 'options'：
        </para>

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

        <para>
            这个用法展示如何在配置文件中配置校验器：
        </para>

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

        <para>
            注意每个条目有一个键，不管是否需要，这是使用配置文件规定的 －－但它也帮助清楚理解哪个参数用于什么。请记住任何校验器选项必需按顺序指定。
        </para>

        <para>
            为校验一个元素，传递值给 <code>isValid()</code>：
        </para>

        <programlisting role="php"><![CDATA[<?php
if ($element->isValid($value)) {
    // valid
} else {
    // invalid
}
?>]]></programlisting>

        <note>
            <title> 在过滤后的值上校验 </title>

            <para>
                <code>Zend_Form_Element::isValid()</code> 在校验之前通过提供过滤器链来过滤（输入）值。见 See <link linkend="zend.form.elements.filters"> 过滤器一节 </link> 有更多信息。
            </para>
        </note>

        <note>
            <title> 校验上下文 </title>

            <para>
                <code>Zend_Form_Element::isValid()</code> 支持另外的参数 <code>$context</code>。当校验一个表单 <code>Zend_Form::isValid()</code> 传递由 <code>$context</code> 处理过的数据的整个数组，<code>Zend_Form_Element::isValid()</code> 接着把它传递给每个校验器。这意味着你可以写知道数据传递给其它表单元素的校验器，例如，标准的注册表单有密码和密码确认元素，得有一个校验它们是否匹配。这样的校验器看起来如下：
            </para>

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

    protected $_messageTemplates = array(
        self::NOT_MATCH => 'Password confirmation does not match'
    );

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

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

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

        <para>
            校验器按顺序处理，除非用 <code>breakChainOnFailure</code> 为 true 创建的校验器并且校验失败，否则每个校验器都要处理。确认按合理的顺序指定你的校验器。
        </para>

        <para>
            校验失败后，你可以从校验器链读取错误代码和消息：
        </para>

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

        <para>
            （注意：错误消息返回的是一个有错误代码/错误消息对的联合数组）
        </para>

        <para>
            除了校验器外，你可以用 <code>setRequired(true)</code> 指定必需的元素。缺省地，这个标志是 false，如果没有值传递给 <code>isValid()</code>，校验器链将被跳过。你也可以用许多办法来修改它的行为：
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    缺省地，当元素是必需的，标志 'allowEmpty'也是 true。这意味着如果传递给 <code>isValid()</code> 的值为空，校验器将被跳过。可以用访问器 <code>setAllowEmpty($flag)</code> 来切换这个标志。当标志为 false，并且传递了一个值，校验器将仍然运行。
                </para>
            </listitem>

            <listitem>
                <para>
                    缺省地，如果元素是必需的，但不包括 'NotEmpty' 校验器，<code>isValid()</code> 就用 <code>breakChainOnFailure</code> 标志设置添加一个到栈顶。这使得要求的标志有语义意义：如果没有传递值，我们立即使提交的数据无效并通知用户，并防止其它校验器继续校验我们已知的无效数据。
                </para>

                <para>
                    如果你不想这样，传递给 <code>setAutoInsertNotEmptyValidator($flag)</code> 一个 false 值使它关闭。这将防止 <code>isValid()</code> 在校验器链里放置一个 'NotEmpty' 校验器。
                </para>
            </listitem>
        </itemizedlist>

        <para>
            关于校验器的更多信息，参见 <link linkend="zend.validate.introduction">Zend_Validate 文档 </link>。
        </para>

        <note>
            <title> 使用 Zend_Form_Elements 作为通用的校验器 </title>

            <para>
                <code>Zend_Form_Element</code> 实现 <code>Zend_Validate_Interface</code>，意味着元素可以在其它非表单相关的校验链里被用做校验器。
            </para>
        </note>

        <para>
            校验相关的方法包括：
        </para>

        <itemizedlist>
            <listitem><para>
                    <code>setRequired($flag)</code> 和 <code>isRequired()</code> 让你设置和读取 'required' 标志的状态。当设置为布尔 <code>true</code>，这个标志要求元素在由 <code>Zend_Form</code> 处理的数据中。
            </para></listitem>

            <listitem><para>
                    <code>setAllowEmpty($flag)</code> 和 <code>getAllowEmpty()</code> 让你修改可选元素的行为（例如，要求的标志为 false 的元素）。当 'allow empty' 标志为 true 时，空值将传递给校验器链。
            </para></listitem>

            <listitem><para>
                    <code>setAutoInsertNotEmptyValidator($flag)</code> 当元素是必需时，让你指定是否 'NotEmpty' 校验器预先准备给校验器链。缺省地，这个标志为 true 。
            </para></listitem>

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

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

            <listitem><para>
                <code>setValidators(array $validators)</code> （重写所有校验器）
            </para></listitem>

            <listitem><para>
                <code>getValidator($name)</code> （按名读取校验器对象）
            </para></listitem>

            <listitem><para>
                <code>getValidators()</code> （读取所有校验器）
            </para></listitem>

            <listitem><para>
                <code>removeValidator($name)</code> （按名删除校验器）
            </para></listitem>

            <listitem><para>
                <code>clearValidators()</code> （删除所有校验器）
            </para></listitem>
        </itemizedlist>
        <sect3 id="zend.form.elements.validators.errors">
            <title> 定制错误消息 </title>

            <para>
                有时，你想定制一条或多条特定的错误消息来替代由附加到元素上的校验器所带的错误消息。
                另外，有时候你想自己标记表单无效，从 1.6.0 版开始，通过下列方法来实现这个功能。
            </para>

            <itemizedlist>
                <listitem><para>
                    <code>addErrorMessage($message)</code>: 添加一条来显示当校验失败时的错误消息。
                    可以多次调用，新消息就追加到堆栈。
                </para></listitem>

                <listitem><para>
                    <code>addErrorMessages(array $messages)</code>: 添加多条错误消息来显示校验错误。
                </para></listitem>

                <listitem><para>
                    <code>setErrorMessages(array $messages)</code>: 添加多条错误消息来显示校验错误，并覆盖先前的错误消息。
                </para></listitem>

                <listitem><para>
                    <code>getErrorMessages()</code>: 读取已定义的定制的错误消息列表。
                </para></listitem>

                <listitem><para>
                    <code>clearErrorMessages()</code>: 删除已定义的定制的错误消息。
                </para></listitem>

                <listitem><para>
                    <code>markAsError()</code>: 标记表单已经有失败的校验。
                </para></listitem>

                <listitem><para>
                    <code>hasErrors()</code>: 确定是否元素有失败校验或标记为无效。
          </para></listitem>

                <listitem><para>
                    <code>addError($message)</code>: 添加一条消息给定制错误消息栈并标记表单无效。
                </para></listitem>

                <listitem><para>
                    <code>addErrors(array $messages)</code>: 添加数条消息给定制错误消息栈并标记表单无效。
                </para></listitem>

                <listitem><para>
                    <code>setErrors(array $messages)</code>: 覆盖定制的错误消息堆栈并标记表单无效。
                </para></listitem>
            </itemizedlist>

            <para>
                所有用这个方式设置的错误可以被翻译。
            </para>
        </sect3>
    </sect2>

    <sect2 id="zend.form.elements.decorators">
        <title> 装饰器 </title>

        <para>
            对许多 web 开发者来说一个特别的痛苦是 XHTML 表单自己的生成。对于每个元素，开发者需要为元素自己生成 markup，label 是一个典型，并且，如果他们对用户很好，需要为显示校验错误消息生成 markup。在页面元素越多，任务就越不琐碎。
        </para>

        <para>
            <code>Zend_Form_Element</code> 试图用 "装饰器" 来解决这个问题。装饰器就是个类，可以访问元素和用于解析内容的方法。更多关于装饰器如何工作，参见 <link linkend="zend.form.decorators">Zend_Form_Decorator</link>。
        </para>

        <para>
            <code>Zend_Form_Element</code> 所使用的缺省的装饰器是：
        </para>

        <itemizedlist>
            <listitem><para>
                <emphasis>ViewHelper</emphasis>: 指定一个视图助手用于解析元素。'helper' 元素属性可用来指定使用哪个视图助手。缺省地，<code>Zend_Form_Element</code> 指定 'formText' 视图助手，但个别的子类指定不同的助手。
            </para></listitem>

            <listitem><para>
                <emphasis>Errors</emphasis>: 使用 <code>Zend_View_Helper_FormErrors</code> 追加错误消息给元素，如果没有错误，就不追加。
            </para></listitem>

            <listitem><para>
                <emphasis>HtmlTag</emphasis>: 在一个 HTML &lt;dd&gt; 标签里封装元素和错误。
            </para></listitem>

            <listitem><para>
                <emphasis>Label</emphasis>: 使用 <code>Zend_View_Helper_FormLabel</code> 预先准备一个标签给元素，并把它封装在一个 &lt;dt&gt; 标签里。如果没有提供标签（Label），就解析定义术语（definition term）标签（tag）。
            </para></listitem>
        </itemizedlist>

        <note>
            <title> 不需要加载缺省装饰器 </title>

            <para>
                缺省地，在对象初始化过程中加载缺省装饰器。你可以通过传递 'disableLoadDefaultDecorators' 选项给构造器来关闭它：
            </para>

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

            <para>
                该选项可以和企图选项混合，它们都是数组选项或在 <code>Zend_Config</code> 对象里。
            </para>
        </note>

        <para>
            因为装饰器注册顺序的原因 －－先注册先执行－－你需要确保按合适的顺序来注册装饰器，或者确保以健全的方式设置替换选项。这个是注册缺省装饰器的例子：
        </para>

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

        <para>
            初始内容由 'ViewHelper' 装饰器生成，它生成表单元素自己。接着，'Errors' 装饰器从元素里抓取错误消息。如果有任何错误，就传递给 'FormErrors' 视图助手来解析。下一个装饰器 'HtmlTag' 在一个 HTML &lt;dd&gt; 标签里封装元素和错误。最后，'label' 装饰器读取元素的标签并传递给 'FormLabel' 视图助手，封装在一个 HTML &lt;dt&gt; 标签里。缺省地，数据预先准备给内容，输出结果基本上是这样的：
        </para>

        <programlisting role="html"><![CDATA[
<dt><label for="foo" class="optional">Foo</label></dt>
<dd>
    <input type="text" name="foo" id="foo" value="123" />
    <ul class="errors">
        <li>"123" is not an alphanumeric value</li>
    </ul>
</dd>
]]></programlisting>

        <para>
            关于装饰器的更多信息，请阅读 <link linkend="zend.form.decorators">Zend_Form_Decorator 一节</link>。
        </para>

        <note>
            <title> 使用同类型的多重装饰器 </title>

            <para>
                在内部，当读取装饰器时，<code>Zend_Form_Element</code> 使用装饰器的类作为查询机制。结果，你不能注册同类型的多重装饰器，后来的装饰器就重写以前存在的装饰器。
            </para>

            <para>
                为解决这个问题，你可以使用 <emphasis>aliases</emphasis>。不是传递装饰器或装饰器名作为第一个参数给 <code>addDecorator()</code>，而是传递带有一个单个元素的数组，并且别名指向装饰器对象或名字：
            </para>

            <programlisting role="php"><![CDATA[<?php
// Alias to 'FooBar':
$element->addDecorator(array('FooBar' => 'HtmlTag'), array('tag' => 'div'));

// And retrieve later:
$decorator = $element->getDecorator('FooBar');
?>]]></programlisting>

            <para>
                在 <code>addDecorators()</code> 和 <code>setDecorators()</code> 方法中，你需要在表示装饰器的数组中传递 'decorator' 选项：
            </para>

            <programlisting role="php"><![CDATA[<?php
// Add two 'HtmlTag' decorators, aliasing one to 'FooBar':
$element->addDecorators(
    array('HtmlTag', array('tag' => 'div')),
    array(
        'decorator' => array('FooBar' => 'HtmlTag'),
        'options' => array('tag' => 'dd')
    ),
);

// And retrieve later:
$htmlTag = $element->getDecorator('HtmlTag');
$fooBar  = $element->getDecorator('FooBar');
?>]]></programlisting>
        </note>

        <para>
            装饰器带有的方法包括：
        </para>

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

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

            <listitem><para>
                <code>setDecorators(array $decorators)</code> （重写所有装饰器）
            </para></listitem>

            <listitem><para>
                <code>getDecorator($name)</code> （按名读取装饰器对象）
            </para></listitem>

            <listitem><para>
                <code>getDecorators()</code> （读取所有装饰器）
            </para></listitem>

            <listitem><para>
                <code>removeDecorator($name)</code> （按名删除装饰器）
            </para></listitem>

            <listitem><para>
                <code>clearDecorators()</code> （删除所有装饰器）
            </para></listitem>
        </itemizedlist>
    </sect2>

    <sect2 id="zend.form.elements.metadata">
        <title> 元数据和属性 </title>

        <para>
            <code>Zend_Form_Element</code> 处理广泛的属性和元素元数据，基本属性包括：
        </para>

        <itemizedlist>
            <listitem><para>
                <emphasis>name</emphasis>: 元素名，使用 <code>setName()</code> 和 <code>getName()</code> 访问器。
            </para></listitem>

            <listitem><para>
                <emphasis>label</emphasis>: 元素标签，使用 <code>setLabel()</code> 和 <code>getLabel()</code> 访问器。
            </para></listitem>

            <listitem><para>
                <emphasis>order</emphasis>: 在表单中出现的元素的索引，使用 <code>setOrder()</code> 和 <code>getOrder()</code> 访问器。
            </para></listitem>

            <listitem><para>
                <emphasis>value</emphasis>: 当前元素的值，使用 <code>setValue()</code> 和 <code>getValue()</code> 访问器。
            </para></listitem>

            <listitem><para>
                <emphasis>description</emphasis>: 元素的描述，常用于提供工具提示或 javascript 上下文提示，描述元素的意图，使用 <code>setDescription()</code> 和 <code>getDescription()</code> 访问器。
            </para></listitem>

            <listitem><para>
                <emphasis>required</emphasis>: 当执行表单校验时，指示元素是否必需的标志，使用 <code>setRequired()</code> 和 <code>isRequired()</code> 访问器，缺省为 false。
            </para></listitem>

            <listitem><para>
                <emphasis>allowEmpty</emphasis>: 指示可选的元素是否应该校验空值的标志，当为 true，并且要求的标志为 false，空值就不传递给校验器链，并假定为 true。使用 <code>setAllowEmpty()</code> 和 <code>getAllowEmpty()</code> 访问器，缺省为 true。
            </para></listitem>

            <listitem><para>
                <emphasis>autoInsertNotEmptyValidator</emphasis>: 当元素是必需时，指示是否插入一个 'NotEmpty' 校验器。缺省地，这个标志为 true，用 <code>setAutoInsertNotEmptyValidator($flag)</code> 来设置该标志并用 <code>autoInsertNotEmptyValidator()</code> 来确定它的值。
            </para></listitem>
        </itemizedlist>

        <para>
            表单元素可能要求另外的元数据。例如，对于 XHTML 表单元素，你可能想指定属性如类或 id，有一组访问器来完成它：
        </para>

        <itemizedlist>
            <listitem><para>
                <emphasis>setAttrib($name, $value)</emphasis>: 添加属性
            </para></listitem>

            <listitem><para>
                <emphasis>setAttribs(array $attribs)</emphasis>: 像 addAttribs() 一样，但重写
            </para></listitem>

            <listitem><para>
                <emphasis>getAttrib($name)</emphasis>: 读取一个单个的属性值
            </para></listitem>

            <listitem><para>
                <emphasis>getAttribs()</emphasis>: 以键/值对读取所有属性
            </para></listitem>
        </itemizedlist>

        <para>
            然而大多数时候，你可以把它们当作对象属性来访问，因为 <code>Zend_Form_Element</code> 利用重载来简便访问它们：
        </para>

        <programlisting role="php"><![CDATA[<?php
// Equivalent to $element->setAttrib('class', 'text'):
$element->class = 'text;
?>]]></programlisting>

        <para>
            缺省地，在解析过程中所有属性传递给由元素使用的视图助手，并当作该元素标签的 HTML 属性来解析。
        </para>
    </sect2>

    <sect2 id="zend.form.elements.standard">
        <title> 标准元素 </title>

        <para>
            <code>Zend_Form</code> 带有许多标准元素，请阅读 <link linkend="zend.form.standardElements"> 标准元素 </link> 一章有全部细节。
        </para>
    </sect2>

    <sect2 id="zend.form.elements.methods">
        <title>Zend_Form_Element 方法 </title>

        <para>
            <code>Zend_Form_Element</code> 有许多许多方法。下面是一个快速概要，按类分组：
        </para>

        <itemizedlist>
            <listitem><para>配置：</para>
                <itemizedlist>
                    <listitem><para><code>setOptions(array $options)</code></para></listitem>
                    <listitem><para><code>setConfig(Zend_Config $config)</code></para></listitem>
                </itemizedlist>
            </listitem>

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

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

            <listitem><para> 插件加载器和路径：</para>
                <itemizedlist>
                    <listitem><para><code>setPluginLoader(Zend_Loader_PluginLoader_Interface $loader, $type)</code></para></listitem>
                    <listitem><para><code>getPluginLoader($type)</code></para></listitem>
                    <listitem><para><code>addPrefixPath($prefix, $path, $type = null)</code></para></listitem>
                    <listitem><para><code>addPrefixPaths(array $spec)</code></para></listitem>
                </itemizedlist>
            </listitem>

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

            <listitem><para> 过滤器：</para>
                <itemizedlist>
                    <listitem><para><code>addFilter($filter, $options = array())</code></para></listitem>
                    <listitem><para><code>addFilters(array $filters)</code></para></listitem>
                    <listitem><para><code>setFilters(array $filters)</code></para></listitem>
                    <listitem><para><code>getFilter($name)</code></para></listitem>
                    <listitem><para><code>getFilters()</code></para></listitem>
                    <listitem><para><code>removeFilter($name)</code></para></listitem>
                    <listitem><para><code>clearFilters()</code></para></listitem>
                </itemizedlist>
            </listitem>

            <listitem><para> 解析：</para>
                <itemizedlist>
                    <listitem><para><code>setView(Zend_View_Interface $view = null)</code></para></listitem>
                    <listitem><para><code>getView()</code></para></listitem>
                    <listitem><para><code>addDecorator($decorator, $options = null)</code></para></listitem>
                    <listitem><para><code>addDecorators(array $decorators)</code></para></listitem>
                    <listitem><para><code>setDecorators(array $decorators)</code></para></listitem>
                    <listitem><para><code>getDecorator($name)</code></para></listitem>
                    <listitem><para><code>getDecorators()</code></para></listitem>
                    <listitem><para><code>removeDecorator($name)</code></para></listitem>
                    <listitem><para><code>clearDecorators()</code></para></listitem>
                    <listitem><para><code>render(Zend_View_Interface $view = null)</code></para></listitem>
                </itemizedlist>
            </listitem>
        </itemizedlist>
    </sect2>

    <sect2 id="zend.form.elements.config">
        <title> 配置 </title>

        <para>
            <code>Zend_Form_Element</code> 的构造器接受选项数组或包含选项的 <code>Zend_Config</code> 的对象，它也可以用 <code>setOptions()</code> 或 <code>setConfig()</code> 来配置。一般来说，命名键如下：
        </para>

        <itemizedlist>
            <listitem><para>
                如果 'set' + 键指向 <code>Zend_Form_Element</code> 方法，那么提供的值就传递给这个方法。
            </para></listitem>

            <listitem><para>
                否则，这个值就用来设置属性。
            </para></listitem>
        </itemizedlist>

        <para>
            该规则的例外包括如下：
        </para>

        <itemizedlist>
            <listitem><para>
                <code>prefixPath</code> 将传递给 <code>addPrefixPaths()</code>
            </para></listitem>

            <listitem>
                <para>
                    下面的设置器不能用这个办法：
                </para>

                <itemizedlist>
                    <listitem><para>
                            <code>setAttrib</code> （通过 <code>setAttribs</code> <emphasis>来工作</emphasis>）
                    </para></listitem>

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

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

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

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

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

        <para>
            这里是一个例子，为每个配置数据类型传递配置的配置文件：
        </para>

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

    <sect2 id="zend.form.elements.custom">
        <title> 定制元素 </title>

        <para>
            通过继承 <code>Zend_Form_Element</code> 类，你可以生成自己的定制元素，这样做的原因是：
        </para>

        <itemizedlist>
            <listitem><para>
                共享通用的校验器和/或过滤器的元素
            </para></listitem>

            <listitem><para>
                有定制装饰器功能的元素
            </para></listitem>
        </itemizedlist>

        <para>
            有两个方法一般用来扩展元素：<code>init()</code> 可为元素添加定制的初始化逻辑；<code>loadDefaultDecorators()</code> 可用于设置一个用于元素的缺省装饰器的列表。
        </para>
        <para>
            用例子来说明，你在一个表单里生成的所有文本元素需要用 <code>StringTrim</code> 来过滤、用通用的规则表达式来校验，并且你想用你生成的定制的装饰器来显示它们，'My_Decorator_TextItem'。另外，你有许多想指定的标准属性，包括 'size'、 'maxLength' 和 'class'。你可以定义这样的元素如下：
        </para>

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

        <para>
            你接着可以通知表单对象关于元素的前缀路径并开始生成元素：
        </para>

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

        <para>
            'foo' 元素现在是 <code>My_Element_Text</code> 类型并展示你描画的行为。
        </para>

        <para>
            当继承 <code>Zend_Form_Element</code> 时你想 override 的另一个特殊方法是 <code>loadDefaultDecorators()</code>。这个方法有条件地为你的元素加载一组缺省装饰器，你可能想在你的继承类里替换你自己的装饰器。
        </para>

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

        <para>
            有许多办法定制元素。别忘了阅读  <code>Zend_Form_Element</code> API 文档来获知所有的可用方法。
        </para>
    </sect2>
</sect1>
<!--
vim:se ts=4 sw=4 tw=80 et:
-->