视图助手View Helpers

编写和维护HTML标记很快就会变成一个乏味的任务,因为命名约定和众多的属性需要被考虑。Phalcon提供:doc:`Phalcon\Tag <../api/Phalcon_Tag>`来处理这些复杂的工作,使用视图助手来生成HTML标记。

Writing and maintaining HTML markup can quickly become a tedious task because of the naming conventions and numerous attributes that have to be taken into consideration. Phalcon deals with this complexity by offering Phalcon\Tag, which in turn offers view helpers to generate HTML markup.

该组件可被用在一个纯HTML + PHP视图或:doc:`Volt <volt>`模板。

This component can be used in a plain HTML+PHP view or in a Volt template.

本指南并不打算成为一个完整的文档,更多的使用说明请参考:doc:`Phalcon\Tag <../api/Phalcon_Tag>`页面的完整的api说明。

This guide is not intended to be a complete documentation of available helpers and their arguments. Please visit the Phalcon\Tag page in the API for a complete reference.

文档内容的类型Document Type of Content

Phalcon提供Phalcon\Tag::setDoctype() 辅助设置文档内容的类型。文档类型设置可能会影响到其他标签产生的HTML输出。例如,如果设置XHTML文档类型,返回或输出HTML标签会产生遵循标准的XHTML闭合标记。

Phalcon provides Phalcon\Tag::setDoctype() helper to set document type of the content. Document type setting may affect HTML output produced by other tag helpers. For example, if you set XHTML document type family, helpers that return or output HTML tags will produce self-closing tags to follow valid XHTML standard.

Phalcon\Tag命名空间可用的文档类型：

Available document type constants in Phalcon\Tag namespace are:

ConstantDocument type
HTML32HTML 3.2
HTML401_STRICTHTML 4.01 Strict
HTML401_TRANSITIONALHTML 4.01 Transitional
HTML401_FRAMESETHTML 4.01 Frameset
HTML5HTML 5
XHTML10_STRICTXHTML 1.0 Strict
XHTML10_TRANSITIONALXHTML 1.0 Transitional
XHTML10_FRAMESETXHTML 1.0 Frameset
XHTML11XHTML 1.1
XHTML20XHTML 2.0
XHTML5XHTML 5

设置文档类型

Setting document type.

  1. <?php
  3. use Phalcon\Tag;
  5. $this->tag->setDoctype(Tag::HTML401_STRICT);
  6. ?>

获得文档类型

Getting document type.

  1. <?= $this->tag->getDoctype() ?>
  2. <html>
  3. <!-- your HTML code -->
  4. </html>

会产生如下HTML代码

The following HTML will be produced.

  1. <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"
  2.         "http://www.w3.org/TR/html4/strict.dtd">
  3. <html>
  4. <!-- your HTML code -->
  5. </html>

Volt语法：

Volt syntax:

  1. {{ get_doctype() }}
  2. <html>
  3. <!-- your HTML code -->
  4. </html>

生成链接Generating Links

一个真正的任何web应用程序或网站的共同任务是产生链接,让我们从一个页面导航到另一个地方。我们可以用以下方法创建内部url:

A real common task in any web application or website is to produce links that allow us to navigate from one page to another. When they are internal URLs we can create them in the following manner:

  1. <!-- for the default route -->
  2. <?= $this->tag->linkTo("products/search", "Search") ?>
  4. <!-- with CSS attributes -->
  5. <?= $this->tag->linkTo(array('products/edit/10', 'Edit', 'class' => 'edit-btn')) ?>
  7. <!-- for a named route -->
  8. <?= $this->tag->linkTo(array(array('for' => 'show-product', 'title' => 123, 'name' => 'carrots'), 'Show')) ?>

所有链接通过 :doc:`Phalcon\Mvc\Url <url>`组件来产生

Actually, all produced URLs are generated by the component Phalcon\Mvc\Url (or service “url” failing)

一些链接通过Volt来生成：

Same links generated with Volt:

  1. <!-- for the default route -->
  2. {{ link_to("products/search", "Search") }}
  4. <!-- for a named route -->
  5. {{ link_to(['for': 'show-product', 'id': 123, 'name': 'carrots'], 'Show') }}
  7. <!-- for a named route with class -->
  8. {{ link_to(['for': 'show-product', 'id': 123, 'name': 'carrots'], 'Show','class'=>'edit-btn') }}

创建表单Creating Forms

表单在web应用程序中获取用户输入，是一个非常重要组成部分。下面的例子展示了如何通过使用视图助手实现一个简单的搜索表单:

Forms in web applications play an essential part in retrieving user input. The following example shows how to implement a simple search form using view helpers:

  1. <!-- Sending the form by method POST -->
  2. <?= $this->tag->form("products/search") ?>
  3.     <label for="q">Search:</label>
  4.     <?= $this->tag->textField("q") ?>
  5.     <?= $this->tag->submitButton("Search") ?>
  6. <?= $this->tag->endForm() ?>
  8. <!-- Specifying another method or attributes for the FORM tag -->
  9. <?= $this->tag->form(array("products/search", "method" => "get")); ?>
  10.     <label for="q">Search:</label>
  11.     <?= $this->tag->textField("q"); ?>
  12.     <?= $this->tag->submitButton("Search"); ?>
  13. <?= $this->tag->endForm() ?>

这最后的代码将生成以下HTML:

This last code will generate the following HTML:

  1. <form action="/store/products/search/" method="get">
  2.      <label for="q">Search:</label>
  3.      <input type="text" id="q" value="" name="q" />
  4.      <input type="submit" value="Search" />
  5. </form>

在Volt中生成同样的表单：

Same form generated in Volt:

  1. <!-- Specifying another method or attributes for the FORM tag -->
  2. {{ form("products/search", "method": "get") }}
  3.     <label for="q">Search:</label>
  4.     {{ text_field("q") }}
  5.     {{ submit_button("Search") }}
  6. {{ endform() }}

Phalcon为面向对象创建表单提供:doc:`form builder <forms>`组件。

Phalcon also provides a form builder to create forms in an object-oriented manner.

生成表单元素的视图助手Helpers to Generate Form Elements

Phalcon提供了一系列的用于生成表单元素的助手，例如：文本框，按钮等。视图助手的第一个参数是生成元素的名称。提交表单时,将通过表单传递同名数据。在一个控制器可以在请求对象上（$this->request）通过使用getPost()和getQuery()方法得到相同的名称的数值。

Phalcon provides a series of helpers to generate form elements such as text fields, buttons and more. The first parameter of each helper is always the name of the element to be generated. When the form is submitted, the name will be passed along with the form data. In a controller you can get these values using the same name by using the getPost() and getQuery() methods on the request object ($this->request).

  1. <?php echo $this->tag->textField("username") ?>
  3. <?php echo $this->tag->textArea(array(
  4.     "comment",
  5.     "This is the content of the text-area",
  6.     "cols" => "6",
  7.     "rows" => 20
  8. )) ?>
  10. <?php echo $this->tag->passwordField(array(
  11.     "password",
  12.     "size" => 30
  13. )) ?>
  15. <?php echo $this->tag->hiddenField(array(
  16.     "parent_id",
  17.     "value"=> "5"
  18. )) ?>

Volt语法：

Volt syntax:

  1. {{ text_field("username") }}
  3. {{ text_area("comment", "This is the content", "cols": "6", "rows": 20) }}
  5. {{ password_field("password", "size": 30) }}
  7. {{ hidden_field("parent_id", "value": "5") }}

做筛选框Making Select Boxes

生成选择框是很容易的,尤其是如果相关数据存储在PHP关联数组。选择元素的视图助手为Phalcon\Tag::select() 和Phalcon\Tag::selectStatic()。Phalcon\Tag::select()是专门设计用于处理:doc:`Phalcon\Mvc\Model <models>`数据的,Phalcon\Tag::selectStatic()可以使用PHP数组。

Generating select boxes (select box) is easy, especially if the related data is stored in PHP associative arrays. The helpers for select elements are Phalcon\Tag::select() and Phalcon\Tag::selectStatic(). Phalcon\Tag::select() has been was specifically designed to work with Phalcon\Mvc\Model, while Phalcon\Tag::selectStatic() can with PHP arrays.

  1. <?php
  3. // Using data from a resultset
  4. echo $this->tag->select(
  5.     array(
  6.         "productId",
  7.         Products::find("type = 'vegetables'"),
  8.         "using" => array("id", "name")
  9.     )
  10. );
  12. // Using data from an array
  13. echo $this->tag->selectStatic(
  14.     array(
  15.         "status",
  16.         array(
  17.             "A" => "Active",
  18.             "I" => "Inactive",
  19.         )
  20.     )
  21. );

将会产生如下HTML代码：

The following HTML will generated:

  1. <select id="productId" name="productId">
  2.     <option value="101">Tomato</option>
  3.     <option value="102">Lettuce</option>
  4.     <option value="103">Beans</option>
  5. </select>
  7. <select id="status" name="status">
  8.     <option value="A">Active</option>
  9.     <option value="I">Inactive</option>
  10. </select>

可以添加一个空白的option到产生的html中：

You can add an “empty” option to the generated HTML:

  1. <?php
  3. // Creating a Select Tag with an empty option
  4. echo $this->tag->select(
  5.     array(
  6.         "productId",
  7.         Products::find("type = 'vegetables'"),
  8.         "using" => array("id", "name"),
  9.         "useEmpty" => true
  10.     )
  11. );
  1. <select id="productId" name="productId">
  2.     <option value="">Choose..</option>
  3.     <option value="101">Tomato</option>
  4.     <option value="102">Lettuce</option>
  5.     <option value="103">Beans</option>
  6. </select>
  1. <?php
  3. // Creating a Select Tag with an empty option with default text
  4. echo $this->tag->select(
  5.     array(
  6.         'productId',
  7.         Products::find("type = 'vegetables'"),
  8.         'using'      => array('id', "name"),
  9.         'useEmpty'   => true,
  10.         'emptyText'  => 'Please, choose one...',
  11.         'emptyValue' => '@'
  12.     )
  13. );
  1. <select id="productId" name="productId">
  2.     <option value="@">Please, choose one..</option>
  3.     <option value="101">Tomato</option>
  4.     <option value="102">Lettuce</option>
  5.     <option value="103">Beans</option>
  6. </select>

用Volt实现如上的代码：

Volt syntax for above example:

  1. {# Creating a Select Tag with an empty option with default text #}
  2. {{ select('productId', products, 'using': ['id', 'name'],
  3.     'useEmpty': true, 'emptyText': 'Please, choose one...', 'emptyValue': '@') }}

HTML属性赋值Assigning HTML attributes

所有的视图助手接受数组作为其第一个参数，可以包含额外的HTML属性用于元素的生成。

All the helpers accept an array as their first parameter which can contain additional HTML attributes for the element generated.

  1. <?php $this->tag->textField(
  2.     array(
  3.         "price",
  4.         "size"        => 20,
  5.         "maxlength"   => 30,
  6.         "placeholder" => "Enter a price",
  7.     )
  8. ) ?>

使用Volt如下：

or using Volt:

  1. {{ text_field("price", "size": 20, "maxlength": 30, "placeholder": "Enter a price") }}

产生的html如下：

The following HTML is generated:

  1. <input type="text" name="price" id="price" size="20" maxlength="30"
  2.     placeholder="Enter a price" />

设置视图助手值Setting Helper Values

控制器中视图助手From Controllers

在MVC框架为表单元素在视图中设置特定的默认值是一个好的编程原则。可以直接从控制器使用Phalcon\Tag::setDefault()设置这些值。这个助手预先设置了所有在视图中其他助手的默认值。如果任何助手中名称匹配预加载的默认值,则将使用这个默认值,除非是在视图中直接指定一个默认值。

It is a good programming principle for MVC frameworks to set specific values for form elements in the view. You can set those values directly from the controller using Phalcon\Tag::setDefault(). This helper preloads a value for any helpers present in the view. If any helper in the view has a name that matches the preloaded value, it will use it, unless a value is directly assigned on the helper in the view.

  1. <?php
  3. use Phalcon\Mvc\Controller;
  5. class ProductsController extends Controller
  6. {
  8.     public function indexAction()
  9.     {
  10.         $this->tag->setDefault("color", "Blue");
  11.     }
  13. }

在视图中，selectStatic助手匹配的值将会使用默认值，在这个例子中就是color

At the view, a selectStatic helper matches the same index used to preset the value. In this case “color”:

  1. <?php
  3. echo $this->tag->selectStatic(
  4.     array(
  5.         "color",
  6.         array(
  7.             "Yellow" => "Yellow",
  8.             "Blue"   => "Blue",
  9.             "Red"    => "Red"
  10.         )
  11.     )
  12. );

将会产生如下”Blue”为选中状态的默认值：

This will generate the following select tag with the value “Blue” selected:

  1. <select id="color" name="color">
  2.     <option value="Yellow">Yellow</option>
  3.     <option value="Blue" selected="selected">Blue</option>
  4.     <option value="Red">Red</option>
  5. </select>

请求中的视图助手From the Request

:doc:`Phalcon\Tag <../api/Phalcon_Tag>`提供一个特殊功能，在请求的时候视图助手提供了简便的验证提示信息并且不会丢失已经输入的信息。

A special feature that the Phalcon\Tag helpers have is that they keep the values of form helpers between requests. This way you can easily show validation messages without losing entered data.

直接设置值Specifying values directly

视图助手都有”value”属性。可以直接设置视图助手的值。如果直接设置了值，则将忽略setDefault()设置的值以及请求过来的值。

Every form helper supports the parameter “value”. With it you can specify a value for the helper directly. When this parameter is present, any preset value using setDefault() or via request will be ignored.

动态设置文档标题Changing dynamically the Document Title

:doc:`Phalcon\Tag <../api/Phalcon_Tag>`提供了在控制器中动态改变文档标题的功能。

Phalcon\Tag offers helpers to change dynamically the document title from the controller. The following example demonstrates just that:

  1. <?php
  3. use Phalcon\Mvc\Controller;
  5. class PostsController extends Controller
  6. {
  8.     public function initialize()
  9.     {
  10.         $this->tag->setTitle("Your Website");
  11.     }
  13.     public function indexAction()
  14.     {
  15.         $this->tag->prependTitle("Index of Posts - ");
  16.     }
  18. }
  1. <html>
  2.     <head>
  3.         <?php echo $this->tag->getTitle(); ?>
  4.     </head>
  5.     <body>
  7.     </body>
  8. </html>

将会产生如下代码：

The following HTML will generated:

  1. <html>
  2.     <head>
  3.         <title>Index of Posts - Your Website</title>
  4.     </head>
  5.       <body>
  7.       </body>
  8. </html>

静态内容助手Static Content Helpers

:doc:`Phalcon\Tag <../api/Phalcon_Tag>`提供了产生script, link 或者 img的标签。帮助我们快速产生代码。

Phalcon\Tag also provide helpers to generate tags such as script, link or img. They aid in quick and easy generation of the static resources of your application

图片Images

  1. <?php
  3. // Generate <img src="/your-app/img/hello.gif">
  4. echo $this->tag->image("img/hello.gif");
  6. // Generate <img alt="alternative text" src="/your-app/img/hello.gif">
  7. echo $this->tag->image(
  8.     array(
  9.        "img/hello.gif",
  10.        "alt" => "alternative text"
  11.     )
  12. );

Volt 语法:

Volt syntax:

  1. {# Generate <img src="/your-app/img/hello.gif"> #}
  2. {{ image("img/hello.gif") }}
  4. {# Generate <img alt="alternative text" src="/your-app/img/hello.gif"> #}
  5. {{ image("img/hello.gif", "alt": "alternative text") }}

css样式Stylesheets

  1. <?php
  3. // Generate <link rel="stylesheet" href="http://fonts.googleapis.com/css?family=Rosario" type="text/css">
  4. echo $this->tag->stylesheetLink("http://fonts.googleapis.com/css?family=Rosario", false);
  6. // Generate <link rel="stylesheet" href="/your-app/css/styles.css" type="text/css">
  7. echo $this->tag->stylesheetLink("css/styles.css");

Volt 语法:

Volt syntax:

  1. {# Generate <link rel="stylesheet" href="http://fonts.googleapis.com/css?family=Rosario" type="text/css"> #}
  2. {{ stylesheet_link("http://fonts.googleapis.com/css?family=Rosario", false) }}
  4. {# Generate <link rel="stylesheet" href="/your-app/css/styles.css" type="text/css"> #}
  5. {{ stylesheet_link("css/styles.css") }}

Javascript

  1. <?php
  3. // Generate <script src="http://localhost/javascript/jquery.min.js" type="text/javascript"></script>
  4. echo $this->tag->javascriptInclude("http://localhost/javascript/jquery.min.js", false);
  6. // Generate <script src="/your-app/javascript/jquery.min.js" type="text/javascript"></script>
  7. echo $this->tag->javascriptInclude("javascript/jquery.min.js");

Volt 语法:

Volt syntax:

  1. {# Generate <script src="http://localhost/javascript/jquery.min.js" type="text/javascript"></script> #}
  2. {{ javascript_include("http://localhost/javascript/jquery.min.js", false) }}
  4. {# Generate <script src="/your-app/javascript/jquery.min.js" type="text/javascript"></script> #}
  5. {{ javascript_include("javascript/jquery.min.js") }}

HTML5 对象 HTML5 elements - generic HTML helper

Phalcon 提供了生成任何HTML元素的标签助手。由开发人员为视图助手生成一个有效的HTML元素名。

Phalcon offers a generic HTML helper that allows the generation of any kind of HTML element. It is up to the developer to produce a valid HTML element name to the helper.

  1. <?php
  3. // Generate
  4. // <canvas id="canvas1" width="300" class="cnvclass">
  5. // This is my canvas
  6. // </canvas>
  7. echo $this->tag->tagHtml("canvas", array("id" => "canvas1", "width" => "300", "class" => "cnvclass"), false, true, true);
  8. echo "This is my canvas";
  9. echo $this->tag->tagHtmlClose("canvas");

Volt 语法:

Volt syntax:

  1. {# Generate
  2. <canvas id="canvas1" width="300" class="cnvclass">
  3. This is my canvas
  4. </canvas> #}
  5. {{ tag_html("canvas", ["id": "canvas1", width": "300", "class": "cnvclass"], false, true, true) }}
  6.     This is my canvas
  7. {{ tag_html_close("canvas") }}

标签服务Tag Service

:doc:`Phalcon\Tag <../api/Phalcon_Tag>`通过使用’tag‘服务来生效。这就意味着在应用中任何包含服务应用的地方可以使用它。

Phalcon\Tag is available via the ‘tag’ service, this means you can access it from any part of the application where the services container is located:

  1. <?php echo $this->tag->linkTo('pages/about', 'About') ?>

可以方便的定义一个新的视图助手去替换服务容器中的’tag‘服务：

You can easily add new helpers to a custom component replacing the service ‘tag’ in the services container:

  1. <?php
  3. use Phalcon\Tag;
  5. class MyTags extends Tag
  6. {
  7.     //...
  9.     //Create a new helper
  10.     static public function myAmazingHelper($parameters)
  11.     {
  12.         //...
  13.     }
  15.     //Override an existing method
  16.     static public function textField($parameters)
  17.     {
  18.         //...
  19.     }
  20. }

然后替换’tag‘服务定义：

Then change the definition of the service ‘tag’:

  1. <?php
  3. $di['tag'] = function() {
  4.     return new MyTags();
  5. };

创建助手Creating your own helpers

可以方便的创建助手，第一步，在controller和models的同级目录创建一个以视图助手名称命名的文件，在文件中创建一个``MyTags.php``文件。如``/app/customhelpers/MyTags.php``目录结构。在``MyTags.php``文件中我们扩展 Phalcon\Tag 并实现自己的代码。下面就是自定义助手的例子：

You can easily create your own helpers. First, start by creating a new folder within the same directory as your controllers and models. Give it a title that is relative to what you are creating. For our example here, we can call it “customhelpers”. Next we will create a new file titled MyTags.php within this new directory. At this point, we have a structure that looks similar to : /app/customhelpers/MyTags.php. In MyTags.php, we will extend the Phalcon\Tag and implement your own helper. Below is a simple example of a custom helper:

  1. <?php
  3. use Phalcon\Tag;
  5. class MyTags extends Tag
  6. {
  8.     /**
  9.      * Generates a widget to show a HTML5 audio tag
  10.      *
  11.      * @param array
  12.      * @return string
  13.      */
  14.     static public function audioField($parameters)
  15.     {
  17.         // Converting parameters to array if it is not
  18.         if (!is_array($parameters)) {
  19.             $parameters = array($parameters);
  20.         }
  22.         // Determining attributes "id" and "name"
  23.         if (!isset($parameters[0])) {
  24.             $parameters[0] = $parameters["id"];
  25.         }
  27.         $id = $parameters[0];
  28.         if (!isset($parameters["name"])) {
  29.             $parameters["name"] = $id;
  30.         } else {
  31.             if (!$parameters["name"]) {
  32.                 $parameters["name"] = $id;
  33.             }
  34.         }
  36.         // Determining widget value,
  37.         // \Phalcon\Tag::setDefault() allows to set the widget value
  38.         if (isset($parameters["value"])) {
  39.             $value = $parameters["value"];
  40.             unset($parameters["value"]);
  41.         } else {
  42.             $value = self::getValue($id);
  43.         }
  45.         // Generate the tag code
  46.         $code = '<audio id="'.$id.'" value="'.$value.'" ';
  47.         foreach ($parameters as $key => $attributeValue) {
  48.             if (!is_integer($key)) {
  49.                 $code.= $key.'="'.$attributeValue.'" ';
  50.             }
  51.         }
  52.         $code.=" />";
  54.         return $code;
  55.     }
  57. }

创建完自定义助手后，我们需要在index.php中自动加载上我们的助手目录。

After creating our custom helper, we will autoload the new directory that contains our helper class from our “index.php” located in the public directory.

  1. <?php
  3. use Phalcon\Loader;
  4. use Phalcon\Mvc\Application;
  5. use Phalcon\DI\FactoryDefault();
  6. use Phalcon\Exception as PhalconException;
  8. try {
  10.     $loader = new Loader();
  11.     $loader->registerDirs(array(
  12.         '../app/controllers',
  13.         '../app/models',
  14.         '../app/customhelpers' // Add the new helpers folder
  15.     ))->register();
  17.     $di = new FactoryDefault();
  19.     // Assign our new tag a definition so we can call it
  20.     $di->set('MyTags',  function()
  21.     {
  22.         return new MyTags();
  23.     });
  25.     $application = new Application($di);
  26.     echo $application->handle()->getContent();
  28.     } catch(PhalconException $e) {
  29.          echo "PhalconException: ", $e->getMessage();
  30.     }
  32. }

现在我们就可以视图中使用我们的新视图助手了：

Now you are ready to use your new helper within your views:

  1. <body>
  3.     <?php
  5.     echo MyTags::audioField(array(
  6.         'name'  => 'test',
  7.         'id'    => 'audio_test',
  8.         'src'   => '/path/to/audio.mp3'
  9.         ));
  10.     ?>
  12. </body>

下面我们将介绍一个非常快的PHP模板引擎 Volt ,在里面我们使用和Phalcon\Tag相同的语法。

In next chapter, we’ll talk about Volt a faster template engine for PHP, where you can use a more friendly syntax for using helpers provided by Phalcon\Tag.