Zend Framework中文手册

Zend_Form 利用 Zend_Loader_PluginLoader 使开发者指定替代元素和装饰器的位置。每个表单有和它一起伴随的插件加载器，总访问器用来读取和修改每个表单。

下列加载器类型和不同的插件加载器方法 'element' 和 'decorator' 一起来使用。类型名大小写敏感。

用来和插件加载器结合使用的方法如下：

另外，也可以用下列方法为所有通过Zend_Form实例生成元素和显示组指定前缀路径：

定制元素和装饰器是在表单和封装定制函数之间共享功能的简便方法。在元素文档（elements documentation）中参见 Custom Label example ，看定制元素如何用来替换标准类。

Zend_Form 提供了若干访问器用来从表单中添加和删除元素。这些可以获得元素对象实例或以工厂模式来为实例化元素对象自己服务。

添加元素的最基本的方法是 addElement()。该方法可以或者带有 Zend_Form_Element （或者继承 Zend_Form_Element 的类 ）类型对象的参数，或者用于建立新元素的参数 － 包括元素类型、名称和任何配置选项。

如一些例子：

<?php
// Using an element instance:
$element = new Zend_Form_Element_Text('foo');
$form->addElement($element);

// Using a factory
// 
// Creates an element of type Zend_Form_Element_Text with the
// name of 'foo':
$form->addElement('text', 'foo');

// Pass label option to the element:
$form->addElement('text', 'foo', array('label' => 'Foo:'));
?>

	addElement() 实现 Fluent Interface
	addElement() 实现一个 fluent interface，就是说，它返回 Zend_Form 对象，而不是元素。这样做来允许你把多个 addElement()方法或者其它实现 fluent interface 的表单方法链接起来（所有 Zend_Form 中的设置器（ setters） 都实现这个模式）。 如果你想返回元素，使用 createElement()，下面是要点。然而请注意，createElement() 不把元素加到表单上。 在内部，addElement() 实际上用 createElement() 来生成元素之后把它加到表单上。

一旦元素被添加到表单，可以用名字来读取。通过使用 getElement() 方法或者通过重载（overloading）使元素作为对象属性来访问：

<?php
// getElement():
$foo = $form->getElement('foo');

// As object property:
$foo = $form->foo;
?>

偶尔地，你只想生成一个元素并不想把它加到表单上（例如，你想利用众多的用表单注册的插件路径，但稍后把这些对象加到子表单上）。createElement() 方法可以完成这些：

<?php
// $username becomes a Zend_Form_Element_Text object:
$username = $form->createElement('text', 'username');
?>

<?php
// Get all values:
$values = $form->getValues();

// Get only 'foo' element's value:
$value = $form->getValue('foo');
?>

<?php
$form->setDefaults($data);
$form->populate($data);
?>

$form->reset();

17.4.2.2.  全局操作

偶尔，你想用对所有元素进行特定的操作，一般的情形包括需要为所有元素设置插件前缀路径、装饰器和过滤器，如下例：

例 17.2.  为所有元素设置前缀路径

可以通过类型来为所有的元素设置前缀路径，或者使用全局前缀，如这些例子：

<?php
// Set global prefix path:
// Creates paths for prefixes My_Foo_Filter, My_Foo_Validate,
// and My_Foo_Decorator
$form->addElementPrefixPath('My_Foo', 'My/Foo/');

// Just filter paths:
$form->addElementPrefixPath('My_Foo_Filter', 'My/Foo/Filter', 'filter');

// Just validator paths:
$form->addElementPrefixPath('My_Foo_Validate', 'My/Foo/Validate', 'validate');

// Just decorator paths:
$form->addElementPrefixPath('My_Foo_Decorator', 'My/Foo/Decorator', 'decorator');
?>

例 17.3.  为所有元素设置装饰器（Decorators）

你可以为所有元素设置装饰器。setElementDecorators() 接受一个装饰器数组， 就象 setDecorators() 一样，并对每个元素重写（overwrite）先前设置的装饰器。在本例中，我们为 ViewHelper 和一个 Label 设置装饰器：

<?php
$form->setElementDecorators(array(
    'ViewHelper',
    'Label'
));
?>

例 17.4.  为某些元素设置装饰器

你也可以对一个元素的子集设置装饰器，包含和排除都可以。 setElementDecorators() 的第二个参数可以是元素名数组； 缺省地，指定这样一个数组将只对这些元素设置指定的装饰器。 你也可以传递第三个参数，用来指示是包含还是排除这个元素列表的标志。 如果是 false，它将装饰 除了 这些在列表中的元素 之外 的所有元素。使用方法的标准用法，在每个元素中，任何传递的装饰器将覆盖任何先前设置的装饰器。

在下面的片段中，我们只对 'foo' 和 'bar' 元素使用视图助手和标签装饰器：

$form->setElementDecorators(
    array(
        'ViewHelper',
        'Label'
    ),
    array(
        'foo',
        'bar'
    )
);

另一方面，在这个片段中，我们对除了'foo' 元素 'bar'之外的所以元素使用视图助手和标签装饰器：

$form->setElementDecorators(
    array(
        'ViewHelper',
        'Label'
    ),
    array(
        'foo',
        'bar'
    ),
    false
);

	有些装饰器不适合某些元素
	虽然 setElementDecorators() 可能是个好方案，但有时候不会得到所期望的结果。例如，各种各样的按钮元素（Submit, Button, Reset）。当前使用标签（label）作为按钮（button）的值（value），并只使用 ViewHelper 和 DtDdWrapper 装饰器 －－ 防止解析另外的标签、错误、和提示，上述例子可能重复（duplicate）一些内容（标签）。 你可以使用 包含/排除 数组来克服在前面例子中所述的问题。 所以，要灵活使用这个方法，你需要排除或手工修改一些元素的装饰器来防止不希望的输出。

例 17.5.  为所有元素设置过滤器

大多数情况下，你想对所有元素应用同一个过滤器，一个通常的用法是 修整（trim()） 所有的值：

<?php
$form->setElementFilters(array('StringTrim'));
?>

显示组是生成要显示的虚拟元素组的一种方法。所有元素在表单中保持用名字可访问，但是当迭代或解析（rendering）所有表单的时候，任何在显示组中的元素将被一起解析（rendered）。最普通的用例是把（数据库表中的）字段组成一组元素。

显示组的基本类是 Zend_Form_DisplayGroup。虽然它可以直接实例化，但是一般最好是用 Zend_Form 的 addDisplayGroup() 方法来做。该方法带有一个元素数组作为第一个参数，和一个显示组的名称作为第二个参数。也可以传递一个选项数组或 Zend_Config 对象作为第三个参数。

假定元素 'username' 和 'password'已经在表单中，下面的代码将把它们组成一个 'login'显示组：

<?php
$form->addDisplayGroup(array('username', 'password'), 'login');
?>

你可以用 getDisplayGroup() 方法来访问显示组，或用显示组的名称来重载（overloading）：

<?php
// Using getDisplayGroup():
$login = $form->getDisplayGroup('login');

// Using overloading:
$login = $form->login;
?>

	不需要加载缺省的装饰器
	缺省地，缺省的装饰器在对象初始化过程中加载。你可以在生成显示组的时候通过传递 'disableLoadDefaultDecorators' 选项来关闭（disable）它。 <?php $form->addDisplayGroup( array('foo', 'bar'), 'foobar', array('disableLoadDefaultDecorators' => true) ); 该选项可以和其它选项混合，它们都是数组或者 Zend_Config 对象。

<?php
$form->addDisplayGroupPrefixPath('My_Foo_Decorator', 'My/Foo/Decorator');
?>

<?php
$form->setDisplayGroupDecorators(array(
    'FormElements',
    'Fieldset'
));
?>

<?php
// Use the 'My_DisplayGroup' class
$form->addDisplayGroup(
    array('username', 'password'), 
    'user',
    array('displayGroupClass' => 'My_DisplayGroup')
);
?>

<?php
// Use the 'My_DisplayGroup' class for all display groups:
$form->setDefaultDisplayGroupClass('My_DisplayGroup');
?>

子表单服务于如干目的：

子表单可以是 Zend_Form 对象，或者更一般地是 Zend_Form_SubForm 对象。后者包含适合包含在大表单（例如，它不解析另外的 HTML 表单标签，但解析组元素）里的装饰器。为了加上子表单，简单地把它添加到一个表单并给出名字：

<?php
$form->addSubForm($subForm, 'subform');
?>

可以用 getSubForm($name) 或用子表单名重载（overloading）它来读取子表单：

<?php
// Using getSubForm():
$subForm = $form->getSubForm('subform');

// Using overloading:
$subForm = $form->subform;
?>

虽然子表单包含的元素不包含在表单迭代中，但子表单包含在其中。

<?php
$form->setSubFormDecorators(array(
    'FormElements',
    'Fieldset'
));
?>

虽然表单的有效性基本源于它所包含的元素，但它也可以包含其它元数据，如名称（在 HTML 标记语言中经常用作唯一的 ID）、表单动作和方法、许多元素、组、它所包含的子表单和属性元数据（通常用做为表单标签自己设置 HTML 属性）。

可以使用名字访问器来设置和读取表单的名字：

<?php
// Set the name:
$form->setName('registration');

// Retrieve the name:
$name = $form->getName();
?>

为了设置动作（到表单提交的 url ）和方法（提交的方法如 'POST' 或 'GET'），使用动作和方法访问器：

<?php
// Set the action and method:
$form->setAction('/user/login')
     ->setMethod('post');
?>

你也可以指定特别使用 enctype 访问器的表单编码类型。 Zend_Form 定义了两个常量， Zend_Form::ENCTYPE_URLENCODED 和 Zend_Form::ENCTYPE_MULTIPART，分别对应值为 'application/x-www-form-urlencoded' 和 'multipart/form-data'； 然而，你可以把它设置为任意的编码类型。

<?php
// Set the action, method, and enctype:
$form->setAction('/user/login')
     ->setMethod('post')
     ->setEnctype(Zend_Form::ENCTYPE_MULTIPART);
?>

	注意
	方法、动作和 enctype 只用来内部解析，不用于任何校验。

Zend_Form 实现 Countable 接口，允许把它当作参数传递给计数器（count）：

<?php
$numItems = count($form);
?>

设置任意元数据可通过属性访问器来完成。因为在 Zend_Form 中重载用于访问元素、显示组和子表单，这是唯一的访问元数据的方法。

<?php
// Setting attributes:
$form->setAttrib('class', 'zend-form')
     ->addAttribs(array(
         'id'       => 'registration',
         'onSubmit' => 'validate(this)',
     ));

// Retrieving attributes:
$class = $form->getAttrib('class');
$attribs = $form->getAttribs();

// Remove an attribute:
$form->removeAttrib('onSubmit');

// Clear all attributes:
$form->clearAttribs();
?>

为表单生成 markup 通常是一件耗时的任务，特别是如果打算重复使用同一个 markup 来显示校验错误、提交的值等。Zend_Form 的解决办法是 装饰器（decorators）。

Zend_Form 对象的装饰器可用来解析表单。FormElements 装饰器将迭代所有在表单中的条目 －－元素、显示组、子表单 －－并解析它们和返回结果。另外，装饰器可以用来封装内容、或追加、或预先准备它。

Zend_Form 的缺省装饰器是 FormElements，HtmlTag（ 封装在定义列表 ）和 Form，生成它们的等同的代码如下：

<?php
$form->setDecorators(array(
    'FormElements',
    array('HtmlTag', array('tag' => 'dl')),
    'Form'
));
?>

生成输出如下：

<form action="/form/action" method="post">
<dl>
...
</dl>
</form>

在表单对象中的任何属性设置将用做 <form> 标签的 HTML 属性。

	不需要加载缺省的装饰器
	缺省地，缺省的装饰器在对象初始化过程中加载。可通过传递 'disableLoadDefaultDecorators' 选项给构造器来关闭（disable）它： <?php $form = new Zend_Form(array('disableLoadDefaultDecorators' => true)); 该选项可以和其它任何选项混合，它们都是数组或在一个 Zend_Config 对象里。

使用同类型的多个装饰器

在内部，当读取装饰器时，Zend_Form 使用装饰器的类做为查找机制。结果，可以注册同类型的多个装饰器，后来的装饰器将重些以前的（装饰器）。 To get around this,可以使用别名。不用传递装饰器或装饰器名称为第一个参数给 addDecorator()，而是传递一个带有单个元素的、带有指向装饰器对象或名字的别名的数组： <?php // Alias to 'FooBar': $form->addDecorator(array('FooBar' => 'HtmlTag'), array('tag' => 'div')); // And retrieve later: $form = $element->getDecorator('FooBar'); ?> 在 addDecorators() 和 setDecorators() 方法中，需要传递在表示装饰器的数组中的 'decorator' 选项： <?php // Add two 'HtmlTag' decorators, aliasing one to 'FooBar': $form->addDecorators( array('HtmlTag', array('tag' => 'div')), array( 'decorator' => array('FooBar' => 'HtmlTag'), 'options' => array('tag' => 'dd') ), ); // And retrieve later: $htmlTag = $form->getDecorator('HtmlTag'); $fooBar = $form->getDecorator('FooBar'); ?>

为生成表单，你可以生成自己的装饰器。一个通常的用例是如果你知道额外的你想用的 HTML，你的装饰器可以潜在地使用从独立的元素或显示组来的装饰器生成额外的 HTML 并返回它。

下列方法可以用来和装饰器交互使用：

表单的一个基本用例是校验提交的数据。Zend_Form 让你一次性校验整个表单或部分表单，还有对 XmlHttpRequests (AJAX)的自动校验响应。如果提交的数据无效，它有一些方法用来为元素和子表单校验失败而读取各种各样的错误代码和消息。

为了校验整个表单，使用 isValid() 方法：

<?php
if (!$form->isValid($_POST)) {
    // failed validation
}
?>

isValid() 校验每个必需的元素和任何包括在提交的数据中的非必需的元素。

有时候你可能只需要校验数据的一个子集，可以使用 isValidPartial($data)：

<?php
if (!$form->isValidPartial($data)) {
    // failed validation
}
?>

isValidPartial() 只尝试校验那些数据中匹配的元素，如果某个元素不在数据中，那就跳过。

当为 AJAX 请求校验元素或元素组，你一般要校验表单的一个子集，并想要响应返回到 json。用 processAjax() 正好：

<?php
$json = $form->processAjax($data);
?>

你可以发送 JSON 响应到客户端。如果表单有效，这将是个布尔 true 响应，如果表单无效，则是个包含 key/message 对的 javascript 对象，这里，每个 'message' 是校验错误消息的数组。

对于校验失败的表单，你可以分别使用 getErrors() 和 getMessages() 获取错误代码和错误消息：

<?php
$codes = $form->getErrors();
$messages = $form->getMessage();
?>

	注意
	因为由 getMessages() 返回的消息是 error code/message 对的数组，一般不需要 getErrors()。

你可以通过传递元素名为单个元素来获取代码和错误消息；

<?php
$codes = $form->getErrors('username');
$messages = $form->getMessages('username');
?>

	注意
	注意：当校验元素时，Zend_Form 发送第二个参数给每个元素的 isValid() 方法：被校验的数据的数组。当确定数据和合法性时，单个的校验器可以用这个来让它们来利用其它提交的值。一个典型的例子是注册表单，密码和密码确认都是必需的；密码元素可以使用密码确认做为它的校验的一部分。

下面是 Zend_Form 的方法大全，按类分组：

Zend_Form 可以通过 setOptions() 和 setConfig() （或者通过传递选项或 Zend_Config 对象 ） 进行全面配置。使用这些方法，你可以指定表单元素、显示组、装饰器和元数据。

作为通用的规则，如果 'set' + 选项键涉及 Zend_Form 方法，那么提供的值将传递给那个方法。 如果访问器不存在，键被假定引用一个属性并将传递给 setAttrib() 。

规则的异常包括下列这些：

作为一个例子，这里是一个为每个可配置数据传递配置的配置文件：

[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"
?>

上述可以很容易被抽象成 XML 或 PHP 基于数组的配置文件。

一个使用基于配置的表单的替代方法是继承 Zend_Form 类，有若干优点：

最典型的用例是使用 init() 方法来设置指定的表单元素和配置：

<?php
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'
        ));
    }
}
?>

这个表单可以简单地实例化：

<?php
$form = new My_Form_Login();
?>

所有的功能已经设置并准备好了，不需要配置文件。（注意这个例子非常简化，因为它没有为元素包含校验器和过滤器。）

另一个普通的扩展原因是定义一组缺省的装饰器，可以通过覆盖（overriding）loadDefaultDecorators() 方法来完成：

<?php
class My_Form_Login extends Zend_Form
{
    public function loadDefaultDecorators()
    {
        $this->setDecorators(array(
            'FormElements',
            'Fieldset',
            'Form'
        ));
    }
}