# 表单（Forms）
Phalcon中提供了`Phalcon\Forms`组件以方便开发者创建和维护应用中的表单。
下面的例子中展示了基本的使用方法：
~~~
<?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",
[
"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组件。 当使用:code:render()`函数时， phalcon内部会使用 :doc:`Phalcon\\Tag 生成相应的html项， 第二个参数中可以对一些属性进行设置。
~~~
<p>
<label>
Name
</label>
<?php echo $form->render("name", ["maxlength" => 30, "placeholder" => "Type your name"]); ?>
</p>
~~~
HTML的属性也可以在创建时指定：
~~~
<?php
$form->add(
new Text(
"name",
[
"maxlength" => 30,
"placeholder" => "Type your name",
]
)
);
~~~
## 初始化表单（Initializing forms）
从上面的例子我们可以看到表单项也可以在form对象初始化后进行添加。 当然开发者也可以对原有的Form类进行扩展：
~~~
<?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(),
[
"using" => [
"id",
"name",
]
]
)
);
}
}
~~~
由于[Phalcon\\Forms\\Form](http://docs.iphalcon.cn/api/Phalcon_Forms_Form.html)实现了[Phalcon\\Di\\Injectable](http://docs.iphalcon.cn/api/Phalcon_Di_Injectable.html)接口， 所以开发者可以根据自己的需要访问应用中的服务。
~~~
<?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"
)
);
}
}
~~~
相关的实体在初始化时添加到表单， 自定义的选项通过构造器传送：
~~~
<?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(Users $user, array $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(),
[
"edit" => true,
]
);
~~~
## 验证（Validation）
Phalcon表单组件可以和[validation](http://docs.iphalcon.cn/reference/validation.html)集成，以提供验证。 开发者要单独为每个html元素提供内置或自定义的验证器。
~~~
<?php
use Phalcon\Forms\Element\Text;
use Phalcon\Validation\Validator\PresenceOf;
use Phalcon\Validation\Validator\StringLength;
$name = new Text(
"name"
);
$name->addValidator(
new PresenceOf(
[
"message" => "The name is required",
]
)
);
$name->addValidator(
new StringLength(
[
"min" => 10,
"messageMinimum" => "The name is too short",
]
)
);
$form->add($name);
~~~
然后， 开发者可以根据用户的输入进行验证：
~~~
<?php
if (!$form->isValid($_POST)) {
$messages = $form->getMessages();
foreach ($messages 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
$messages = $form->getMessagesFor("name");
foreach ($messages as $message) {
echo $message, "<br>";
}
~~~
## 过滤（Filtering）
表单元素可以在进行验证前先进行过滤， 开发者可以为每个元素设置过滤器：
~~~
<?php
use Phalcon\Forms\Element\Text;
$name = new Text(
"name"
);
// Set multiple filters
$name->setFilters(
[
"string",
"trim",
]
);
$form->add($name);
$email = new Text(
"email"
);
// Set one filter
$email->setFilters(
"email"
);
$form->add($email);
~~~
> Learn more about filtering in Phalcon by reading the[Filter documentation](http://docs.iphalcon.cn/reference/filter.html).
## 表单与实体（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",
[
"America/New_York" => "New York",
"Europe/Amsterdam" => "Amsterdam",
"America/Sao_Paulo" => "Sao Paulo",
"Asia/Tokyo" => "Tokyo",
]
)
);
$form->add(
new Select(
"receiveEmails",
[
"Yes" => "Yes, please!",
"No" => "No, thanks",
]
)
);
~~~
实体中也可以使用getters, 这样可以给开发者更多的自由， 当然也会使开发稍麻烦一些，不过这是值得的：
~~~
<?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](http://docs.iphalcon.cn/api/Phalcon_Forms_Element.html)命名空间下：
| 名称 | 描述 |
| --- | --- |
| [Phalcon\\Forms\\Element\\Text](http://docs.iphalcon.cn/api/Phalcon_Forms_Element_Text.html) | 产生 INPUT\[type=text\] 项 |
| [Phalcon\\Forms\\Element\\Password](http://docs.iphalcon.cn/api/Phalcon_Forms_Element_Password.html) | 产生 INPUT\[type=password\] 项 |
| [Phalcon\\Forms\\Element\\Select](http://docs.iphalcon.cn/api/Phalcon_Forms_Element_Select.html) | 产生 SELECT tag (combo lists) 项 |
| [Phalcon\\Forms\\Element\\Check](http://docs.iphalcon.cn/api/Phalcon_Forms_Element_Check.html) | 产生 INPUT\[type=check\] 项 |
| [Phalcon\\Forms\\Element\\TextArea](http://docs.iphalcon.cn/api/Phalcon_Forms_Element_TextArea.html) | 产生 TEXTAREA 项 |
| [Phalcon\\Forms\\Element\\Hidden](http://docs.iphalcon.cn/api/Phalcon_Forms_Element_Hidden.html) | 产生 INPUT\[type=hidden\] 项 |
| [Phalcon\\Forms\\Element\\File](http://docs.iphalcon.cn/api/Phalcon_Forms_Element_File.html) | 产生 INPUT\[type=file\] 项 |
| [Phalcon\\Forms\\Element\\Date](http://docs.iphalcon.cn/api/Phalcon_Forms_Element_Date.html) | 产生 INPUT\[type=date\] 项 |
| [Phalcon\\Forms\\Element\\Numeric](http://docs.iphalcon.cn/api/Phalcon_Forms_Element_Numeric.html) | 产生 INPUT\[type=number\] 项 |
| [Phalcon\\Forms\\Element\\Submit](http://docs.iphalcon.cn/api/Phalcon_Forms_Element_Submit.html) | 产生 INPUT\[type=submit\] 项 |
## 事件回调（Event Callbacks）
当扩展表单时， 我们可以在表单类中实现验证前操作及验证后操作：
~~~
<?php
use Phalcon\Forms\Form;
class ContactForm extends 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
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>";
}
}
~~~
视图中：
~~~
<?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
use Phalcon\Forms\Manager as FormsManager;
$di["forms"] = function () {
return new FormsManager();
};
~~~
表单被添加到表单管理器， 然后设置了唯一的名字：
~~~
<?php
$this->forms->set(
"login",
new LoginForm()
);
~~~
使用唯一名， 我们可以在应用的任何地方访问到表单：
~~~
<?php
$loginForm = $this->forms->get("login");
echo $loginForm->render();
~~~
## 外部资源（External Resources)
* [Vökuró](http://vokuro.phalconphp.com/)是一个使用表单构建器来创建和维护表单的示例 \[[Github](https://github.com/phalcon/vokuro)\]
- 简介
- 安装
- 安装(installlation)
- XAMPP下的安装
- WAMP下安装
- Nginx安装说明
- Apache安装说明
- Cherokee 安装说明
- 使用 PHP 内置 web 服务器
- Phalcon 开发工具
- Linux 系统下使用 Phalcon 开发工具
- Mac OS X 系统下使用 Phalcon 开发工具
- Windows 系统下使用 Phalcon 开发工具
- 教程
- 教程 1：让我们通过例子来学习
- 教程 2：INVO简介
- 教程 3: 保护INVO
- 教程4: 使用CRUD
- 教程5: 定制INVO
- 教程 6: Vökuró
- 教程 7：创建简单的 REST API
- 组件
- 依赖注入与服务定位器
- MVC架构
- 使用控制器
- 使用模型
- 模型关系
- 事件与事件管理器
- Behaviors
- 模型元数据
- 事务管理
- 验证数据完整性
- Workingwith Models
- Phalcon查询语言
- 缓存对象关系映射
- 对象文档映射 ODM
- 使用视图
- 视图助手
- 资源文件管理
- Volt 模版引擎
- MVC 应用
- 路由
- 调度控制器
- Micro Applications
- 使用命名空间
- 事件管理器
- Request Environmen
- 返回响应
- Cookie 管理
- 生成 URL 和 路径
- 闪存消息
- 使用 Session 存储数据
- 过滤与清理
- 上下文编码
- 验证Validation
- 表单_Forms
- 读取配置
- 分页 Pagination
- 使用缓存提高性能
- 安全
- 加密与解密 Encryption/Decryption
- 访问控制列表
- 多语言支持
- 类加载器 Class Autoloader
- 日志记录_Logging
- 注释解析器 Annotations Parser
- 命令行应用 Command Line Applications
- Images
- 队列 Queueing
- 数据库抽象层
- 国际化
- 数据库迁移
- 调试应用程序
- 单元测试
- 进阶技巧与延伸阅读
- 提高性能：下一步该做什么？
- Dependency Injection Explained
- Understanding How Phalcon Applications Work
- Api
- Abstract class Phalcon\Acl