template.md 3.75 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 53 54
```

### Additional functions

55
Yii adds the following construct to the standard Twig syntax:
56 57 58 59 60

```php
<a href="{{ path('blog/view', {'alias' : post.alias}) }}">{{ post.title }}</a>
```

61
Internally, the `path()` function calls Yii's `Url::to()` method.
62 63 64

### Additional variables

65 66 67 68
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
69

70 71
### Globals

Larry Ullman committed
72 73
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:
74 75 76

```php
'globals' => [
77 78
    'html' => '\yii\helpers\Html',
    'name' => 'Carsten',
79 80 81
],
```

Larry Ullman committed
82
Once configured, in your template you can use the globals in the following way:
83 84

```
yupe committed
85
Hello, {{name}}! {{ html.a('Please login', 'site/login') | raw }}.
86 87 88 89
```

### Additional filters

Larry Ullman committed
90
Additional filters may be added via the application configuration's `filters` option:
91 92 93

```php
'filters' => [
94
    'jsonEncode' => '\yii\helpers\Json::encode',
95 96 97
],
```

Larry Ullman committed
98
Then in the template you can use:
99 100 101 102 103 104

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


105 106 107
Smarty
------

Larry Ullman committed
108 109
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:
110 111

```php
Alexander Makarov committed
112
echo $this->render('renderer.tpl', ['username' => 'Alex']);
113 114 115 116
```

### Additional functions

117
Yii adds the following construct to the standard Smarty syntax:
118 119 120 121 122

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

123
Internally, the `path()` function calls Yii's `Url::to()` method.
124 125 126

### Additional variables

127 128 129 130
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
131