tutorial-template-engines.md 4.13 KB
Newer Older
1 2 3
Using template engines
======================

Larry Ullman committed
4
By default, Yii uses PHP as its template language, but you can configure Yii to support other rendering engines, such as
5
[Twig](http://twig.sensiolabs.org/) or [Smarty](http://www.smarty.net/).
6

Larry Ullman committed
7
The `view` component is responsible for rendering views. You can add a custom template engine by reconfiguring this
8
component's behavior:
9 10

```php
Alexander Makarov committed
11
[
12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29
    'components' => [
        'view' => [
            'class' => 'yii\web\View',
            'renderers' => [
                'tpl' => [
                    'class' => 'yii\smarty\ViewRenderer',
                    //'cachePath' => '@runtime/Smarty/cache',
                ],
                'twig' => [
                    'class' => 'yii\twig\ViewRenderer',
                    //'cachePath' => '@runtime/Twig/cache',
                    //'options' => [], /*  Array of twig options */
                    'globals' => ['html' => '\yii\helpers\Html'],
                ],
                // ...
            ],
        ],
    ],
Alexander Makarov committed
30
]
31 32
```

Larry Ullman committed
33 34
In the code above, both Smarty and Twig are configured to be useable by the view files. But in order to get these extensions into your project, you need to also modify
your `composer.json` file to include them, too:
35 36 37 38 39

```
"yiisoft/yii2-smarty": "*",
"yiisoft/yii2-twig": "*",
```
Larry Ullman committed
40
That code would be added to the `require` section of `composer.json`. After making that change and saving the file, you can install the extensions by running `composer update --preder-dist` in the command-line.
41 42 43 44

Twig
----

Larry Ullman committed
45 46 47
To use Twig, you need to create templates in files that have the `.twig` extension (or use another file extension but configure the component accordingly).
Unlike standard view files, when using Twig you must include the extension in your `$this->render()`
or `$this->renderPartial()` controller calls:
48 49

```php
Alexander Makarov committed
50
echo $this->render('renderer.twig', ['username' => 'Alex']);
51 52
```

Alexander Makarov committed
53
### Additional syntax
54

Alexander Makarov committed
55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74
Yii adds some extra syntax constructs additionally to standard Twig ones.


###

{{registerAssetBundle('AppAsset')}} - Registers asset bundle of a given name


### Forms

```
{% set form = form_begin({ ... }) %}
{{ form.field(...) }}
{% form.end() %}
```


#### Getting URL for a route

There are two functions you can use for URLs:
75 76 77

```php
<a href="{{ path('blog/view', {'alias' : post.alias}) }}">{{ post.title }}</a>
Alexander Makarov committed
78
<a href="{{ url('blog/view', {'alias' : post.alias}) }}">{{ post.title }}</a>
79 80
```

Alexander Makarov committed
81
`path` generates relative URL while `url` generates absolute one. Internally both are using [[\yii\helpers\Url]].
82 83 84

### Additional variables

85 86 87 88
Within Twig templates, you can also make use of these variables:

- `app`, which equates to `\Yii::$app`
- `this`, which equates to the current `View` object
89

90 91
### Globals

Larry Ullman committed
92 93
You can add global helpers or values via the application configuration's `globals` variable. You can define both Yii helpers and your own
variables there:
94 95 96

```php
'globals' => [
97 98
    'html' => '\yii\helpers\Html',
    'name' => 'Carsten',
99 100 101
],
```

Larry Ullman committed
102
Once configured, in your template you can use the globals in the following way:
103 104

```
yupe committed
105
Hello, {{name}}! {{ html.a('Please login', 'site/login') | raw }}.
106 107 108 109
```

### Additional filters

Larry Ullman committed
110
Additional filters may be added via the application configuration's `filters` option:
111 112 113

```php
'filters' => [
114
    'jsonEncode' => '\yii\helpers\Json::encode',
115 116 117
],
```

Larry Ullman committed
118
Then in the template you can use:
119 120 121 122 123 124

```
{{ model|jsonEncode }}
```


125 126 127
Smarty
------

Larry Ullman committed
128 129
To use Smarty, you need to create templates in files that have the `.tpl` extension (or use another file extension but configure the component accordingly). Unlike standard view files, when using Smarty you must include the extension in your `$this->render()`
or `$this->renderPartial()` controller calls:
130 131

```php
Alexander Makarov committed
132
echo $this->render('renderer.tpl', ['username' => 'Alex']);
133 134 135 136
```

### Additional functions

137
Yii adds the following construct to the standard Smarty syntax:
138 139 140 141 142

```php
<a href="{path route='blog/view' alias=$post.alias}">{$post.title}</a>
```

143
Internally, the `path()` function calls Yii's `Url::to()` method.
144 145 146

### Additional variables

147 148 149 150
Within Smarty templates, you can also make use of these variables:

- `$app`, which equates to `\Yii::$app`
- `$this`, which equates to the current `View` object
151