视图助手 (Tags)（View Helpers (Tags)）

视图助手 (Tags)（View Helpers (Tags)）

因为HTML标签的命名方式和很多标签属性，让书写HTML标签变成一项超级沉闷的工作。Phalcon提供 Phalcon\Tag 类来处理这些复杂而无趣的事情。

这个简单的指导不是一个完整的关于视图助手的文档，请查看 Phalcon\Tag 以获得视图助手的完整说明。

文档类型（Document Type of Content）

Phalcon 提供 Phalcon\Tag::setDoctype() 方法可以设置输出内容的文档类型。此类型设置可能被其他的tag方法影响。

常量	对应的文档类型
HTML32	HTML 3.2
HTML401_STRICT	HTML 4.01 严格模式
HTML401_TRANSITIONAL	HTML 4.01 过渡模式
HTML401_FRAMESET	HTML 4.01 Frameset
HTML5	HTML 5
XHTML10_STRICT	XHTML 1.0 严格模式
XHTML10_TRANSITIONAL	XHTML 1.0 过渡模式
XHTML10_FRAMESET	XHTML 1.0 Frameset
XHTML11	XHTML 1.1
XHTML20	XHTML 2.0
XHTML5	XHTML 5

设置文档类型:

<?php
use Phalcon\Tag;
$this->tag->setDoctype(Tag::HTML401_STRICT);
?>

获取文档类型:

<?= $this->tag->getDoctype() ?>
<html>
<!-- your HTML code -->
</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 语法:

{{ get_doctype() }}
<html>
<!-- your HTML code -->
</html>

生成链接（Generating Links）

每一个普通的web应用都需要生成超链接去让我们在不同的页面之间进行导航。我们可以使用如下的方法创建指向我们站内的超链接：

<!-- 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生成超链接的例子:

<!-- 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") }}

创建表单（Creating Forms）

在Web应用中，表单是获取用户输入的重要工具，下面的例子显示了使用视图助手(tag)如何去生成一个简单的form表单。

<!-- 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:

<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生成表单:

<!-- 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也提供了 form builder 类去以面向对象的风格去生成这样的表单。

使用助手生成表单控件（Helpers to Generate Form Elements）

Phalcon 提供了一系列的方法去生成例如文本域(text)，按钮(button)和其他的一些form表单元素。提供给所有方法(helper)的第一个参数都是需要创建的表单元素的名称(name属性)。当提交表单的时候，这个名称将被和form表单数据一起传输。在控制器中，你可以使用request对象 ($this->request) 的 getPost() 和 getQuery() 方法结合之前定义的名字(name属性)来获取到这些值。

<?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 的语法:

{{ 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") }}

使用选择框（Making Select Boxes）

生成选择框(select)很简单,特别是当你已经把相关的数据存储在了PHP的关联数组中。生成select的方法是 Phalcon\Tag::select() 和 Phalcon\Tag::selectStatic() 。方法 Phalcon\Tag::select() 与 Phalcon\Mvc\Model 一起使用会更好。当然 Phalcon\Tag::selectStatic() 也可以和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代码将会被生成:

<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>

你可以添加一个空的选项(option)到被生成的HTML页面中:

<?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如下:

<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
$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" => "@",
    ]
);

<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的语法生成以上的select选择框

{# 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 属性（Assigning HTML attributes）

所有的方法的第一个参数可以是一个数组，这个数组包含了这个被生成的HTML元素额外的属性。

<?php $this->tag->textField(
    [
        "price",
        "size"        => 20,
        "maxlength"   => 30,
        "placeholder" => "Enter a price",
    ]
) ?>

Volt语法:

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

以下的HTML代码将被生成。

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

设置助手的值（Setting Helper Values）

通过控制器（From Controllers）

使用MVC框架编程时的一个好习惯是给form元素在视图中设定一个明确的值。你可以直接使用 Phalcon\Tag::setDefault() 在控制器中设置这个值。这个方法为所有的视图助手的方法预先设定了一个值，如果任意一个视图助手方法有一个和此预设值相匹配的名字，这个值将会被使用，除非那个视图方法明确的指定了这个值。

<?php
use Phalcon\Mvc\Controller;
class ProductsController extends Controller
{
    public function indexAction()
    {
        $this->tag->setDefault("color", "Blue");
    }
}

例如，在视图中一个选择框助手方法(select helper)匹配到了这个之前被预设的值”color”

<?php
echo $this->tag->selectStatic(
    [
        "color",
        [
            "Yellow" => "Yellow",
            "Blue"   => "Blue",
            "Red"    => "Red",
        ]
    ]
);

当这个选择框被生成的时候，”Blue”将被默认选中。

<select id="color" name="color">
    <option value="Yellow">Yellow</option>
    <option value="Blue" selected="selected">Blue</option>
    <option value="Red">Red</option>
</select>

通过请求（From the Request）

Phalcon\Tag 助手有一个特性，它可以在用户请求的时候保持表单的值。这个特性让你在不损失任何输入数据的情况下显示一些确认信息。

直接设置值（Specifying values directly）

所有的表单方法都支持参数”value”。你可以直接设置一个明确的值给表单方法。当这个值被明确设定的时候，任何通过 setDefault() 或者通过请求(request) 所设置的值将被直接忽略。

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

Phalcon\Tag 类提供了一些方法，让我们可以在控制器中动态地设置HTML文档的标题(title)。

<?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 - ");
    }
}

<html>
    <head>
        <?php echo $this->tag->getTitle(); ?>
    </head>
    <body>
    </body>
</html>

以下的HTML代码将会被生成:

<html>
    <head>
        <title>Index of Posts - Your Website</title>
    </head>
    <body>
    </body>
</html>

静态内容助手（Static Content Helpers）

Phalcon\Tag 也提供一些其他的方法去生成一些其他的标签，例如脚本(script),超链接(link)或者图片(img)。它可以帮助你很快的生成一些你应用中的静态资源

图片（Images）

<?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 语法:

{# 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") }}

样式表（Stylesheets）

<?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 语法:

{# 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
// 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 语法：

{# 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 对象（HTML5 elements - generic HTML helper）

Phalcon 提供了一个通用的方法去生成任何HTML的元素。在这个方法中，需要开发者将有效的HTML元素标签传给此方法。

<?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 语法：

{# 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") }}

标签服务（Tag Service）

Phalcon\Tag 类可以通过 ‘tag’ 服务来使用，这意味着你可以在服务容器被加载的任何地方访问到它。

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

在服务容器中我们可以很容易的添加一个新的组件去替换’tag’组件。

<?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
$di["tag"] = function () {
    return new MyTags();
};

创建助手（Creating your own helpers）

你可以简单地创建你自己的方法。首先，在你的控制器和模型的同级目录下创建一个新的文件夹，给此文件夹起一个和它功能相关的名字。在这里，叫它”customhelpers”好了。接下来我们在此文件夹下创建一个新的文件命名为 MyTags.php 这时，我们有一个类似于 /app/customhelpers/MyTags.php 的结构，我们将扩展(extend) Phalcon\Tag 并且实现(implement)这个类。下面是一个自定义的助手(helper)类：

<?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;
    }
}

在我们创建了自定义的助手(helper)类之后，我们要在我们的public目录下的”index.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();
}

现在，你就可以在你的视图中使用你的新助手类了。

<body>
    <?php
    echo MyTags::audioField(
        [
            "name" => "test",
            "id"   => "audio_test",
            "src"  => "/path/to/audio.mp3",
        ]
    );
    ?>
</body>

在下一节中，我们将讨论关于 Volt 的内容，它是PHP的一个速度很快的模板引擎，在 Phalcon\Tag 中你将得到更多关于视图助手的友好的提示。