表单Forms

表单Forms

Phalcon中提供了 Phalcon\Forms组件以方便开发者创建和维护应用中的表单。下面的例子中展示了基本的使用方法：

Phalcon\Forms is a component that aid the developer in the creation and maintenance of forms in web applications.

The following example shows its basic usage:

<?php
use Phalcon\Forms\Form;
use Phalcon\Forms\Element\Text;
use Phalcon\Forms\Element\Select;
$form = new Form();
$form->add(new Text("name"));
$form->add(new Text("telephone"));
$form->add(new Select("telephoneType", array(
    'H' => 'Home',
    'C' => 'Cell'
)));

可在表单定义时穿插使用表单元素的字义：

Forms can be rendered based on the form definition:

<h1>Contacts</h1>
<form method="post">
    <p>
        <label>Name</label>
        <?php echo $form->render("name") ?>
    </p>
    <p>
        <label>Telephone</label>
        <?php echo $form->render("telephone") ?>
    </p>
    <p>
        <label>Type</label>
        <?php echo $form->render("telephoneType") ?>
    </p>
    <p>
        <input type="submit" value="Save" />
    </p>
</form>

开发者可根据需要渲染html组件。当使用render()函数时， phalcon内部会使用 Phalcon\Tag 生成相应的html项，第二个参数中可以对一些属性进行设置。

Each element in the form can be rendered as required by the developer. Internally, Phalcon\Tag is used to produce the right HTML for each element, you can pass additional html attributes as second parameter for render:

<p>
    <label>Name</label>
    <?php echo $form->render("name", array('maxlength' => 30, 'placeholder' => 'Type your name')) ?>
</p>

html的属性也可以在创建时指定：

HTML Attributes also can be set in the element’s definition:

<?php
$form->add(new Text("name", array(
    'maxlength'   => 30,
    'placeholder' => 'Type your name'
)));

初始化表单Initializing forms

从上面的例子我们可以看到表单项也可以在form对象初始化后进行添加。当然开发者也可以对原有的Form类进行扩展：

As seen before, forms can be initialized outside the form class by adding elements to it. You can re-use code or organize your form classes implementing the form in a separated file:

<?php
use Phalcon\Forms\Form;
use Phalcon\Forms\Element\Text;
use Phalcon\Forms\Element\Select;
class ContactForm extends Form
{
    public function initialize()
    {
        $this->add(new Text("name"));
        $this->add(new Text("telephone"));
        $this->add(new Select("telephoneType", TelephoneTypes::find(), array(
            'using' => array('id', 'name')
        )));
    }
}

由于 :doc:`Phalcon\Forms\Form <../api/Phalcon_Forms_Form>`实现了 :doc:`Phalcon\DI\Injectable <../api/Phalcon_DI_Injectable>`接口，所以开发者可以根据自己的需要访问应用中的服务。

Phalcon\Forms\Form extends Phalcon\DI\Injectable so you have access to the application services if needed:

<?php
use Phalcon\Forms\Form;
use Phalcon\Forms\Element\Text;
use Phalcon\Forms\Element\Hidden;
class ContactForm extends Form
{
    /**
     * This method returns the default value for field 'csrf'
     */
    public function getCsrf()
    {
        return $this->security->getToken();
    }
    public function initialize()
    {
        //Set the same form as entity
        $this->setEntity($this);
        //Add a text element to capture the 'email'
        $this->add(new Text("email"));
        //Add a text element to put a hidden csrf
        $this->add(new Hidden("csrf"));
    }
}

相关的实体在初始化时添加到表单，自定义的选项通过构造器传送：

The associated entity added to the form in the initialization and custom user options are passed to the form constructor:

<?php
use Phalcon\Forms\Form;
use Phalcon\Forms\Element\Text;
use Phalcon\Forms\Element\Hidden;
class UsersForm extends Form
{
    /**
     * Forms initializer
     *
     * @param Users $user
     * @param array $options
     */
    public function initialize($user, $options)
    {
        if ($options['edit']) {
            $this->add(new Hidden('id'));
        } else {
            $this->add(new Text('id'));
        }
        $this->add(new Text('name'));
    }
}

在表单实例中必须要这样使用：

In the form’s instantiation you must use:

<?php
$form = new UsersForm(new Users(), array('edit' => true));

验证Validation

Phalcon表单组件可以和 validation 集成，以提供验证。开发者要单独为每个html元素提供内置或自定义的验证器。

Phalcon forms are integrated with the validation component to offer instant validation. Built-in or custom validators could be set to each element:

<?php
use Phalcon\Forms\Element\Text;
use Phalcon\Validation\Validator\PresenceOf;
use Phalcon\Validation\Validator\StringLength;
$name = new Text("name");
$name->addValidator(new PresenceOf(array(
    'message' => 'The name is required'
)));
$name->addValidator(new StringLength(array(
    'min' => 10,
    'messageMinimum' => 'The name is too short'
)));
$form->add($name);

然后，开发者可以根据用户的输入进行验证：

Then you can validate the form according to the input entered by the user:

<?php
if (!$form->isValid($_POST)) {
    foreach ($form->getMessages() as $message) {
        echo $message, '<br>';
    }
}

验证器执行的顺序和注册的顺序一致。

Validators are executed in the same order as they were registered.

默认情况下，所有的元素产生的消息是放在一起的，所以开发者可以使用简单的foreach来遍历消息，开发者可以按照自己的意愿组织输出：

By default messages generated by all the elements in the form are joined so they can be traversed using a single foreach, you can change this behavior to get the messages separated by the field:

<?php
foreach ($form->getMessages(false) as $attribute => $messages) {
    echo 'Messages generated by ', $attribute, ':', "\n";
    foreach ($messages as $message) {
        echo $message, '<br>';
    }
}

或获取指定元素的消息：

Or get specific messages for an element:

<?php
foreach ($form->getMessagesFor('name') as $message) {
    echo $message, '<br>';
}

过滤Filtering

表单元素可以在进行验证前先进行过滤，开发者可以为每个元素设置过滤器：

A form is also able to filter data before it is validated. You can set filters in each element:

设置用户选项Setting User Options

表单与实体Forms + Entities

我们可以把 model/collection/plain 设置到表单对象中，这样 phalcon 会自动的设置表单元素的值：

An entity such as a model/collection/plain instance or just a plain PHP class can be linked to the form in order to set default values in the form’s elements or assign the values from the form to the entity easily:

<?php
$robot = Robots::findFirst();
$form = new Form($robot);
$form->add(new Text("name"));
$form->add(new Text("year"));

在表单渲染时如果表单项未设置默认值， phalcon会使用对象实体值作为默认值：

Once the form is rendered if there is no default values assigned to the elements it will use the ones provided by the entity:

<?php echo $form->render('name') ?>

开发者可以使用下面的方式验证表单及利用用户的输入来设置值：

You can validate the form and assign the values from the user input in the following way:

<?php
$form->bind($_POST, $robot);
//Check if the form is valid
if ($form->isValid()) {
    //Save the entity
    $robot->save();
}

也可以使用一个简单的类做为对象实体进行参数传递：

Setting up a plain class as entity also is possible:

<?php
class Preferences
{
    public $timezone = 'Europe/Amsterdam';
    public $receiveEmails = 'No';
}

使用此类做为对象实体，这样可以使用此类中的值作为表单的默认值：

Using this class as entity, allows the form to take the default values from it:

<?php
$form = new Form(new Preferences());
$form->add(new Select("timezone", array(
    'America/New_York'  => 'New York',
    'Europe/Amsterdam'  => 'Amsterdam',
    'America/Sao_Paulo' => 'Sao Paulo',
    'Asia/Tokyo'        => 'Tokyo',
)));
$form->add(new Select("receiveEmails", array(
    'Yes' => 'Yes, please!',
    'No'  => 'No, thanks'
)));

实体中也可以使用getters, 这样可以给开发者更多的自由，当然也会洽使开发稍麻烦一些，不过这是值得的：

Entities can implement getters, which have a higher precedence than public properties. These methods give you more freedom to produce values:

<?php
class Preferences
{
    public $timezone;
    public $receiveEmails;
    public function getTimezone()
    {
        return 'Europe/Amsterdam';
    }
    public function getReceiveEmails()
    {
        return 'No';
    }
}

表单控件Form Elements

Phalcon提供了一些内置的html元素类，所有这些元素类仅位于 Phalcon\Forms\Element命名空间下：

Phalcon provides a set of built-in elements to use in your forms, all these elements are located in the Phalcon\Forms\Element namespace:

Name	Description	Example
Text	Generate INPUT[type=text] elements	Example
Password	Generate INPUT[type=password] elements	Example
Select	Generate SELECT tag (combo lists) elements based on choices	Example
Check	Generate INPUT[type=check] elements	Example
Textarea	Generate TEXTAREA elements	Example
Hidden	Generate INPUT[type=hidden] elements	Example
File	Generate INPUT[type=file] elements	Example
Date	Generate INPUT[type=date] elements	Example
Numeric	Generate INPUT[type=number] elements	Example
Submit	Generate INPUT[type=submit] elements	Example

事件回调Event Callbacks

当扩展表单时，我们可以在表单类中实现验证前操作及验证后操作：

Whenever forms are implemented as classes, the callbacks: beforeValidation and afterValidation can be implemented in the form’s class to perform pre-validations and post-validations:

<?php
use Phalcon\Mvc\Form;
class ContactForm extends Form
{
    public function beforeValidation()
    {
    }
}

渲染表单Rendering Forms

开发者对表单的渲染操作有完全的控制，下面的的例子展示了如何使用标准方法渲染html元素：

You can render the form with total flexibility, the following example shows how to render each element using an standard procedure:

<?php
<form method="post">
    <?php
        //Traverse the form
        foreach ($form as $element) {
            //Get any generated messages for the current element
            $messages = $form->getMessagesFor($element->getName());
            if (count($messages)) {
                //Print each element
                echo '<div class="messages">';
                foreach ($messages as $message) {
                    echo $message;
                }
                echo '</div>';
            }
            echo '<p>';
            echo '<label for="', $element->getName(), '">', $element->getLabel(), '</label>';
            echo $element;
            echo '</p>';
        }
    ?>
    <input type="submit" value="Send"/>
</form>

或是在登录表单中重用表单类：

Or reuse the logic in your form class:

<?php
use Phalcon\Forms\Form;
class ContactForm extends Form
{
    public function initialize()
    {
        //...
    }
    public function renderDecorated($name)
    {
        $element  = $this->get($name);
        //Get any generated messages for the current element
        $messages = $this->getMessagesFor($element->getName());
        if (count($messages)) {
            //Print each element
            echo '<div class="messages">';
            foreach ($messages as $message) {
                echo $this->flash->error($message);
            }
            echo '</div>';
        }
        echo '<p>';
        echo '<label for="', $element->getName(), '">', $element->getLabel(), '</label>';
        echo $element;
        echo '</p>';
    }
}

视图中：

In the view:

<?php
echo $element->renderDecorated('name');
echo $element->renderDecorated('telephone');

创建表单控件Creating Form Elements

除了可以使用phalcon提供的html元素以外，开发者还可以使用自定义的html元素：

In addition to the form elements provided by Phalcon you can create your own custom elements:

<?php
use Phalcon\Forms\Element;
class MyElement extends Element
{
    public function render($attributes=null)
    {
        $html = //... produce some html
        return $html;
    }
}

表单管理Forms Manager

此组件为开发者提供了一个表单管理器，可以用来注册表单，此组件可以使用服务容器来访问：

This component provides a forms manager that can be used by the developer to register forms and access them via the service locator:

<?php
use Phalcon\Forms\Manager as FormsManager;
$di['forms'] = function() {
    return new FormsManager();
};

表单被添加到表单管理器，然后设置了唯一的名字：

Forms are added to the forms manager and referenced by a unique name:

<?php
$this->forms->set('login', new LoginForm());

使用唯一名，我们可以在应用的任何地方访问到表单：

Using the unique name, forms can be accessed in any part of the application:

<?php
echo $this->forms->get('login')->render();

外部资源External Resources

[Vökuró <http://vokuro.phalconphp.com>\`\_是一个使用表单构建器来创建和维护表单的示例 [`Github](https://github.com/phalcon/vokuro)\]

Vökuró, is a sample application that uses the forms builder to create and manage forms, [Github]