Zend_Form 创建、校验和解析表单的基础--（手冊）

1.  创建表单对象

创建表单对象很easy：仅仅要实现 Zend_Form：

<?php
$form = newZend_Form;
?
>

对于高级用例。须要创建 Zend_Form 的子类，但对于简单的表单，程序能够用Zend_Form 的对象来创建。

假设想指定表单的动作和方法（总是好主意）。用 setAction() 和 setMethod() 来完毕：

<?php
$form->setAction('/resource/process')
     ->setMethod('post');
?>

上述代码设置表单动作为部分 URL"/resource/process" 和表单方法为 HTTP POST，这将在解析的最后期间表现出来。

你能够通过使用 setAttrib() 或 setAttribs() 方法为 <form> 标签设置另外的 HTML 属性，比如：假设想设置 id, 则设置 "id" 属性：

<?
php
$form->setAttrib('id','login');
?>

2.  加入表单元素

没有元素。表单就什么都不是。

Zend_Form 带有一些缺省的通过 Zend_View 助手解析 XHTML 的元素：

• button
• checkbox (or many checkboxes at once with multiCheckbox)
• hidden
• image
• password
• radio
• reset
• select (both regular and multi-select types)
• submit
• text
• textarea

有两个方法加入表单元素：实例化详细的元素并传递这些对象，或者传递元素类型并使Zend_Form 实例化一个正确类型的对象。

一些样例：

<?php
// Instantiating anelement and passing to the form object:
$form->addElement(newZend_Form_Element_Text('username'));
 
// Passing a formelement type to the form object:
$form->addElement('text','username');
?
>

缺省地，这些没有校验器和过滤器，你须要用最主要的校验器和可能的过滤器来配置元素。有三个方法：

(a) 在传递元素给表单之前，

(b) 通过用 Zend_Form 创建元素时传递的配置选项。

(c) 从表单把元素拉出来并在以后配置。

让我们首先看看为一个详细的元素实例创建校验器。能够传递 Zend_Validate_* 对象。或校验器的名称：

<?
php
$username = newZend_Form_Element_Text('username');
 
// Passing aZend_Validate_* object:
$username->addValidator(newZend_Validate_Alnum());
 
// Passing avalidator name:
$username->addValidator('alnum');
?>

当使用第二个方法。假设校验器可接受构造器參数，能够把它们放到数组里作为第三个參数：

<?php
// Pass a pattern
$username->addValidator('regex',false, array('/^[a-z]/i'));
?>

（第二个參数用来指示是否这个校验失败时停止后面的校验。缺省为 false。）

你也可能希望指定一个必需的元素，能够通过使用訪问器或当创建该元素时传递一个选项来完毕，在前面的样例中：

<?php
// 使这个元素成为必需：
$username->setRequired(true);
?
>

当一个元素是必需的。一个 ‘NotEmpty‘ 校验器被加入到校验器链的顶部。确保该元素有一个值。

过滤器会像校验器一样注冊，为了演示，让我们加入一个来把终于值变小写的过滤器：

<?php
$username->addFilter('StringtoLower');
?
>

这样，终于元素设置看起来像这样：

<?php
$username->addValidator('alnum')
         ->addValidator('regex', false,array('/^[a-z]/'))
         ->setRequired(true)
         ->addFilter('StringToLower');
 
// or, morecompactly:
$username->addValidators(array('alnum',
        array('regex', false, '/^[a-z]/i')
    ))
    ->setRequired(true)
    ->addFilters(array('StringToLower'));
?>

就算这样简单，在表单中为每一个元素都做这种工作也是单调乏味的。让我们试一试上述的方法(b)，当使用工厂模式 Zend_Form::addElement() 创建一个新元素，我们能够可选地传递配置选项，包含校验器和过滤器。

这样，能够简单地完毕上述任务：

<?php
$form->addElement('text','username', array(
    'validators' => array(
        'alnum',
        array('regex', false, '/^[a-z]/i')
    ),
    'required' => true,
    'filters' => array('StringToLower'),
));
?
>

3.  解析（Render）表单

解析表单非常easy。大部分元素使用 Zend_View 助手来解析，这样须要视图对象来解析。除了这以外，还有两个方法：使用表单的 render() 方法或简单地 echo 它。

<?
php
// Explicitly callingrender(), and passing an optional view object:
echo$form->render($view);
 
// Assuming a viewobject has been previously set via setView():
echo $form;
?>

缺省地。Zend_Form 和 Zend_Form_Element 将企图使用在 ViewRenderer 中初始化过的视图对象。你不须要在Zend Framework MVC 中手工设置视图。

在视图脚本中解析表单是如此的简单：

<?= $this->form?>

在内部，Zend_Form 使用"decorators" （装饰器） 来运行解析。这些装饰器能够替换内容、追加内容或预先准备内容，并拥有传递给它们的元素的 full introspection 。结果。你能够组合多个装饰器来完毕定制效果。缺省地。Zend_Form_Element 实际上组合了四个装饰器来完毕输出。參见下例的设置：

<?
php
$element->addDecorators(array(
    'ViewHelper',
    'Errors',
    array('HtmlTag', array('tag' => 'dd')),
    array('Label', array('tag' => 'dt')),
));
?
>

（ <HELPERNAME> 是视图助手的名称，并依据元素不同而不同）

上述的样例创建的输出例如以下：

<dt><labelfor="username" class="required">Username</dt>
<dd>
    <input type="text"name="username" value="123-abc" />
    <ul class="errors">
        <li>'123-abc' has not onlyalphabetic and digit characters</li>
        <li>'123-abc' does not matchagainst pattern '/^[a-z]/i'</li>
    </ul>
</dd>

（尽管没有使用同样的格式。）

假设你想输出不同的东西，能够改动由元素使用的装饰器，參见装饰器一节有很多其它内容。

表单循环检查全部元素，并把它们放到 HTML <form>。当设置表单时。你提供的动作和方法被提供给 <form> 标签，还有不论什么通过 setAttribs() 和它的家族设置的属性。

元素或者按注冊的顺序循环。或者假设元素包括顺序属性，就按这个顺序循环。能够使用下列方法设置元素顺序：

<?
php
$element->setOrder(10);
?>

或者。当创建元素，作为一个选项传递给它：

<?php
$form->addElement('text','username', array('order' => 10));
?>

4.  检查表单是否有效

表单提交之后，须要检查它能否通过校验。每一个元素依据提供的数据来检查。假设匹配元素名的键没有出现。并该条目被标记为必需，就用 null 值来校验。

数据从哪里来？用 $_POST 或 $_GET 或者其他手头上的数据源 （比如 web 服务请求）：

<?
php
if($form->isValid($_POST)) {
    // success!
} else {
    // failure!
}
?>

用 AJAX 请求。 有时候能够侥幸成功校验单个元素或一组元素。

isValidPartial() 将校验局部的表单，不像 isValid()，假设特定的键没有出现，那个特定部分的元素就不校验：

<?php
if($form->isValidPartial($_POST)) {
    // elements present all passed validations
} else {
    // one or more elements tested failedvalidations
}
?>

一个可选的方法。processAjax()，也能够用来校验局部表单，不像 isValidPartial()。假设失败。它返回一个包括错误消息的 JSON 格式的字符串。

如果校验都通过，如今就能够取得过滤后的值：

<?php
$values =$form->getValues();
?>

假设不论什么时候须要没有过滤的值，使用：

<?php
$unfiltered =$form->getUnfilteredValues();
?>

5.  获得错误状态

假设表单校验失败，在大多数情况下，能够再次解析表单。假设使用了缺省的装饰器。错误信息就会显示出来：

<?php
if(!$form->isValid($_POST)) {
    echo $form;
 
    // or assign to the view object and rendera view...
    $this->view->form = $form;
    return $this->render('form');
}
?
>

假设想插入错误消息，有两个方法： getErrors() 返回一个元素名/代码对的联合数组（这里的代码是指一个错误代码数组）。

getMessages() 返回一个元素名/消息对的联合数组（这里的消息是指错误代码/错误消息对的联合数组）。

假设给定的元素没有不论什么错误。数组就不包括它。

6.  放到一起

来创建一个简单的登录表单。我们须要这些元素：

• username
• password
• submit

让我们如果有效的username应当仅仅是字母数字字符，以字母开头。最少 6 个字符。最长 20 个字符，最后格式化成小写。password最少 6 个字符。当完毕这些，我们就提交，保持未校验。

我们使用 Zend_Form 的配置选项的能力来建立表单：

<?
php

$form = newZend_Form();
$form->setAction('/user/login')
     ->setMethod('post');
 
// Create andconfigure username element:
$username =$form->createElement('text', 'username');
$username->addValidator('alnum')
         ->addValidator('regex', false,array('/^[a-z]+/'))
         ->addValidator('stringLength',false, array(6, 20))
         ->setRequired(true)
         ->addFilter('StringToLower');
 
// Create andconfigure password element:
$password =$form->createElement('password', 'password');
$password->addValidator('StringLength',false, array(6))
         ->setRequired(true);
 
// Add elements toform:
$form->addElement($username)
     ->addElement($password)
     // use addElement() as a factory to create'Login' button:
     ->addElement('submit', 'login',array('label' => 'Login'));
?
>

接着，我们将创建控制器来处理这些：

<?
php
class UserControllerextends Zend_Controller_Action
{
    public function getForm()
    {
        // create form as above
        return $form;
    }
 
    public function indexAction()
    {
        // render user/form.phtml
        $this->view->form =$this->getForm();
        $this->render('form');
    }
 
    public function loginAction()
    {
        if(!$this->getRequest()->isPost()) {
            return $this->_forward('index');
        }
        $form = $this->getForm();
        if (!$form->isValid($_POST)) {
            // Failed validation; redisplayform
            $this->view->form = $form;
            return $this->render('form');
        }
 
        $values = $form->getValues();
        // now try and authenticate....
    }
}
?>

和一个视图脚本来显示表单：

<h2>Pleaselogin:</h2>
<?= $this->form?
>

注意在控制器代码中，还有非常多须要做：比如在提交后，须要用 Zend_Auth 来认证。

7.  使用 Zend_Config 对象

全部 Zend_Form 类能够用 Zend_Config 来配置，能够传递 Zend_Config 对象给构造器或者通过 setConfig() 来传递。来看一下怎样用 INI 文件来创建上述表单，首先，遵循建议。把配置放到反映发行位置的节里面，并集中到 ‘development‘ 节，接着，为给定控制器（‘user‘）设置一个节，为表单（‘login‘）设置一个键：

[development]
; general formmetainformation
user.login.action ="/user/login"
user.login.method ="post"
 
; username element
user.login.elements.username.type= "text"
user.login.elements.username.options.validators.alnum.validator= "alnum"
user.login.elements.username.options.validators.regex.validator= "regex"
user.login.elements.username.options.validators.regex.options.pattern= "/^[a-z]/i"
user.login.elements.username.options.validators.strlen.validator= "StringLength"
user.login.elements.username.options.validators.strlen.options.min= "6"
user.login.elements.username.options.validators.strlen.options.max= "20"
user.login.elements.username.options.required= true
user.login.elements.username.options.filters.lower.filter= "StringToLower"
 
; password element
user.login.elements.password.type= "password"
user.login.elements.password.options.validators.strlen.validator= "StringLength"
user.login.elements.password.options.validators.strlen.options.min= "6"
user.login.elements.password.options.required= true
 
; submit element
user.login.elements.submit.type= "submit"

接着。你能够把它传递给表单构造器：

<?php
$config = newZend_Config_Ini($configFile, 'development');
$form   = new Zend_Form($config->user->login);
?>

整个表单就定义好了。