template.md 3.27 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
					'globals' => ['html' => '\yii\helpers\Html'],
Alexander Makarov committed
25
				],
26
				// ...
Alexander Makarov committed
27 28 29 30
			],
		],
	],
]
31 32
```

33 34 35 36 37 38 39 40
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": "*",
```

41
in `require` section and then run `composer update --preder-dist`.
42 43 44 45

Twig
----

46 47
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()`
48 49 50
or `$this->renderPartial()` from your controller:

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

### Additional functions

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

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

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

### Additional variables

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

71 72 73 74 75 76 77 78 79 80 81 82 83 84 85
### 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:

```
yupe committed
86
Hello, {{name}}! {{ html.a('Please login', 'site/login') | raw }}.
87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105
```

### 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 }}
```


106 107 108
Smarty
------

109
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()`
110 111 112
or `$this->renderPartial()` from your controller:

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

### Additional functions

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

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

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

### Additional variables

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