[TOC]
# 视图助手（标签）
由于命名约定和必须考虑的众多属性，编写和维护HTML标记很快就会变成一项繁琐的任务。Phalcon通过提供Phalcon \ Tag组件来处理这种复杂性，而 `Phalcon\Tag` 组件又提供视图助手来生成HTML标记。
此组件可用于纯HTML + PHP视图或`Volt`模板。
>[warning] 本指南并非旨在提供可用帮助程序及其参数的完整文档。请访问API中的`Phalcon\Tag`页面以获取完整参考。
## 文档内容类型
Phalcon提供 `Phalcon\Tag::setDoctype()` 帮助器来设置内容的文档类型。文档类型设置可能会影响其他标记帮助程序生成的HTML输出。例如，如果您设置XHTML文档类型系列，则返回或输出HTML标记的帮助程序将生成自动关闭标记以遵循有效的XHTML标准。
`Phalcon\Tag` 命名空间中的可用文档类型常量是：
| 常量 | 文档类型 |
| -------------------- | ---------------------- |
| HTML32 | HTML 3.2 |
| HTML401_STRICT | HTML 4.01 Strict |
| HTML401_TRANSITIONAL | HTML 4.01 Transitional |
| HTML401_FRAMESET | HTML 4.01 Frameset |
| HTML5 | HTML 5 |
| XHTML10_STRICT | XHTML 1.0 Strict |
| XHTML10_TRANSITIONAL | XHTML 1.0 Transitional |
| XHTML10_FRAMESET | XHTML 1.0 Frameset |
| XHTML11 | XHTML 1.1 |
| XHTML20 | XHTML 2.0 |
| XHTML5 | XHTML 5 |
设置文档类型。
```php
<?php
use Phalcon\Tag;
$this->tag->setDoctype(Tag::HTML401_STRICT);
```
获取文档类型。
```php
<?= $this->tag->getDoctype() ?>
<html>
<!-- your HTML code -->
</html>
```
将生成以下HTML。
```html
<!DOCTYPE html PUBLIC '-//W3C//DTD HTML 4.01//EN'
'http://www.w3.org/TR/html4/strict.dtd'>
<html>
<!-- your HTML code -->
</html>
```
Volt语法：
```twig
{{ get_doctype() }}
<html>
<!-- your HTML code -->
</html>
```
## 生成链接
任何Web应用程序或网站中的一个真正常见任务是生成允许我们从一个页面导航到另一个页面的链接。当它们是内部URL时，我们可以通过以下方式创建它们：
```php
<!-- for the default route -->
<?= $this->tag->linkTo('products/search', 'Search') ?>
<!-- with CSS attributes -->
<?= $this->tag->linkTo(['products/edit/10', 'Edit', 'class' => 'edit-btn']) ?>
<!-- for a named route -->
<?= $this->tag->linkTo([['for' => 'show-product', 'title' => 123, 'name' => 'carrots'], 'Show']) ?>
```
实际上，所有生成的URL都是由 `Phalcon\Mvc\Url` 组件生成的。使用Volt可以生成相同的链接：
```twig
<!-- for the default route -->
{{ link_to('products/search', 'Search') }}
<!-- for a named route -->
{{ link_to(['for': 'show-product', 'id': 123, 'name': 'carrots'], 'Show') }}
<!-- for a named route with a HTML class -->
{{ link_to(['for': 'show-product', 'id': 123, 'name': 'carrots'], 'Show', 'class': 'edit-btn') }}
```
## 创建表单
Web应用程序中的表单在检索用户输入方面起着至关重要的作用。以下示例显示如何使用视图助手实现简单搜索表单：
```php
<!-- Sending the form by method POST -->
<?= $this->tag->form('products/search') ?>
<label for='q'>Search:</label>
<?= $this->tag->textField('q') ?>
<?= $this->tag->submitButton('Search') ?>
<?= $this->tag->endForm() ?>
<!-- Specifying another method or attributes for the FORM tag -->
<?= $this->tag->form(['products/search', 'method' => 'get']); ?>
<label for='q'>Search:</label>
<?= $this->tag->textField('q'); ?>
<?= $this->tag->submitButton('Search'); ?>
<?= $this->tag->endForm() ?>
```
最后一个代码将生成以下HTML：
```html
<form action='/store/products/search/' method='get'>
<label for='q'>Search:</label>
<input type='text' id='q' value='' name='q' />
<input type='submit' value='Search' />
</form>
```
在Volt中生成相同的表单：
```twig
<!-- Specifying another method or attributes for the FORM tag -->
{{ form('products/search', 'method': 'get') }}
<label for='q'>Search:</label>
{{ text_field('q') }}
{{ submit_button('Search') }}
{{ endForm() }}
```
Phalcon还提供了一个表单构建器，以面向对象的方式创建表单。
## 助手生成表单元素
Phalcon提供了一系列帮助程序来生成表单元素，如文本字段，按钮等。每个帮助程序的第一个参数始终是要生成的元素的名称。提交表单时，名称将与表单数据一起传递。在控制器中，您可以使用请求对象上的`getPost()`和`getQuery()`方法（`$this->request`）使用相同的名称获取这些值。
```php
<?php echo $this->tag->textField('username') ?>
<?php echo $this->tag->textArea(
[
'comment',
'This is the content of the text-area',
'cols' => '6',
'rows' => 20,
]
) ?>
<?php echo $this->tag->passwordField(
[
'password',
'size' => 30,
]
) ?>
<?php echo $this->tag->hiddenField(
[
'parent_id',
'value' => '5',
]
) ?>
```
Volt语法：
```twig
{{ text_field('username') }}
{{ text_area('comment', 'This is the content', 'cols': '6', 'rows': 20) }}
{{ password_field('password', 'size': 30) }}
{{ hidden_field('parent_id', 'value': '5') }}
```
## 制作选择框
生成选择框（选择框）很容易，特别是如果相关数据存储在PHP关联数组中。选择元素的助手是`Phalcon\Tag::select()`和`Phalcon\Tag::selectStatic()`。`Phalcon\Tag::select()`一直是专门设计用于Phalcon模型（`Phalcon\Mvc\Model`），而`Phalcon\Tag::selectStatic()`可以用PHP数组。
```php
<?php
$products = Products::find("type = 'vegetables'");
// Using data from a resultset
echo $this->tag->select(
[
'productId',
$products,
'using' => [
'id',
'name',
]
]
);
// Using data from an array
echo $this->tag->selectStatic(
[
'status',
[
'A' => 'Active',
'I' => 'Inactive',
]
]
);
```
将生成以下HTML：
```html
<select id='productId' name='productId'>
<option value='101'>Tomato</option>
<option value='102'>Lettuce</option>
<option value='103'>Beans</option>
</select>
<select id='status' name='status'>
<option value='A'>Active</option>
<option value='I'>Inactive</option>
</select>
```
您可以为生成的HTML添加一个`空`选项：
```php
<?php
$products = Products::find("type = 'vegetables'");
// Creating a Select Tag with an empty option
echo $this->tag->select(
[
'productId',
$products,
'using' => [
'id',
'name',
],
'useEmpty' => true,
]
);
```
生成此HTML：
```html
<select id='productId' name='productId'>
<option value=''>Choose..</option>
<option value='101'>Tomato</option>
<option value='102'>Lettuce</option>
<option value='103'>Beans</option>
</select>
```
```php
<?php
$products = Products::find("type = 'vegetables'");
// Creating a Select Tag with an empty option with default text
echo $this->tag->select(
[
'productId',
$products,
'using' => [
'id',
'name',
],
'useEmpty' => true,
'emptyText' => 'Please, choose one...',
'emptyValue' => '@',
]
);
```
```html
<select id='productId' name='productId'>
<option value='@'>Please, choose one..</option>
<option value='101'>Tomato</option>
<option value='102'>Lettuce</option>
<option value='103'>Beans</option>
</select>
```
以上示例的Volt语法：
```twig
{# Creating a Select Tag with an empty option with default text #}
{{ select('productId', products, 'using': ['id', 'name'],
'useEmpty': true, 'emptyText': 'Please, choose one...', 'emptyValue': '@') }}
```
## 分配HTML属性
所有帮助程序都接受一个数组作为它们的第一个参数，该参数可以包含生成的元素的其他HTML属性。
```php
<?php $this->tag->textField(
[
'price',
'size' => 20,
'maxlength' => 30,
'placeholder' => 'Enter a price',
]
) ?>
```
或使用Volt：
```twig
{{ text_field('price', 'size': 20, 'maxlength': 30, 'placeholder': 'Enter a price') }}
```
生成以下HTML：
```html
<input type='text' name='price' id='price' size='20' maxlength='30'
placeholder='Enter a price' />
```
## 设置助手值
### 来自控制器
对于MVC框架来说，为视图中的表单元素设置特定值是一个很好的编程原则。您可以使用 `Phalcon\Tag::setDefault()`直接从控制器设置这些值。此帮助程序为视图中存在的任何帮助程序预加载值。如果视图中的任何帮助程序具有与预加载值匹配的名称，则它将使用它，除非在视图中的帮助程序上直接分配值。
```php
<?php
use Phalcon\Mvc\Controller;
class ProductsController extends Controller
{
public function indexAction()
{
$this->tag->setDefault('color', 'Blue');
}
}
```
在视图中，selectStatic助手匹配用于预设值的相同索引。在这种情况下`color`：
```php
<?php
echo $this->tag->selectStatic(
[
'color',
[
'Yellow' => 'Yellow',
'Blue' => 'Blue',
'Red' => 'Red',
]
]
);
```
这将生成以下选择标记，并选择值“Blue”：
```html
<select id='color' name='color'>
<option value='Yellow'>Yellow</option>
<option value='Blue' selected='selected'>Blue</option>
<option value='Red'>Red</option>
</select>
```
### 来自请求
`Phalcon\Tag` 帮助程序具有的一个特殊功能是它们可以在请求之间保留表单帮助程序的值。这样，您可以轻松显示验证消息，而不会丢失输入的数据。
### 直接指定值
每个表单助手都支持参数'value'。有了它，您可以直接为助手指定值。如果存在此参数，则将忽略使用`setDefault()`或通过请求的任何预设值。
## 动态更改文档标题
`Phalcon\Tag` 提供帮助程序以动态更改控制器中的文档标题。以下示例演示了：
```php
<?php
use Phalcon\Mvc\Controller;
class PostsController extends Controller
{
public function initialize()
{
$this->tag->setTitle('Your Website');
}
public function indexAction()
{
$this->tag->prependTitle('Index of Posts - ');
}
}
```
```php
<html>
<head>
<?php echo $this->tag->getTitle(); ?>
</head>
<body>
</body>
</html>
```
将生成以下HTML：
```php
<html>
<head>
<title>Index of Posts - Your Website</title>
</head>
<body>
</body>
</html>
```
## 静态内容助手
`Phalcon\Tag` 还提供帮助程序来生成脚本，链接或img等标记。它们有助于快速轻松地生成应用程序的静态资源
### 图片
```php
<?php
// Generate <img src='/your-app/img/hello.gif'>
echo $this->tag->image('img/hello.gif');
// Generate <img alt='alternative text' src='/your-app/img/hello.gif'>
echo $this->tag->image(
[
'img/hello.gif',
'alt' => 'alternative text',
]
);
```
Volt语法：
```twig
{# Generate <img src='/your-app/img/hello.gif'> #}
{{ image('img/hello.gif') }}
{# Generate <img alt='alternative text' src='/your-app/img/hello.gif'> #}
{{ image('img/hello.gif', 'alt': 'alternative text') }}
```
### 样式表
```php
<?php
// Generate <link rel='stylesheet' href='http://fonts.googleapis.com/css?family=Rosario' type='text/css'>
echo $this->tag->stylesheetLink('http://fonts.googleapis.com/css?family=Rosario', false);
// Generate <link rel='stylesheet' href='/your-app/css/styles.css' type='text/css'>
echo $this->tag->stylesheetLink('css/styles.css');
```
Volt语法：
```twig
{# Generate <link rel='stylesheet' href='http://fonts.googleapis.com/css?family=Rosario' type='text/css'> #}
{{ stylesheet_link('http://fonts.googleapis.com/css?family=Rosario', false) }}
{# Generate <link rel='stylesheet' href='/your-app/css/styles.css' type='text/css'> #}
{{ stylesheet_link('css/styles.css') }}
```
### Javascript
```php
<?php
// Generate <script src='http://localhost/javascript/jquery.min.js' type='text/javascript'></script>
echo $this->tag->javascriptInclude('http://localhost/javascript/jquery.min.js', false);
// Generate <script src='/your-app/javascript/jquery.min.js' type='text/javascript'></script>
echo $this->tag->javascriptInclude('javascript/jquery.min.js');
```
Volt语法：
```twig
{# Generate <script src='http://localhost/javascript/jquery.min.js' type='text/javascript'></script> #}
{{ javascript_include('http://localhost/javascript/jquery.min.js', false) }}
{# Generate <script src='/your-app/javascript/jquery.min.js' type='text/javascript'></script> #}
{{ javascript_include('javascript/jquery.min.js') }}
```
### HTML5元素 - 通用HTML帮助器
Phalcon提供了一个通用的HTML帮助程序，允许生成任何类型的HTML元素。开发人员可以为帮助程序生成有效的HTML元素名称。
```php
<?php
// Generate
// <canvas id='canvas1' width='300' class='cnvclass'>
// This is my canvas
// </canvas>
echo $this->tag->tagHtml(
'canvas',
[
'id' => 'canvas1',
'width' => '300',
'class' => 'cnvclass',
],
false,
true,
true
);
echo 'This is my canvas';
echo $this->tag->tagHtmlClose('canvas');
```
Volt语法：
```php
{# Generate
<canvas id='canvas1' width='300' class='cnvclass'>
This is my canvas
</canvas> #}
{{ tag_html('canvas', ['id': 'canvas1', width': '300', 'class': 'cnvclass'], false, true, true) }}
This is my canvas
{{ tag_html_close('canvas') }}
```
## 标签服务
`Phalcon\Tag` 可通过标签服务获得，这意味着您可以从服务容器所在的应用程序的任何部分访问它：
```php
<?php echo $this->tag->linkTo('pages/about', 'About') ?>
```
您可以轻松地将新助手添加到自定义组件中，替换服务容器中的服务`tag`：
```php
<?php
use Phalcon\Tag;
class MyTags extends Tag
{
// ...
// Create a new helper
public static function myAmazingHelper($parameters)
{
// ...
}
// Override an existing method
public static function textField($parameters)
{
// ...
}
}
```
然后更改服务`tag`的定义：
```php
<?php
$di['tag'] = function () {
return new MyTags();
};
```
## 创建自己的助手工具
您可以轻松创建自己的帮助程序。首先，首先在与控制器和模型相同的目录中创建一个新文件夹。给它一个与你正在创建的相关的标题。对于我们这里的例子，我们可以称之为'customhelpers'。接下来，我们将在这个新目录中创建一个名为`MyTags.php`的新文件。此时，我们的结构看起来类似于：`/app/customhelpers/MyTags.php`。在`MyTags.php`中，我们将扩展`Phalcon\Tag`并实现您自己的帮助器。以下是自定义帮助程序的简单示例：
```php
<?php
use Phalcon\Tag;
class MyTags extends Tag
{
/**
* Generates a widget to show a HTML5 audio tag
*
* @param array
* @return string
*/
public static function audioField($parameters)
{
// Converting parameters to array if it is not
if (!is_array($parameters)) {
$parameters = [$parameters];
}
// Determining attributes 'id' and 'name'
if (!isset($parameters[0])) {
$parameters[0] = $parameters['id'];
}
$id = $parameters[0];
if (!isset($parameters['name'])) {
$parameters['name'] = $id;
} else {
if (!$parameters['name']) {
$parameters['name'] = $id;
}
}
// Determining widget value,
// \Phalcon\Tag::setDefault() allows to set the widget value
if (isset($parameters['value'])) {
$value = $parameters['value'];
unset($parameters['value']);
} else {
$value = self::getValue($id);
}
// Generate the tag code
$code = '<audio id="' . $id . '" value="' . $value . '" ';
foreach ($parameters as $key => $attributeValue) {
if (!is_integer($key)) {
$code.= $key . '="' . $attributeValue . '" ';
}
}
$code.=' />';
return $code;
}
}
```
在创建自定义帮助程序之后，我们将从位于公共目录中的`index.php`中自动加载包含我们的帮助程序类的新目录。
```php
<?php
use Phalcon\Loader;
use Phalcon\Mvc\Application;
use Phalcon\Di\FactoryDefault();
use Phalcon\Exception as PhalconException;
try {
$loader = new Loader();
$loader->registerDirs(
[
'../app/controllers',
'../app/models',
'../app/customhelpers', // Add the new helpers folder
]
);
$loader->register();
$di = new FactoryDefault();
// Assign our new tag a definition so we can call it
$di->set(
'MyTags',
function () {
return new MyTags();
}
);
$application = new Application($di);
$response = $application->handle();
$response->send();
} catch (PhalconException $e) {
echo 'PhalconException: ', $e->getMessage();
}
```
现在，您已准备好在视图中使用新助手：
```php
<body>
<?php
echo MyTags::audioField(
[
'name' => 'test',
'id' => 'audio_test',
'src' => '/path/to/audio.mp3',
]
);
?>
</body>
```
您还可以查看Volt一个更快的PHP模板引擎，在这里您可以使用更友好的开发人员语法来帮助`Phalcon\Tag`提供帮助程序。
- 常规
- Welcome
- 贡献
- 生成回溯
- 测试重现
- 单元测试
- 入门
- 安装
- Web服务器设置
- WAMP
- XAMPP
- 教程
- 基础教程
- 教程：创建一个简单的REST API
- 教程：Vökuró
- 提升性能
- 教程：INVO
- 开发环境
- Phalcon Compose (Docker)
- Nanobox
- Phalcon Box (Vagrant)
- 开发工具
- Phalcon开发者工具的安装
- Phalcon开发者工具的使用
- 调试应用程序
- 核心
- MVC应用
- 微应用
- 创建命令行（CLI）应用程序
- 依赖注入与服务定位
- MVC架构
- 服务
- 使用缓存提高性能
- 读取配置
- 上下文转义
- 类加载器
- 使用命名空间
- 日志
- 队列
- 数据库
- 数据库抽象层
- Phalcon查询语言（PHQL）
- ODM（对象文档映射器）
- 使用模型
- 模型行为
- ORM缓存
- 模型事件
- 模型元数据
- 模型关系
- 模型事务
- 验证模型
- 数据库迁移
- 分页
- 前端
- Assets管理
- 闪存消息
- 表单
- 图像
- 视图助手（标签）
- 使用视图
- Volt：模板引擎
- 业务逻辑
- 访问控制列表（ACL）
- 注解解析器
- 控制器
- 调度控制器
- 事件管理器
- 过滤与清理
- 路由
- 在session中存储数据
- 生成URL和路径
- 验证
- HTTP
- Cookies管理
- 请求环境
- 返回响应
- 安全
- 加密/解密
- 安全
- 国际化
- 国际化
- 多语言支持