Volt: Template Engine

Volt: Template Engine

Volt 是一个用C为PHP编写的超快的并且对设计师友好的模板语言。Volt 提供一组辅助工具有助于你以一种更简单的的方式编写视图（Views）。同时，Volt与Phalcon的其他组件高度集成在一起，就像你在应用中单独使用Volt一样。

Volt is an ultra-fast and designer friendly templating language written in C for PHP. It provides you a set of helpers to write views in an easy way. Volt is highly integrated with other components of Phalcon, just as you can use it as a stand-alone component in your applications.

Volt受 `Armin Ronacher`_开发的Jinja_启发而来开发的。使用过Jinja_会比较熟悉类似的语法。为了方便Phalcon开发者Volt的增加很多的语法特性。

Volt is inspired by Jinja, originally created by Armin Ronacher. Therefore many developers will be in familiar territory using the same syntax they have been using with similar template engines. Volt’s syntax and features have been enhanced with more elements and of course with the performance that developers have been accustomed to while working with Phalcon.

简介Introduction

Volt视图会编译为纯php代码。所以节省编写php代码的时间。

Volt views are compiled to pure PHP code, so basically they save the effort of writing PHP code manually:

{# app/views/products/show.volt #}
{% block last_products %}
{% for product in products %}
    * Name: {{ product.name|e }}
    {% if product.status == "Active" %}
       Price: {{ product.price + product.taxes/100 }}
    {% endif  %}
{% endfor  %}
{% endblock %}

启用 Vlot Activating Volt

像是其他，模板引擎一样。可以在视图组件注册模板引擎，使用新的扩展名或者是默认的.phtml:

As other template engines, you may register Volt in the view component, using a new extension or reusing the standard .phtml:

<?php
use Phalcon\Mvc\View;
//Registering Volt as template engine
$di->set('view', function() {
    $view = new View();
    $view->setViewsDir('../app/views/');
    $view->registerEngines(array(
        ".volt" => 'Phalcon\Mvc\View\Engine\Volt'
    ));
    return $view;
});

使用 ”.phtml” 扩展名:

Use the standard ”.phtml” extension:

<?php
$view->registerEngines(array(
    ".phtml" => 'Phalcon\Mvc\View\Engine\Volt'
));

基本用法Basic Usage

视图文件由volt代码，php和html组成。一些特殊分隔符被用于volt代码。{% … %} 被用于循环或者复制语句。{{ … }}被用于输出计算结果。

A view consists of Volt code, PHP and HTML. A set of special delimiters is available to enter into Volt mode. {% … %} is used to execute statements such as for-loops or assign values and {{ … }}, prints the result of an expression to the template.

下面是一个简单的例子

Below is a minimal template that illustrates a few basics:

{# app/views/posts/show.phtml #}
<!DOCTYPE html>
<html>
    <head>
        <title>{{ title }} - An example blog</title>
    </head>
    <body>
        {% if show_navigation %}
            <ul id="navigation">
            {% for item in menu %}
                <li><a href="{{ item.href }}">{{ item.caption }}</a></li>
            {% endfor %}
            </ul>
        {% endif %}
        <h1>{{ post.title }}</h1>
        <div class="content">
            {{ post.content }}
        </div>
    </body>
</html>

使用Phalcon\Mvc\View 可以由控制器向视图传递值。在上面的例子中，三个变量 title, menu and post被传递到视图。

Using Phalcon\Mvc\View you can pass variables from the controller to the views. In the above example, three variables were passed to the view: title, menu and post:

<?php
use Phalcon\Mvc\Controller;
class PostsController extends Controller
{
    public function showAction()
    {
        $post = Post::findFirst();
        $this->view->title           = $post->title;
        $this->view->post            = $post;
        $this->view->menu            = Menu::find();
        $this->view->show_navigation = true;
    }
}

变量 Variables

对象的属性可以用foo.bar来访问。数据可以用 foo[‘bar’]来访问。

Object variables may have attributes which can be accessed using the syntax: foo.bar. If you are passing arrays, you have to use the square bracket syntax: foo[‘bar’]

{{ post.title }} {# for $post->title #}
{{ post['title'] }} {# for $post['title'] #}

过滤器Filters

变量可以用过滤器进行格式化或者是修改。管道操作符 | 被用来调用过滤器：

Variables can be formatted or modified using filters. The pipe operator | is used to apply filters to variables:

{{ post.title|e }}
{{ post.content|striptags }}
{{ name|capitalize|trim }}

下面是Volt内置的过滤类型：

The following is the list of available built-in filters in Volt:

Filter	Description
e	Applies Phalcon\Escaper->escapeHtml to the value
escape	Applies Phalcon\Escaper->escapeHtml to the value
escape_css	Applies Phalcon\Escaper->escapeCss to the value
escape_js	Applies Phalcon\Escaper->escapeJs to the value
escape_attr	Applies Phalcon\Escaper->escapeHtmlAttr to the value
trim	Applies the trim PHP function to the value. Removing extra spaces
left_trim	Applies the ltrim PHP function to the value. Removing extra spaces
right_trim	Applies the rtrim PHP function to the value. Removing extra spaces
striptags	Applies the striptags PHP function to the value. Removing HTML tags
slashes	Applies the slashes PHP function to the value. Escaping values
stripslashes	Applies the stripslashes PHP function to the value. Removing escaped quotes
capitalize	Capitalizes a string by applying the ucwords PHP function to the value
lower	Change the case of a string to lowercase
upper	Change the case of a string to uppercase
length	Counts the string length or how many items are in an array or object
nl2br	Changes newlines \n by line breaks (<br />). Uses the PHP function nl2br
sort	Sorts an array using the PHP function asort
keys	Returns the array keys using array_keys
join	Joins the array parts using a separator join
format	Formats a string using sprintf.
json_encode	Converts a value into its JSON representation
json_decode	Converts a value from its JSON representation to a PHP representation
abs	Applies the abs PHP function to a value.
url_encode	Applies the urlencode PHP function to the value
default	Sets a default value in case that the evaluated expression is empty (is not set or evaluates to a falsy value)
convert_encoding	Converts a string from one charset to another

例子 Examples:

{# e or escape filter #}
{{ "<h1>Hello<h1>"|e }}
{{ "<h1>Hello<h1>"|escape }}
{# trim filter #}
{{ "   hello   "|trim }}
{# striptags filter #}
{{ "<h1>Hello<h1>"|striptags }}
{# slashes filter #}
{{ "'this is a string'"|slashes }}
{# stripslashes filter #}
{{ "\'this is a string\'"|stripslashes }}
{# capitalize filter #}
{{ "hello"|capitalize }}
{# lower filter #}
{{ "HELLO"|lower }}
{# upper filter #}
{{ "hello"|upper }}
{# length filter #}
{{ "robots"|length }}
{{ [1, 2, 3]|length }}
{# nl2br filter #}
{{ "some\ntext"|nl2br }}
{# sort filter #}
{% set sorted=[3, 1, 2]|sort %}
{# keys filter #}
{% set keys=['first': 1, 'second': 2, 'third': 3]|keys %}
{# join filter #}
{% "a".."z"|join(",") %}
{# format filter #}
{% "My real name is %s"|format(name) %}
{# json_encode filter #}
{% robots|json_encode %}
{# json_decode filter #}
{% set decoded='{"one":1,"two":2,"three":3}'|json_decode %}
{# url_encode filter #}
{{ post.permanent_link|url_encode }}
{# convert_encoding filter #}
{{ "désolé"|convert_encoding('utf8', 'latin1') }}

注释Comments

模板中可以使用{# … #}注释代码。所有在其中的代码将被忽略：

Comments may also be added to a template using the {# … #} delimiters. All text inside them is just ignored in the final output:

{# note: this is a comment
    {% set price = 100; %}
#}

流程控制列表List of Control Structures

Volt在模板中提供了基础但是强大的流程控制结构。

Volt provides a set of basic but powerful control structures for use in templates:

For

按序循环输出序列。下面的例子演示了如何循环输出”robots”：

Loop over each item in a sequence. The following example shows how to traverse a set of “robots” and print his/her name:

<h1>Robots</h1>
<ul>
{% for robot in robots %}
  <li>{{ robot.name|e }}</li>
{% endfor %}
</ul>

循环可以嵌套：

for-loops can also be nested:

<h1>Robots</h1>
{% for robot in robots %}
  {% for part in robot.parts %}
  Robot: {{ robot.name|e }} Part: {{ part.name|e }} <br/>
  {% endfor %}
{% endfor %}

可以像是php那样获取循环的key值

You can get the element “keys” as in the PHP counterpart using the following syntax:

{% set numbers = ['one': 1, 'two': 2, 'three': 3] %}
{% for name, value in numbers %}
  Name: {{ name }} Value: {{ value }}
{% endfor %}

可以使用if语句：

An “if” evaluation can be optionally set:

{% set numbers = ['one': 1, 'two': 2, 'three': 3] %}
{% for value in numbers if value < 2 %}
  Value: {{ value }}
{% endfor %}
{% for name, value in numbers if name != 'two' %}
  Name: {{ name }} Value: {{ value }}
{% endfor %}

如果’else’定义在for内部，当条件循环为零的时候就会执行else条件：

If an ‘else’ is defined inside the ‘for’, it will be executed if the expression in the iterator result in zero iterations:

<h1>Robots</h1>
{% for robot in robots %}
    Robot: {{ robot.name|e }} Part: {{ part.name|e }} <br/>
{% else %}
    There are no robots to show
{% endfor %}

另一种写法：

Alternative syntax:

<h1>Robots</h1>
{% for robot in robots %}
    Robot: {{ robot.name|e }} Part: {{ part.name|e }} <br/>
{% elsefor %}
    There are no robots to show
{% endfor %}

循环控制Loop Controls

break和continue语句用户退出或者强制进入下一次循环：

The ‘break’ and ‘continue’ statements can be used to exit from a loop or force an iteration in the current block:

{# skip the even robots #}
{% for index, robot in robots %}
    {% if index is even %}
        {% continue %}
    {% endif %}
    ...
{% endfor %}

{# exit the foreach on the first even robot #}
{% for index, robot in robots %}
    {% if index is even %}
        {% break %}
    {% endif %}
    ...
{% endfor %}

If

就像在PHP中一样，if语句检查表达式的值为true还是false:

As PHP, an “if” statement checks if an expression is evaluated as true or false:

<h1>Cyborg Robots</h1>
<ul>
{% for robot in robots %}
  {% if robot.type == "cyborg" %}
  <li>{{ robot.name|e }}</li>
  {% endif %}
{% endfor %}
</ul>

同样支持else:

The else clause is also supported:

<h1>Robots</h1>
<ul>
{% for robot in robots %}
  {% if robot.type == "cyborg" %}
  <li>{{ robot.name|e }}</li>
  {% else %}
  <li>{{ robot.name|e }} (not a cyborg)</li>
  {% endif %}
{% endfor %}
</ul>

elseif控制同样可以和if一起使用来模拟switch操作：

The ‘elseif’ control flow structure can be used together with if to emulate a ‘switch’ block:

{% if robot.type == "cyborg" %}
    Robot is a cyborg
{% elseif robot.type == "virtual" %}
    Robot is virtual
{% elseif robot.type == "mechanical" %}
    Robot is mechanical
{% endif %}

循环上下文Loop Context

在for循环中提供了特殊的变量提示当前循环的信息

A special variable is available inside ‘for’ loops providing you information about

Variable	Description
loop.index	The current iteration of the loop. (1 indexed)
loop.index0	The current iteration of the loop. (0 indexed)
loop.revindex	The number of iterations from the end of the loop (1 indexed)
loop.revindex0	The number of iterations from the end of the loop (0 indexed)
loop.first	True if in the first iteration.
loop.last	True if in the last iteration.
loop.length	The number of items to iterate

{% for robot in robots %}
    {% if loop.first %}
        <table>
        <tr>
            <th>#</th>
            <th>Id</th>
            <th>Name</th>
        </tr>
    {% endif %}
        <tr>
            <td>{{ loop.index }}</td>
            <td>{{ robot.id }}</td>
            <td>{{ robot.name }}</td>
        </tr>
    {% if loop.last %}
        </table>
    {% endif %}
{% endfor %}

赋值Assignments

在模板中变量可以用set重新赋值：

Variables may be changed in a template using the instruction “set”:

{% set fruits = ['Apple', 'Banana', 'Orange'] %}
{% set name = robot.name %}

同样可以使用连续赋值：

Multiple assignments are allowed in the same instruction:

{% set fruits = ['Apple', 'Banana', 'Orange'], name = robot.name, active = true %}

同时也允许使用复合赋值：

Additionally, you can use compound assignment operators:

{% set price += 100.00 %}
{% set age *= 5 %}

下面是操作符列表：

The following operators are available:

Operator	Description
=	Standard Assignment
+=	Addition assignment
-=	Subtraction assignment
*=	Multiplication assignment
/=	Division assignment

表达式Expressions

Volt提供基础的表达式支持，包括字面值和常见的操作符。

Volt provides a basic set of expression support, including literals and common operators.

表达式可以被执行和使用 ‘{{‘ 和 ‘}}’输出：

A expression can be evaluated and printed using the ‘{{‘ and ‘}}’ delimiters:

{{ (1 + 1) * 2 }}

如果表达式仅需要被执行而不需要输出可以使用do

If an expression needs to be evaluated without be printed the ‘do’ statement can be used:

{% do (1 + 1) * 2 %}

字面值Literals

提供下面的字面值支持：

The following literals are supported:

Filter	Description
“this is a string”	Text between double quotes or single quotes are handled as strings
100.25	Numbers with a decimal part are handled as doubles/floats
100	Numbers without a decimal part are handled as integers
false	Constant “false” is the boolean false value
true	Constant “true” is the boolean true value
null	Constant “null” is the Null value

数组Arrays

使用PHP 5.3 or >= 5.4可以使用方括号定义一个数组：

Whether you’re using PHP 5.3 or >= 5.4 you can create arrays by enclosing a list of values in square brackets:

{# Simple array #}
{{ ['Apple', 'Banana', 'Orange'] }}
{# Other simple array #}
{{ ['Apple', 1, 2.5, false, null] }}
{# Multi-Dimensional array #}
{{ [[1, 2], [3, 4], [5, 6]] }}
{# Hash-style array #}
{{ ['first': 1, 'second': 4/2, 'third': '3'] }}

大括号同样可以被用于定义数组或者哈希表：

Curly braces also can be used to define arrays or hashes:

{% set myArray = {'Apple', 'Banana', 'Orange'} %}
{% set myHash  = {'first': 1, 'second': 4/2, 'third': '3'} %}

算术运算Math

可以在模板中使用下面的操作符：

You may make calculations in templates using the following operators:

Operator	Description
+	Perform an adding operation. {{ 2 + 3 }} returns 5
-	Perform a substraction operation {{ 2 - 3 }} returns -1
	Perform a multiplication operation {{ 2 3 }} returns 6
/	Perform a division operation {{ 10 / 2 }} returns 5
%	Calculate the remainder of an integer division {{ 10 % 3 }} returns 1

比较运算Comparisons

可以在模板中使用下面的操作符：

The following comparison operators are available:

Operator	Description
==	Check whether both operands are equal
!=	Check whether both operands aren’t equal
<>	Check whether both operands aren’t equal
>	Check whether left operand is greater than right operand
<	Check whether left operand is less than right operand
<=	Check whether left operand is less or equal than right operand
>=	Check whether left operand is greater or equal than right operand
===	Check whether both operands are identical
!==	Check whether both operands aren’t identical

逻辑运算Logic

在if中可以混合使用逻辑运算符去做表达式判断：

Logic operators are useful in the “if” expression evaluation to combine multiple tests:

Operator	Description
or	Return true if the left or right operand is evaluated as true
and	Return true if both left and right operands are evaluated as true
not	Negates an expression
( expr )	Parenthesis groups expressions

其他操作Other Operators

其他一些操作符如下：

Additional operators seen the following operators are available:

Operator	Description
~	Concatenates both operands {{ “hello ” ~ “world” }}
\|	Applies a filter in the right operand to the left {{ “hello”\|uppercase }}
..	Creates a range {{ ‘a’..’z’ }} {{ 1..10 }}
is	Same as == (equals), also performs tests
in	To check if an expression is contained into other expressions if “a” in “abc”
is not	Same as != (not equals)
‘a’ ? ‘b’ : ‘c’	Ternary operator. The same as the PHP ternary operator
++	Increments a value
–	Decrements a value

下面是如何使用的一个例子：

The following example shows how to use operators:

{% set robots = ['Voltron', 'Astro Boy', 'Terminator', 'C3PO'] %}
{% for index in 0..robots|length %}
    {% if robots[index] is defined %}
        {{ "Name: " ~ robots[index] }}
    {% endif %}
{% endfor %}

测试运算Tests

Tests被用于检查变量是否有期望的值。is操作符被用于tests：

Tests can be used to test if a variable has a valid expected value. The operator “is” is used to perform the tests:

{% set robots = ['1': 'Voltron', '2': 'Astro Boy', '3': 'Terminator', '4': 'C3PO'] %}
{% for position, name in robots %}
    {% if position is odd %}
        {{ name }}
    {% endif %}
{% endfor %}

内置的tests检查如下：

The following built-in tests are available in Volt:

Test	Description
defined	Checks if a variable is defined (isset)
empty	Checks if a variable is empty
even	Checks if a numeric value is even
odd	Checks if a numeric value is odd
numeric	Checks if value is numeric
scalar	Checks if value is scalar (not an array or object)
iterable	Checks if a value is iterable. Can be traversed by a “for” statement
divisibleby	Checks if a value is divisible by other value
sameas	Checks if a value is identical to other value
type	Checks if a value is of the specified type

更多的例子：

More examples:

{% if robot is defined %}
    The robot variable is defined
{% endif %}
{% if robot is empty %}
    The robot is null or isn't defined
{% endif %}
{% for key, name in [1: 'Voltron', 2: 'Astroy Boy', 3: 'Bender'] %}
    {% if key is even %}
        {{ name }}
    {% endif %}
{% endfor %}
{% for key, name in [1: 'Voltron', 2: 'Astroy Boy', 3: 'Bender'] %}
    {% if key is odd %}
        {{ name }}
    {% endif %}
{% endfor %}
{% for key, name in [1: 'Voltron', 2: 'Astroy Boy', 'third': 'Bender'] %}
    {% if key is numeric %}
        {{ name }}
    {% endif %}
{% endfor %}
{% set robots = [1: 'Voltron', 2: 'Astroy Boy'] %}
{% if robots is iterable %}
    {% for robot in robots %}
        ...
    {% endfor %}
{% endif %}
{% set world = "hello" %}
{% if world is sameas("hello") %}
    {{ "it's hello" }}
{% endif %}
{% set external = false %}
{% if external is type('boolean') %}
    {{ "external is false or true" }}
{% endif %}

宏定义Macros

宏定义可以让我们在模板中重用逻辑。就像PHP函数一样，他们可以接受参数返回数值：

Macros can be used to reuse logic in a template, they act as PHP functions, can receive parameters and return values:

{%- macro related_bar(related_links) %}
    <ul>
        {%- for rellink in related_links %}
            <li><a href="{{ url(link.url) }}" title="{{ link.title|striptags }}">{{ link.text }}</a></li>
        {%- endfor %}
    </ul>
{%- endmacro %}
{# Print related links #}
{{ related_bar(links) }}
<div>This is the content</div>
{# Print related links again #}
{{ related_bar(links) }}

调用宏定义时候可以通过名称传递参数：

When calling macros, parameters can be passed by name:

{%- macro error_messages(message, field, type) %}
    <div>
        <span class="error-type">{{ type }}</span>
        <span class="error-field">{{ field }}</span>
        <span class="error-message">{{ message }}</span>
    </div>
{%- endmacro %}
{# Call the macro #}
{{ error_messages('type': 'Invalid', 'message': 'The name is invalid', 'field': 'name') }}

宏定义可以返回数值：

Macros can return values:

{%- macro my_input(name, class) %}
    {% return text_field(name, 'class': class) %}
{%- endmacro %}
{# Call the macro #}
{{ '<p>' ~ my_input('name', 'input-text') ~ '</p>' }}

可以接受可选参数：

And receive optional parameters:

{%- macro my_input(name, class="input-text") %}
    {% return text_field(name, 'class': class) %}
{%- endmacro %}
{# Call the macro #}
{{ '<p>' ~ my_input('name') ~ '</p>' }}
{{ '<p>' ~ my_input('name', 'input-text') ~ '</p>' }}

使用标签助手Using Tag Helpers

Volt和:doc:`Phalcon\Tag <tags>`整合度很高。所以在Volt模板中可以很方便的使用标签：

Volt is highly integrated with Phalcon\Tag, so it’s easy to use the helpers provided by that component in a Volt template:

{{ javascript_include("js/jquery.js") }}
{{ form('products/save', 'method': 'post') }}
    <label for="name">Name</label>
    {{ text_field("name", "size": 32) }}
    <label for="type">Type</label>
    {{ select("type", productTypes, 'using': ['id', 'name']) }}
    {{ submit_button('Send') }}
{{ end_form() }}

如下PHP代码将会被生成：

The following PHP is generated:

<?php echo Phalcon\Tag::javascriptInclude("js/jquery.js") ?>
<?php echo Phalcon\Tag::form(array('products/save', 'method' => 'post')); ?>
    <label for="name">Name</label>
    <?php echo Phalcon\Tag::textField(array('name', 'size' => 32)); ?>
    <label for="type">Type</label>
    <?php echo Phalcon\Tag::select(array('type', $productTypes, 'using' => array('id', 'name'))); ?>
    <?php echo Phalcon\Tag::submitButton('Send'); ?>
{{ end_form() }}

在Volt中调用Phalcon\Tag标签，需要调用函数的别名：

To call a Phalcon\Tag helper, you only need to call an uncamelized version of the method:

Method	Volt function
Phalcon\Tag::linkTo	link_to
Phalcon\Tag::textField	text_field
Phalcon\Tag::passwordField	password_field
Phalcon\Tag::hiddenField	hidden_field
Phalcon\Tag::fileField	file_field
Phalcon\Tag::checkField	check_field
Phalcon\Tag::radioField	radio_field
Phalcon\Tag::dateField	date_field
Phalcon\Tag::emailField	email_field
Phalcon\Tag::numberField	number_field
Phalcon\Tag::submitButton	submit_button
Phalcon\Tag::selectStatic	select_static
Phalcon\Tag::select	select
Phalcon\Tag::textArea	text_area
Phalcon\Tag::form	form
Phalcon\Tag::endForm	end_form
Phalcon\Tag::getTitle	get_title
Phalcon\Tag::stylesheetLink	stylesheet_link
Phalcon\Tag::javascriptInclude	javascript_include
Phalcon\Tag::image	image
Phalcon\Tag::friendlyTitle	friendly_title

函数 Functions

在volt中内置了如下的函数：

The following built-in functions are available in Volt:

Name	Description
content	Includes the content produced in a previous rendering stage
get_content	Same as ‘content’
partial	Dynamically loads a partial view in the current template
super	Render the contents of the parent block
time	Calls the PHP function with the same name
date	Calls the PHP function with the same name
dump	Calls the PHP function ‘var_dump’
version	Returns the current version of the framework
constant	Reads a PHP constant
url	Generate a URL using the ‘url’ service

视图集成 View Integration

Volt和:doc:`Phalcon\Mvc\View <views>`也集成在一起，可以使用视图分层和部分视图功能：

Also, Volt is integrated with Phalcon\Mvc\View, you can play with the view hierarchy and include partials as well:

{{ content() }}
<!-- Simple include of a partial -->
<div id="footer">{{ partial("partials/footer") }}</div>
<!-- Passing extra variables -->
<div id="footer">{{ partial("partials/footer", ['links': links]) }}</div>

局部模板在运行时被包含引入，Volt提供include。编译时将包含文件引入当前视图：

A partial is included in runtime, Volt also provides “include”, this compiles the content of a view and returns its contents as part of the view which was included:

{# Simple include of a partial #}
<div id="footer">{% include "partials/footer" %}</div>
{# Passing extra variables #}
<div id="footer">{% include "partials/footer" with ['links': links] %}</div>

包含Include

include将会增加volt性能，如果定义了包含文件的扩展名并且文件存在，则Volt会将被包含文件内联到父文件中。如果include 使用with传递了变量则不会内联：

‘include’ has a special behavior that will help us improve performance a bit when using Volt, if you specify the extension when including the file and it exists when the template is compiled, Volt can inline the contents of the template in the parent template where it’s included. Templates aren’t inlined if the ‘include’ have variables passed with ‘with’:

{# The contents of 'partials/footer.volt' is compiled and inlined #}
<div id="footer">{% include "partials/footer.volt" %}</div>

模版继承Template Inheritance

使用模板继承可以重用模板代码。基类模板中的*blocks*定义可以被子类模板重写。假设有如下模板文件：

With template inheritance you can create base templates that can be extended by others templates allowing to reuse code. A base template define blocks than can be overridden by a child template. Let’s pretend that we have the following base template:

{# templates/base.volt #}
<!DOCTYPE html>
<html>
    <head>
        {% block head %}
            <link rel="stylesheet" href="style.css" />
        {% endblock %}
        <title>{% block title %}{% endblock %} - My Webpage</title>
    </head>
    <body>
        <div id="content">{% block content %}{% endblock %}</div>
        <div id="footer">
            {% block footer %}&copy; Copyright 2012, All rights reserved.{% endblock %}
        </div>
    </body>
</html>

我们可以扩展基类模板进行替换：

From other template we could extend the base template replacing the blocks:

{% extends "templates/base.volt" %}
{% block title %}Index{% endblock %}
{% block head %}<style type="text/css">.important { color: #336699; }</style>{% endblock %}
{% block content %}
    <h1>Index</h1>
    <p class="important">Welcome on my awesome homepage.</p>
{% endblock %}

在子类模板中并不是所有的块都要被替换的，最终输出如下所示：

Not all blocks must be replaced at a child template, only those that are needed. The final output produced will be the following:

<!DOCTYPE html>
<html>
    <head>
        <style type="text/css">.important { color: #336699; }</style>
        <title>Index - My Webpage</title>
    </head>
    <body>
        <div id="content">
            <h1>Index</h1>
            <p class="important">Welcome on my awesome homepage.</p>
        </div>
        <div id="footer">
            &copy; Copyright 2012, All rights reserved.
        </div>
    </body>
</html>

多重继承Multiple Inheritance

模板可以多重扩展，如下代码所示：

Extended templates can extend other templates. The following example illustrates this:

{# main.volt #}
<!DOCTYPE html>
<html>
    <head>
        <title>Title</title>
    </head>
    <body>
        {% block content %}{% endblock %}
    </body>
</html>

“layout.volt”扩展了”main.volt”

Template “layout.volt” extends “main.volt”

{# layout.volt #}
{% extends "main.volt" %}
{% block content %}
    <h1>Table of contents</h1>
{% endblock %}

最后模板扩展了”layout.volt”

Finally a view that extends “layout.volt”:

{# index.volt #}
{% extends "layout.volt" %}
{% block content %}
    {{ super() }}
    <ul>
        <li>Some option</li>
        <li>Some other option</li>
    </ul>
{% endblock %}

“index.volt”最后的输出:

Rendering “index.volt” produces:

<!DOCTYPE html>
<html>
    <head>
        <title>Title</title>
    </head>
    <body>
        <h1>Table of contents</h1>
        <ul>
            <li>Some option</li>
            <li>Some other option</li>
        </ul>
    </body>
</html>

注意到”super()”，它渲染输出了父级块。部分模板调用扩展路径使用的是相对于当前视图路径的相对路径(i.e. app/views/)。

Note the call to the function “super()”. With that function it’s possible to render the contents of the parent block.

As partials, the path set to “extends” is a relative path under the current views directory (i.e. app/views/).

默认情况下为了性能原因，Volt只去检查子类模板的变动去判断是否重新编译模板，所以建议使用’compileAlways’ => true 初始化volt，这样父类模板改动的时候也会重新编译。

By default, and for performance reasons, Volt only checks for changes in the children templates to know when to re-compile to plain PHP again, so it is recommended initialize Volt with the option ‘compileAlways’ => true. Thus, the templates are compiled always taking into account changes in the parent templates.

自动转义模式Autoescape mode

在输出变量的时候可以打开自动转义模式：

You can enable auto-escaping of all variables printed in a block using the autoescape mode:

Manually escaped: {{ robot.name|e }}
{% autoescape true %}
    Autoescaped: {{ robot.name }}
    {% autoescape false %}
        No Autoescaped: {{ robot.name }}
    {% endautoescape %}
{% endautoescape %}

配置 Volt 引擎Setting up the Volt Engine

可以配置Volt去改变默认行为，下面例子展示如何使用：

Volt can be configured to alter its default behavior, the following example explain how to do that:

<?php
use Phalcon\Mvc\View;
use Phalcon\Mvc\View\Engine\Volt;
//Register Volt as a service
$di->set('voltService', function($view, $di) {
    $volt = new Volt($view, $di);
    $volt->setOptions(array(
        "compiledPath" => "../app/compiled-templates/",
        "compiledExtension" => ".compiled"
    ));
    return $volt;
});
//Register Volt as template engine
$di->set('view', function() {
    $view = new View();
    $view->setViewsDir('../app/views/');
    $view->registerEngines(array(
        ".volt" => 'voltService'
    ));
    return $view;
});

如果不想让volt去作为一个服务被重用，可以传递一个匿名函数去注册volt。

If you do not want to reuse Volt as a service you can pass an anonymous function to register the engine instead of a service name:

<?php
use Phalcon\Mvc\View;
use Phalcon\Mvc\View\Engine\Volt;
//Register Volt as template engine with an anonymous function
$di->set('view', function() {
    $view = new View();
    $view->setViewsDir('../app/views/');
    $view->registerEngines(array(
        ".volt" => function($view, $di) {
            $volt = new Volt($view, $di);
            //set some options here
            return $volt;
        }
    ));
    return $view;
});

Volt有以下配置选项：

The following options are available in Volt:

Option	Description	Default
compiledPath	A writable path where the compiled PHP templates will be placed	./
compiledExtension	An additional extension appended to the compiled PHP file	.php
compiledSeparator	Volt replaces the directory separators / and \ by this separator in order to create a single file in the compiled directory	%%
stat	Whether Phalcon must check if exists differences between the template file and its compiled path	true
compileAlways	Tell Volt if the templates must be compiled in each request or only when they change	false
prefix	Allows to prepend a prefix to the templates in the compilation path	null

compilation path编译路径根据上面的定义生成，如果开发者想要完全控制编译路径可以定义匿名函数去生成，匿名函数接受相对路径作为参数。下面代码展示了如何动态改变编译后文件路径。

The compilation path is generated according to the above options, if the developer wants total freedom defining the compilation path, an anonymous function can be used to generate it, this function receives the relative path to the template in the views directory. The following examples show how to change the compilation path dynamically:

<?php
// Just append the .php extension to the template path
// leaving the compiled templates in the same directory
$volt->setOptions(array(
    'compiledPath' => function($templatePath) {
        return $templatePath . '.php';
    }
));
// Recursively create the same structure in another directory
$volt->setOptions(array(
    'compiledPath' => function($templatePath) {
        $dirName = dirname($templatePath);
        if (!is_dir('cache/' . $dirName)) {
            mkdir('cache/' . $dirName);
        }
        return 'cache/' . $dirName . '/'. $templatePath . '.php';
    }
));

扩展 Volt Extending Volt

不像是其他的模板引擎，当模板编译后就不再需要volt了。考虑性能和独立性，volt仅仅是个PHP模板编译器。

Unlike other template engines, Volt itself is not required to run the compiled templates. Once the templates are compiled there is no dependence on Volt. With performance independence in mind, Volt only acts as a compiler for PHP templates.

Volt可以被扩展添加更多的函数，tests，和 filters 支持。

The Volt compiler allow you to extend it adding more functions, tests or filters to the existing ones.

函数 Functions

模板中的函数就像是PHP中的普通函数一样。函数需要一个规范的函数名。模板中的函数可以用两种方式定义：一种是定义函数名，一种是使用匿名函数定义。无论哪种总是要返回有效的PHP字符串表达式：

Functions act as normal PHP functions, a valid string name is required as function name. Functions can be added using two strategies, returning a simple string or using an anonymous function. Always is required that the chosen strategy returns a valid PHP string expression:

<?php
use Phalcon\Mvc\View\Engine\Volt;
$volt = new Volt($view, $di);
$compiler = $volt->getCompiler();
//This binds the function name 'shuffle' in Volt to the PHP function 'str_shuffle'
$compiler->addFunction('shuffle', 'str_shuffle');

使用匿名函数注册，我们可以使用$resolvedArgs去传递保留参数：

Register the function with an anonymous function. This case we use $resolvedArgs to pass the arguments exactly as were passed in the arguments:

<?php
$compiler->addFunction('widget', function($resolvedArgs, $exprArgs) {
    return 'MyLibrary\Widgets::get(' . $resolvedArgs . ')';
});

独立处理参数并且不做保留处理：

Treat the arguments independently and unresolved:

<?php
$compiler->addFunction('repeat', function($resolvedArgs, $exprArgs) use ($compiler) {
    //Resolve the first argument
    $firstArgument = $compiler->expression($exprArgs[0]['expr']);
    //Checks if the second argument was passed
    if (isset($exprArgs[1])) {
        $secondArgument = $compiler->expression($exprArgs[1]['expr']);
    } else {
        //Use '10' as default
        $secondArgument = '10';
    }
    return 'str_repeat(' . $firstArgument . ', ' . $secondArgument . ')';
});

根据是否有内置函数创建函数：

Generate the code based on some function availability:

<?php
$compiler->addFunction('contains_text', function($resolvedArgs, $exprArgs) {
    if (function_exists('mb_stripos')) {
        return 'mb_stripos(' . $resolvedArgs . ')';
    } else {
        return 'stripos(' . $resolvedArgs . ')';
    }
});

内置的函数可以被重载：

Built-in functions can be overridden adding a function with its name:

<?php
//Replace built-in function dump
$compiler->addFunction('dump', 'print_r');

过滤器Filters

过滤器使用方式为 leftExpr|name(optional-args)。添加新的过滤器和上面的函数一样：

A filter has the following form in a template: leftExpr|name(optional-args). Adding new filters is similar as seen with the functions:

<?php
//This creates a filter 'hash' that uses the PHP function 'md5'
$compiler->addFilter('hash', 'md5');

<?php
$compiler->addFilter('int', function($resolvedArgs, $exprArgs) {
    return 'intval(' . $resolvedArgs . ')';
});

内置的过滤器一样可以被重载：

Built-in filters can be overridden adding a function with its name:

<?php
//Replace built-in filter 'capitalize'
$compiler->addFilter('capitalize', 'lcfirst');

扩展Extensions

使用扩展可以灵活的扩展模板引擎，重载内置的结构改变行为和操作，添加函数、过滤器等。

With extensions the developer has more flexibility to extend the template engine, and override the compilation of a specific instruction, change the behavior of an expression or operator, add functions/filters, and more.

一个扩展就是一个由Volt触发事件作为其方法的类。

An extension is a class that implements the events triggered by Volt as a method of itself.

例如下面的代码允许在Volt中使用任意PHP函数：

For example, the class below allows to use any PHP function in Volt:

<?php
class PhpFunctionExtension
{
    /**
     * This method is called on any attempt to compile a function call
     */
    public function compileFunction($name, $arguments)
    {
        if (function_exists($name)) {
            return $name . '('. $arguments . ')';
        }
    }
}

上面的compileFunction函数在每次编译模板的函数之前时都会被调用。这个类实现了检查要编译的函数是不是PHP函数，允许模板中直接使用PHP函数。在扩展中的事件必须返回有效的PHP代码，替换内置的编译输出，否则将会使用程序内置的输出。

The above class implements the method ‘compileFunction’ which is invoked before any attempt to compile a function call in any template. The purpose of the extension is to verify if a function to be compiled is a PHP function allowing to call it from the template. Events in extensions must return valid PHP code, this will be used as result of the compilation instead of the one generated by Volt. If an event doesn’t return an string the compilation is done using the default behavior provided by the engine.

下面是可以在模板扩展中使用的编译事件：

The following compilation events are available to be implemented in extensions:

Event/Method	Description
compileFunction	Triggered before trying to compile any function call in a template
compileFilter	Triggered before trying to compile any filter call in a template
resolveExpression	Triggered before trying to compile any expression. This allows the developer to override operators
compileStatement	Triggered before trying to compile any expression. This allows the developer to override any statement

Volt扩展必须被注册在compiler编译器中

Volt extensions must be in registered in the compiler making them available in compile time:

<?php
//Register the extension in the compiler
$compiler->addExtension(new PhpFunctionExtension());

缓存视图片段Caching view fragments

使用Volt非常方便的去缓存视图片段。缓存增加了性能，防止内容块在每次浏览的时候被PHP解析执行：

With Volt it’s easy cache view fragments. This caching improves performance preventing that the contents of a block from being executed by PHP each time the view is displayed:

{% cache "sidebar" %}
    <!-- generate this content is slow so we are going to cache it -->
{% endcache %}

设定缓存时间：

Setting a specific number of seconds:

{# cache the sidebar by 1 hour #}
{% cache "sidebar" 3600 %}
    <!-- generate this content is slow so we are going to cache it -->
{% endcache %}

任何有效的表达式值可以被设置为缓存键名：

Any valid expression can be used as cache key:

{% cache ("article-" ~ post.id) 3600 %}
    <h1>{{ post.title }}</h1>
    <p>{{ post.content }}</p>
{% endcache %}

通过视图组件的:doc:Phalcon\Cache <cache>`实现了缓存效果。参考:doc:“Caching View Fragments” <views>`了解更多。

The caching is done by the Phalcon\Cache component via the view component. Learn more about how this integration works in the section “Caching View Fragments”.

注入服务到模版Inject Services into a Template

在Volt中服务容器也是可用的。在模板中访问服务模板就可以了：

If a service container (DI) is available for Volt, you can use the services by only accessing the name of the service in the template:

{# Inject the 'flash' service #}
<div id="messages">{{ flash.output() }}</div>
{# Inject the 'security' service #}
<input type="hidden" name="token" value="{{ security.getToken() }}">

独立的组件Stand-alone component

下面例子说明独立使用volt:

Using Volt in a stand-alone mode can be demonstrated below:

<?php
Phalcon\Mvc\View\Engine\Volt\Compiler as VoltCompiler;
//Create a compiler
$compiler = new VoltCompiler();
//Optionally add some options
$compiler->setOptions(array(
    //...
));
//Compile a template string returning PHP code
echo $compiler->compileString('{{ "hello" }}');
//Compile a template in a file specifying the destination file
$compiler->compileFile('layouts/main.volt', 'cache/layouts/main.volt.php');
//Compile a template in a file based on the options passed to the compiler
$compiler->compile('layouts/main.volt');
//Require the compiled templated (optional)
require $compiler->getCompiledTemplatePath();

其他资源

External Resources

A bundle for Sublime/Textmate is available here
Album-O-Rama is a sample application using Volt as template engine, [Github]
Our website is running using Volt as template engine, [Github]
Phosphorum, the Phalcon’s forum, also uses Volt, [Github]
Vökuró, is another sample application that use Volt, [Github]