view.md 12.4 KB
Newer Older
Alexander Makarov committed
1 2 3
View
====

4
The view component is an important part of MVC. The view acts as the interface to the application, making it responsible for presenting data to end users, displaying forms, and so forth. 
Qiang Xue committed
5

Alexander Makarov committed
6 7 8 9

Basics
------

10
By default, Yii uses PHP in view templates to generate content and elements. A web application view typically contains some combination of HTML, along with PHP `echo`, `foreach`, `if`, and other basic constructs. Using complex PHP code in views is considered to be bad practice. When complex logic and functionality is needed, such code should either be moved to a controller or a widget.
Alexander Makarov committed
11

12
The view is typically called from controller action using the `render()` method:
Alexander Makarov committed
13 14 15 16

```php
public function actionIndex()
{
Alexander Makarov committed
17
	return $this->render('index', ['username' => 'samdark']);
Alexander Makarov committed
18 19 20
}
```

21 22
The first argument to `render()` is the name of the view to display. In the context of the controller, Yii will search for its views in `views/site/` where `site`
is the controller ID. For details on how the view name is resolved, refer to the [yii\base\Controller::render] method.
Alexander Makarov committed
23

24 25 26 27

The second argument to `render()` is a data array of key-value pairs. Through this array, data can be passed to the view, making the value available in the view as a variable named the same as the corresponding key.

The view for the action above would be `views/site/index.php` and can be something like:
Alexander Makarov committed
28 29

```php
30
<p>Hello, <?= $username ?>!</p>
Alexander Makarov committed
31 32
```

33
Any data type can be passed to the view, including arrays or objects.
Alexander Makarov committed
34 35 36 37

Widgets
-------

38 39 40 41 42 43 44 45 46 47
Widgets are self-contained building blocks for your views, a way to combine complex logic, display, and functionality into a single component. A widget:

* May contain advanced PHP programming
* Is typically configurable
* Is often provided data to be displayed
* Returns HTML to be shown within the context of the view

There are a good number of widgets bundled with Yii, such as [active form](form.md),
breadcrumbs, dmenu, and [wrappers around bootstrap component framework](bootstrap-widgets.md). Additionally there are
extensions that provide more widgets, such as the official widget for [jQueryUI](http://www.jqueryui.com) components.
48

49
In order to use a widget, your view file would do the following:
50 51 52

```php
// Note that you have to "echo" the result to display it
Alexander Makarov committed
53
echo \yii\widgets\Menu::widget(['items' => $items]);
54 55

// Passing an array to initialize the object properties
Alexander Makarov committed
56 57 58 59
$form = \yii\widgets\ActiveForm::begin([
	'options' => ['class' => 'form-horizontal'],
	'fieldConfig' => ['inputOptions' => ['class' => 'input-xlarge']],
]);
60 61 62 63
... form inputs here ...
\yii\widgets\ActiveForm::end();
```

64
In the first example in the code above, the `widget` method is used to invoke a widget that just outputs content. In the second example, `begin` and `end` are used for a
65 66 67
widget that wraps content between method calls with its own output. In case of the form this output is the `<form>` tag
with some properties set.

Alexander Makarov committed
68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83
Security
--------

One of the main security principles is to always escape output. If violated it leads to script execution and,
most probably, to cross-site scripting known as XSS leading to leaking of admin passwords, making a user to automatically
perform actions etc.

Yii provides a good toolset in order help you escaping your output. The very basic thing to escape is a text without any
markup. You can deal with it like the following:

```php
<?php
use yii\helpers\Html;
?>

<div class="username">
Alexander Makarov committed
84
	<?= Html::encode($user->name) ?>
Alexander Makarov committed
85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104
</div>
```

When you want to render HTML it becomes complex so we're delegating the task to excellent
[HTMLPurifier](http://htmlpurifier.org/) library. In order to use it you need to modify your `composer.json` first by
adding the following to `require`:

```javascript
"ezyang/htmlpurifier": "v4.5.0"
```

After it's done run `php composer.phar install` and wait till package is downloaded. Now everything is prepared to use
Yii's HtmlPurifier helper:

```php
<?php
use yii\helpers\HtmlPurifier;
?>

<div class="post">
Alexander Makarov committed
105
	<?= HtmlPurifier::process($post->text) ?>
Alexander Makarov committed
106 107 108 109 110 111 112 113 114
</div>
```

Note that besides HTMLPurifier does excellent job making output safe it's not very fast so consider
[caching result](caching.md).

Alternative template languages
------------------------------

115
There are official extensions for [Smarty](http://www.smarty.net/) and [Twig](http://twig.sensiolabs.org/). In order
Alexander Makarov committed
116
to learn more refer to [Using template engines](template.md) section of the guide.
Alexander Makarov committed
117

118 119
Using View object in templates
------------------------------
Alexander Makarov committed
120

Alexander Makarov committed
121
An instance of `yii\web\View` component is available in view templates as `$this` variable. Using it in templates you
122
can do many useful things including setting page title and meta, registering scripts and accessing the context.
Alexander Makarov committed
123 124 125 126 127 128 129 130 131 132 133 134

### Setting page title

A common place to set page title are view templates. Since we can access view object with `$this`, setting a title
becomes as easy as:

```php
$this->title = 'My page title';
```

### Adding meta tags

135
Adding meta tags such as encoding, description, keywords is easy with view object as well:
Alexander Makarov committed
136 137

```php
Alexander Makarov committed
138
$this->registerMetaTag(['encoding' => 'utf-8']);
Alexander Makarov committed
139 140 141 142 143 144 145 146 147 148 149
```

The first argument is an map of `<meta>` tag option names and values. The code above will produce:

```html
<meta encoding="utf-8">
```

Sometimes there's a need to have only a single tag of a type. In this case you need to specify the second argument:

```html
Alexander Makarov committed
150 151
$this->registerMetaTag(['description' => 'This is my cool website made with Yii!'], 'meta-description');
$this->registerMetaTag(['description' => 'This website is about funny raccoons.'], 'meta-description');
Alexander Makarov committed
152 153
```

Aris Karageorgos committed
154
If there are multiple calls with the same value of the second argument (`meta-description` in this case), the latter will
155
override the former and only a single tag will be rendered:
Alexander Makarov committed
156 157 158 159 160 161 162

```html
<meta description="This website is about funny raccoons.">
```

### Registering link tags

163
`<link>` tag is useful in many cases such as customizing favicon, pointing to RSS feed or delegating OpenID to another
Alexander Makarov committed
164 165 166
server. Yii view object has a method to work with these:

```php
Alexander Makarov committed
167
$this->registerLinkTag([
Alexander Makarov committed
168 169 170 171
	'title' => 'Lives News for Yii Framework',
	'rel' => 'alternate',
	'type' => 'application/rss+xml',
	'href' => 'http://www.yiiframework.com/rss.xml/',
Alexander Makarov committed
172
]);
Alexander Makarov committed
173 174 175 176 177 178 179 180 181 182 183 184 185
```

The code above will result in

```html
<link title="Lives News for Yii Framework" rel="alternate" type="application/rss+xml" href="http://www.yiiframework.com/rss.xml/" />
```

Same as with meta tags you can specify additional argument to make sure there's only one link of a type registered.

### Registering CSS

You can register CSS using `registerCss` or `registerCssFile`. Former is for outputting code in `<style>` tags directly
Aris Karageorgos committed
186
to the page which is not recommended in most cases (but still valid). Latter is for registering CSS file. In Yii it's
Alexander Makarov committed
187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205
much better to [use asset manager](assets.md) to deal with these since it provides extra features so `registerCssFile`
is manly useful for external CSS files.

```php
$this->registerCss("body { background: #f00; }");
```

The code above will result in adding the following to the head section of the page:

```html
<style>
body { background: #f00; }
</style>
```

If you want to specify additional properties of the style tag, pass array of name-values to the second argument. If you
need to make sure there's only a single style tag use third argument as was mentioned in meta tags description.

```php
Alexander Makarov committed
206
$this->registerCssFile("http://example.com/css/themes/black-and-white.css", ['media' => 'print'], 'css-print-theme');
Alexander Makarov committed
207 208 209 210 211 212 213
```

The code above will add a link to CSS file to the head section of the page. The CSS will be used only when printing the
page. We're using third argument so one of the views could override it.

### Registering scripts

214
With View object you can register scripts. There are two dedicated methods for it: `registerJs` for inline scripts
Alexander Makarov committed
215 216
and `registerJsFile` for external scripts. Inline scripts are useful for configuration and dynamically generated code.
The method for adding these can be used as follows:
Alexander Makarov committed
217

Alexander Makarov committed
218
```php
219
$this->registerJs("var options = ".json_encode($options).";", View::POS_END, 'my-options');
Alexander Makarov committed
220 221 222 223 224 225 226 227 228 229 230 231
```

First argument is the actual code where we're converting a PHP array of options to JavaScript one. Second argument
determines where script should be in the page. Possible values are:

- `View::POS_HEAD` for head section.
- `View::POS_BEGIN` for right after opening `<body>`.
- `View::POS_END` for right before closing `</body>`.
- `View::POS_READY` for executing code on document `ready` event. This one registers jQuery automatically.

The last argument is unique script ID that is used to identify code block and replace existing one with the same ID
instead of adding a new one.
Alexander Makarov committed
232

Alexander Makarov committed
233 234 235 236 237 238 239
External script can be added like the following:

```php
$this->registerJsFile('http://example.com/js/main.js');
```

Same as with external CSS it's preferred to use asset bundles for external scripts.
Alexander Makarov committed
240 241 242 243 244 245 246 247

### Registering asset bundles

As was mentioned earlier it's preferred to use asset bundles instead of using CSS and JavaScript directly. You can get
details on how to define asset bundles in [asset manager](assets.md) section of the guide. As for using already defined
asset bundle, it's very straightforward:

```php
248
frontend\assets\AppAsset::register($this);
Alexander Makarov committed
249 250 251 252
```

### Layout

Alexander Makarov committed
253 254 255 256 257 258 259 260 261
A layout is a very convenient way to represent the part of the page that is common for all or at least for most pages
generated by your application. Typically it includes `<head>` section, footer, main menu and alike elements.
You can fine a fine example of the layout in a [basic application template](apps-basic.md). Here we'll review the very
basic one without any widgets or extra markup.

```php
<?php
use yii\helpers\Html;
?>
Алексей committed
262
<?php $this->beginPage() ?>
Alexander Makarov committed
263
<!DOCTYPE html>
264
<html lang="<?= Yii::$app->language ?>">
Alexander Makarov committed
265
<head>
Alexander Makarov committed
266 267
	<meta charset="<?= Yii::$app->charset ?>"/>
	<title><?= Html::encode($this->title) ?></title>
Алексей committed
268
	<?php $this->head() ?>
Alexander Makarov committed
269 270
</head>
<body>
Алексей committed
271
<?php $this->beginBody() ?>
Alexander Makarov committed
272
	<div class="container">
Alexander Makarov committed
273
		<?= $content ?>
Alexander Makarov committed
274 275
	</div>
	<footer class="footer">© 2013 me :)</footer>
Алексей committed
276
<?php $this->endBody() ?>
Alexander Makarov committed
277 278
</body>
</html>
Алексей committed
279
<?php $this->endPage() ?>
Alexander Makarov committed
280 281 282 283 284
```

In the markup above there's some code. First of all, `$content` is a variable that will contain result of views rendered
with controller's `$this->render()` method.

285 286 287 288 289 290
We are importing `Html` helper via standard PHP `use` statement. This helper is typically used for almost all views
where one need to escape outputted data.

Several special methods such as `beginPage`/`endPage`, `head`, `beginBody`/`endBody` are triggering page rendering events
that are used for registering scripts, links and process page in many other ways. Always include these in your layout in
order for rendering to work correctly.
Alexander Makarov committed
291

Alexander Makarov committed
292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307
### Partials

Often you need to reuse some HTML markup in many views and often it's too simple to create a full-featured widget for it.
In this case you may use partials.

Partial is a view as well. It resides in one of directories under `views` and by convention is often started with `_`.
For example, we need to render a list of user profiles and, at the same time, display individual profile elsewhere.

First we need to define a partial for user profile in `_profile.php`:

```php
<?php
use yii\helpers\Html;
?>

<div class="profile">
Alexander Makarov committed
308 309
	<h2><?= Html::encode($username) ?></h2>
	<p><?= Html::encode($tagline) ?></p>
Alexander Makarov committed
310 311 312 313 314 315 316 317
</div>
```

Then we're using it in `index.php` view where we display a list of users:

```php
<div class="user-index">
	<?php
318
	foreach ($users as $user) {
Alexander Makarov committed
319
		echo $this->render('_profile', [
Alexander Makarov committed
320 321
			'username' => $user->name,
			'tagline' => $user->tagline,
Alexander Makarov committed
322
		]);
Alexander Makarov committed
323 324 325 326 327 328 329 330
	}
	?>
</div>
```

Same way we can reuse it in another view displaying a single user profile:

```php
Alexander Makarov committed
331
echo $this->render('_profile', [
Alexander Makarov committed
332 333
	'username' => $user->name,
	'tagline' => $user->tagline,
Alexander Makarov committed
334
]);
Alexander Makarov committed
335 336 337 338 339 340 341 342 343 344 345 346 347 348
```

### Accessing context

Views are generally used either by controller or by widget. In both cases the object that called view rendering is
available in the view as `$this->context`. For example if we need to print out the current internal request route in a
view rendered by controller we can use the following:

```php
echo $this->context->getRoute();
```

### Caching blocks

Alexander Makarov committed
349
To learn about caching of view fragments please refer to [caching](caching.md) section of the guide.
350 351 352 353 354

Customizing View component
--------------------------

Since view is also an application component named `view` you can replace it with your own component that extends
Alexander Makarov committed
355
from `yii\base\View` or `yii\web\View`. It can be done via application configuration file such as `config/web.php`:
356 357

```php
Alexander Makarov committed
358
return [
359
	// ...
Alexander Makarov committed
360 361
	'components' => [
		'view' => [
362
			'class' => 'app\components\View',
Alexander Makarov committed
363
		],
364
		// ...
Alexander Makarov committed
365 366
	],
];
367
```