Phalcon之 表单（Forms）
Phalcon中提供了 Phalcon\Forms组件以方便开发人员创建和维护应用中的表单。 以下的样例中展示了主要的用法：
<?php
use Phalcon\Forms\Form,
Phalcon\Forms\Element\Text,
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'
)));
可在表单定义时穿插使用表单元素的字义：
<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项， 第二个參数中能够对一些属性进行设置。
<p>
<label>Name</label>
<?php echo $form->render("name", array('maxlength' => 30, 'placeholder' => 'Type your name')) ?>
</p>
html的属性也能够在创建时指定：
<?php
$form->add(new Text("name", array(
'maxlength' => 30,
'placeholder' => 'Type your name'
)));
初始化表单（Initializing forms）¶
从上面的样例我们能够看到表单项也能够在form对象初始化后进行加入。 当然开发人员也能够对原有的Form类进行扩展：
<?php
use Phalcon\Forms\Form,
Phalcon\Forms\Element\Text,
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')
)));
}
}
因为 Phalcon\Forms\Form 实现了 Phalcon\DI\Injectable 接口， 所以开发人员能够依据自己的须要訪问应用中的服务。
<?php
use Phalcon\Forms\Form,
Phalcon\Forms\Element\Text,
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"));
}
}
相关的实体在初始化时加入到表单， 自己定义的选项通过构造器传送：
<?php
use Phalcon\Forms\Form,
Phalcon\Forms\Element\Text,
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'));
}
}
在表单实例中必需要这样使用：
<?php
$form = new UsersForm(new Users(), array('edit' => true));
验证（Validation）¶
Phalcon表单组件能够和 validation 集成，以提供验证。 开发人员要单独为每一个html元素提供内置或自己定义的验证器。
<?php
use Phalcon\Forms\Element\Text,
Phalcon\Validation\Validator\PresenceOf,
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);
然后， 开发人员能够依据用户的输入进行验证：
<?php
if (!$form->isValid($_POST)) {
foreach ($form->getMessages() as $message) {
echo $message, '<br>';
}
}
验证器运行的顺序和注冊的顺序一致。
默认情况下，全部的元素产生的消息是放在一起的， 所以开发人员能够使用简单的foreach来遍历消息， 开发人员能够依照自己的意愿组织输出：
<?php
foreach ($form->getMessages(false) as $attribute => $messages) {
echo 'Messages generated by ', $attribute, ':', "\n";
foreach ($messages as $message) {
echo $message, '<br>';
}
}
或获取指定元素的消息：
<?php
foreach ($form->getMessagesFor('name') as $message) {
echo $message, '<br>';
}
过滤（Filtering）¶
表单元素能够在进行验证前先进行过滤， 开发人员能够为每一个元素设置过滤器：
设置用户选项（Setting User Options）¶
表单与实体（Forms + Entities）¶
我们能够把 model/collection/plain 设置到表单对象中， 这样 phalcon 会自己主动的设置表单元素的值：
<?php
$robot = Robots::findFirst();
$form = new Form($robot);
$form->add(new Text("name"));
$form->add(new Text("year"));
在表单渲染时假设表单项未设置默认值， phalcon会使用对象实体值作为默认值：
<?php echo $form->render('name') ?>
开发人员能够使用以下的方式验证表单及利用用户的输入来设置值：
<?php
$form->bind($_POST, $robot);
//Check if the form is valid
if ($form->isValid()) {
//Save the entity
$robot->save();
}
也能够使用一个简单的类做为对象实体进行參数传递：
<?php
class Preferences
{
public $timezone = 'Europe/Amsterdam';
public $receiveEmails = 'No';
}
使用此类做为对象实体，这样能够使用此类中的值作为表单的默认值：
<?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, 这样能够给开发人员很多其它的自由， 当然也会洽使开发稍麻烦一些，只是这是值得的：
<?php
class Preferences
{
public $timezone;
public $receiveEmails;
public function getTimezone()
{
return 'Europe/Amsterdam';
}
public function getTimezone()
{
return 'No';
}
}
表单控件（Form Elements）¶
Phalcon提供了一些内置的html元素类， 全部这些元素类仅位于 Phalcon\Forms\Element命名空间下：
| 名称 | 描写叙述 | 演示样例 |
|---|---|---|
| Text | 产生 INPUT[type=text] 项 | Example |
| Password | 产生 INPUT[type=password] 项 | Example |
| Select | 产生 SELECT tag (combo lists) 项 | Example |
| Check | 产生 INPUT[type=check] 项 | Example |
| Textarea | 产生 TEXTAREA 项 | Example |
| Hidden | 产生 INPUT[type=hidden] 项 | Example |
| File | 产生 INPUT[type=file] 项 | Example |
| Date | 产生 INPUT[type=date] 项 | Example |
| Numeric | 产生 INPUT[type=number] 项 | Example |
| Submit | 产生 INPUT[type=submit] 项 | Example |
事件回调（Event Callbacks）¶
当扩展表单时， 我们能够在表单类中实现验证前操作及验证后操作：
<?php
class ContactForm extends Phalcon\Mvc\Form
{
public function beforeValidation()
{
}
}
渲染表单（Rendering Forms）¶
开发人员对表单的渲染操作有全然的控制， 以下的的样例展示了怎样使用标准方法渲染html元素：
<?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>
或是在登录表单中重用表单类：
<?php
class ContactForm extends Phalcon\Forms\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>';
}
}
视图中：
<?php
echo $element->renderDecorated('name');
echo $element->renderDecorated('telephone');
创建表单控件（Creating Form Elements）¶
除了能够使用phalcon提供的html元素以外， 开发人员还能够使用自己定义的html元素：
<?php
use Phalcon\Forms\Element;
class MyElement extends Element
{
public function render($attributes=null)
{
$html = //... produce some html
return $html;
}
}
表单管理（Forms Manager）¶
此组件为开发人员提供了一个表单管理器， 能够用来注冊表单，此组件能够使用服务容器来訪问：
<?php
$di['forms'] = function() {
return new Phalcon\Forms\Manager();
};
表单被加入到表单管理器， 然后设置了唯一的名字：
<?php
$this->forms->set('login', new LoginForm());
使用唯一名， 我们能够在应用的不论什么地方訪问到表单：
<?php
echo $this->forms->get('login')->render();