template.md 3.35 KB
Newer Older
1 2 3
Using template engines
======================

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

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

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

35 36 37 38 39 40 41 42 43
In the config above we're using Smarty and Twig. In order to get these extensions in your project you need to modify
your `composer.json` to include

```
"yiisoft/yii2-smarty": "*",
"yiisoft/yii2-twig": "*",
```

in `require` section and then run `composer update`.
44 45 46 47

Twig
----

48 49
To use Twig, you need to create templates in files with 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  when calling `$this->render()`
50 51 52
or `$this->renderPartial()` from your controller:

```php
Alexander Makarov committed
53
echo $this->render('renderer.twig', ['username' => 'Alex']);
54 55 56 57
```

### Additional functions

58
Yii adds the following construct to the standard Twig syntax:
59 60 61 62 63

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

64
Internally, the `path()` function calls Yii's `Html::url()` method.
65 66 67

### Additional variables

68 69 70 71
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
72

73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107
### Globals

You can add global helpers or values via config's `globals`. It allows both using Yii helpers and setting your own
values:

```php
'globals' => [
	'html' => '\yii\helpers\Html',
	'name' => 'Carsten',
],
```

Then in your template you can use it the following way:

```
Hello, {{name}}! {{ html.link('Please login', 'site/login') }}.
```

### Additional filters

Additional filters may be added via config's `filters` option:

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

Then in the template you can use

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


108 109 110
Smarty
------

111
To use Smarty, you need to create templates in files with 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  when calling `$this->render()`
112 113 114
or `$this->renderPartial()` from your controller:

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

### Additional functions

120
Yii adds the following construct to the standard Smarty syntax:
121 122 123 124 125

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

126
Internally, the `path()` function calls Yii's `Html::url()` method.
127 128 129

### Additional variables

130 131 132 133
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
134