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

最后更新于:2018-09-01 07:08:51

因为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 中你将得到更多关于视图助手的友好的提示。