structure-views.md 18.4 KB
Newer Older
Alexander Makarov committed
1 2 3
View
====

4
> Note: This section is under development.
Qiang Xue committed
5

6 7
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
8

Alexander Makarov committed
9 10 11 12

Basics
------

13 14 15 16
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
17

18
The view is typically called from controller action using the [[yii\base\Controller::render()|render()]] method:
Alexander Makarov committed
19 20 21 22

```php
public function actionIndex()
{
23
    return $this->render('index', ['username' => 'samdark']);
Alexander Makarov committed
24 25 26
}
```

27 28
The first argument to [[yii\base\Controller::render()|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`
Qiang Xue committed
29
is the controller ID. For details on how the view name is resolved, refer to the [[yii\base\Controller::render()]] method.
Alexander Makarov committed
30

31 32 33
The second argument to [[yii\base\Controller::render()|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.
34 35

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

```php
38
<p>Hello, <?= $username ?>!</p>
Alexander Makarov committed
39 40
```

41
Any data type can be passed to the view, including arrays or objects.
Alexander Makarov committed
42

43 44 45 46 47 48 49 50 51 52 53
Besides the above [[yii\web\Controller::render()|render()]] method, the [[yii\web\Controller]] class also provides
several other rendering methods. Below is a summary of these methods:

* [[yii\web\Controller::render()|render()]]: renders a view and applies the layout to the rendering result.
  This is most commonly used to render a complete page.
* [[yii\web\Controller::renderPartial()|renderPartial()]]: renders a view without applying any layout.
  This is often used to render a fragment of a page.
* [[yii\web\Controller::renderAjax()|renderAjax()]]: renders a view without applying any layout, and injects all
  registered JS/CSS scripts and files. It is most commonly used to render an HTML output to respond to an AJAX request.
* [[yii\web\Controller::renderFile()|renderFile()]]: renders a view file. This is similar to
  [[yii\web\Controller::renderPartial()|renderPartial()]] except that it takes the file path
Qiang Xue committed
54 55 56
  of the view instead of the view name.


Alexander Makarov committed
57 58 59
Widgets
-------

60 61 62 63 64 65 66 67
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),
Qiang Xue committed
68
breadcrumbs, menu, and [wrappers around bootstrap component framework](bootstrap-widgets.md). Additionally there are
69
extensions that provide more widgets, such as the official widget for [jQueryUI](http://www.jqueryui.com) components.
70

71
In order to use a widget, your view file would do the following:
72 73 74

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

// Passing an array to initialize the object properties
Alexander Makarov committed
78
$form = \yii\widgets\ActiveForm::begin([
79 80
    'options' => ['class' => 'form-horizontal'],
    'fieldConfig' => ['inputOptions' => ['class' => 'input-xlarge']],
Alexander Makarov committed
81
]);
82 83 84 85
... form inputs here ...
\yii\widgets\ActiveForm::end();
```

86 87 88
In the first example in the code above, the [[yii\base\Widget::widget()|widget()]] method is used to invoke a widget
that just outputs content. In the second example, [[yii\base\Widget::begin()|begin()]] and [[yii\base\Widget::end()|end()]]
are used for a
89 90 91
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.

92

Alexander Makarov committed
93 94 95 96 97 98 99
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.

Qiang Xue committed
100
Yii provides a good tool set in order to help you escape your output. The very basic thing to escape is a text without any
Alexander Makarov committed
101 102 103 104 105 106 107 108
markup. You can deal with it like the following:

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

<div class="username">
109
    <?= Html::encode($user->name) ?>
Alexander Makarov committed
110 111 112 113
</div>
```

When you want to render HTML it becomes complex so we're delegating the task to excellent
Qiang Xue committed
114
[HTMLPurifier](http://htmlpurifier.org/) library which is wrapped in Yii as a helper [[yii\helpers\HtmlPurifier]]:
Alexander Makarov committed
115 116 117 118 119 120 121

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

<div class="post">
122
    <?= HtmlPurifier::process($post->text) ?>
Alexander Makarov committed
123 124 125 126 127 128 129 130 131
</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
------------------------------

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

135 136
Using View object in templates
------------------------------
Alexander Makarov committed
137

138
An instance of [[yii\web\View]] component is available in view templates as `$this` variable. Using it in templates you
139
can do many useful things including setting page title and meta, registering scripts and accessing the context.
Alexander Makarov committed
140 141 142 143 144 145 146 147 148 149 150 151

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

152
Adding meta tags such as encoding, description, keywords is easy with view object as well:
Alexander Makarov committed
153 154

```php
Alexander Makarov committed
155
$this->registerMetaTag(['encoding' => 'utf-8']);
Alexander Makarov committed
156 157 158 159 160 161 162 163 164 165 166
```

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
167 168
$this->registerMetaTag(['name' => 'description', 'content' => 'This is my cool website made with Yii!'], 'meta-description');
$this->registerMetaTag(['name' => 'description', 'content' => 'This website is about funny raccoons.'], 'meta-description');
Alexander Makarov committed
169 170
```

Aris Karageorgos committed
171
If there are multiple calls with the same value of the second argument (`meta-description` in this case), the latter will
172
override the former and only a single tag will be rendered:
Alexander Makarov committed
173 174

```html
175
<meta name="description" content="This website is about funny raccoons.">
Alexander Makarov committed
176 177 178 179
```

### Registering link tags

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

```php
Alexander Makarov committed
184
$this->registerLinkTag([
185 186 187 188
    'title' => 'Lives News for Yii Framework',
    'rel' => 'alternate',
    'type' => 'application/rss+xml',
    'href' => 'http://www.yiiframework.com/rss.xml/',
Alexander Makarov committed
189
]);
Alexander Makarov committed
190 191 192 193 194 195 196 197 198 199 200 201
```

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

202 203
You can register CSS using [[yii\web\View::registerCss()|registerCss()]] or [[yii\web\View::registerCssFile()|registerCssFile()]].
The former registers a block of CSS code while the latter registers an external CSS file. For example,
Alexander Makarov committed
204 205 206 207 208 209 210 211 212 213 214 215 216

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

Anderson Müller committed
217
If you want to specify additional properties of the style tag, pass an array of name-values to the third argument.
Anderson Müller committed
218
If you need to make sure there's only a single style tag use fourth argument as was mentioned in meta tags description.
Alexander Makarov committed
219 220

```php
Qiang Xue committed
221
$this->registerCssFile("http://example.com/css/themes/black-and-white.css", [BootstrapAsset::className()], ['media' => 'print'], 'css-print-theme');
Alexander Makarov committed
222 223
```

Qiang Xue committed
224 225 226
The code above will add a link to CSS file to the head section of the page.

* The first argument specifies the CSS file to be registered.
227 228 229
* The second argument specifies that this CSS file depends on [[yii\bootstrap\BootstrapAsset|BootstrapAsset]], meaning it will be added
  AFTER the CSS files in [[yii\bootstrap\BootstrapAsset|BootstrapAsset]]. Without this dependency specification, the relative order
  between this CSS file and the [[yii\bootstrap\BootstrapAsset|BootstrapAsset]] CSS files would be undefined.
Qiang Xue committed
230 231 232 233 234 235
* The third argument specifies the attributes for the resulting `<link>` tag.
* The last argument specifies an ID identifying this CSS file. If it is not provided, the URL of the CSS file will be
  used instead.


It is highly recommended that you use [asset bundles](assets.md) to register external CSS files rather than
236 237
using [[yii\web\View::registerCssFile()|registerCssFile()]]. Using asset bundles allows you to combine and compress
multiple CSS files, which is desirable for high traffic websites.
Qiang Xue committed
238

Alexander Makarov committed
239 240 241

### Registering scripts

242 243 244 245
With the [[yii\web\View]] object you can register scripts. There are two dedicated methods for it:
[[yii\web\View::registerJs()|registerJs()]] for inline scripts and
[[yii\web\View::registerJsFile()|registerJsFile()]] for external scripts.
Inline scripts are useful for configuration and dynamically generated code.
Alexander Makarov committed
246
The method for adding these can be used as follows:
Alexander Makarov committed
247

Alexander Makarov committed
248
```php
249
$this->registerJs("var options = ".json_encode($options).";", View::POS_END, 'my-options');
Alexander Makarov committed
250 251
```

Qiang Xue committed
252 253
The first argument is the actual JS code we want to insert into the page. The second argument
determines where script should be inserted into the page. Possible values are:
Alexander Makarov committed
254

255 256 257 258 259
- [[yii\web\View::POS_HEAD|View::POS_HEAD]] for head section.
- [[yii\web\View::POS_BEGIN|View::POS_BEGIN]] for right after opening `<body>`.
- [[yii\web\View::POS_END|View::POS_END]] for right before closing `</body>`.
- [[yii\web\View::POS_READY|View::POS_READY]] for executing code on document `ready` event. This will register [[yii\web\JqueryAsset|jQuery]] automatically.
- [[yii\web\View::POS_LOAD|View::POS_LOAD]] for executing code on document `load` event. This will register [[yii\web\JqueryAsset|jQuery]] automatically.
Alexander Makarov committed
260

Qiang Xue committed
261 262
The last argument is a unique script ID that is used to identify code block and replace existing one with the same ID
instead of adding a new one. If you don't provide it, the JS code itself will be used as the ID.
Alexander Makarov committed
263

Qiang Xue committed
264
An external script can be added like the following:
Alexander Makarov committed
265 266

```php
Qiang Xue committed
267
$this->registerJsFile('http://example.com/js/main.js', [JqueryAsset::className()]);
Alexander Makarov committed
268 269
```

270 271
The arguments for [[yii\web\View::registerJsFile()|registerJsFile()]] are similar to those for
[[yii\web\View::registerCssFile()|registerCssFile()]]. In the above example,
Qiang Xue committed
272 273 274 275
we register the `main.js` file with the dependency on `JqueryAsset`. This means the `main.js` file
will be added AFTER `jquery.js`. Without this dependency specification, the relative order between
`main.js` and `jquery.js` would be undefined.

276 277
Like for [[yii\web\View::registerCssFile()|registerCssFile()]], it is also highly recommended that you use
[asset bundles](assets.md) to register external JS files rather than using [[yii\web\View::registerJsFile()|registerJsFile()]].
Qiang Xue committed
278

Alexander Makarov committed
279 280 281 282 283 284 285 286

### 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
287
\frontend\assets\AppAsset::register($this);
Alexander Makarov committed
288 289 290 291
```

### Layout

Alexander Makarov committed
292 293
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.
Reazul Iqbal committed
294
You can find a fine example of the layout in a [basic application template](apps-basic.md). Here we'll review the very
Alexander Makarov committed
295 296 297 298 299 300
basic one without any widgets or extra markup.

```php
<?php
use yii\helpers\Html;
?>
Алексей committed
301
<?php $this->beginPage() ?>
Alexander Makarov committed
302
<!DOCTYPE html>
303
<html lang="<?= Yii::$app->language ?>">
Alexander Makarov committed
304
<head>
305 306 307
    <meta charset="<?= Yii::$app->charset ?>"/>
    <title><?= Html::encode($this->title) ?></title>
    <?php $this->head() ?>
Alexander Makarov committed
308 309
</head>
<body>
Алексей committed
310
<?php $this->beginBody() ?>
311 312 313
    <div class="container">
        <?= $content ?>
    </div>
314
    <footer class="footer">&copy; 2013 me :)</footer>
Алексей committed
315
<?php $this->endBody() ?>
Alexander Makarov committed
316 317
</body>
</html>
Алексей committed
318
<?php $this->endPage() ?>
Alexander Makarov committed
319 320 321 322 323
```

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.

324
We are importing [[yii\helpers\Html|Html]] helper via standard PHP `use` statement. This helper is typically used for almost all views
325 326
where one need to escape outputted data.

327 328 329 330
Several special methods such as [[yii\web\View::beginPage()|beginPage()]]/[[yii\web\View::endPage()|endPage()]],
[[yii\web\View::head()|head()]], [[yii\web\View::beginBody()|beginBody()]]/[[yii\web\View::endBody()|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 the rendering to work correctly.
Alexander Makarov committed
331

332
By default layout is loaded from `views/layouts/main.php`. You may change it at controller or module level by setting
333
different value to `layout` property.
334 335

In order to pass data from controller to layout, that you may need for breadcrumbs or similar elements, use view component
Alexander Makarov committed
336
params property. In controller it can be set as:
337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355

```php
$this->view->params['breadcrumbs'][] = 'Contact';
```

In a view it will be:

```php
$this->params['breadcrumbs'][] = 'Contact';
```

In layout file the value can be used like the following:

```php
<?= Breadcrumbs::widget([
    'links' => isset($this->params['breadcrumbs']) ? $this->params['breadcrumbs'] : [],
]) ?>
```

356 357 358 359 360 361 362 363 364 365 366
You may also wrap the view render result into a layout using [[yii\base\View::beginContent()]], [[yii\base\View::endContent()]].
This approach can be used while applying nested layouts:

```php
<?php $this->beginContent('//layouts/overall') ?>
<div class="content">
    <?= $content ?>
<div>
<?php $this->endContent() ?>
```

Alexander Makarov committed
367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382
### 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">
383 384
    <h2><?= Html::encode($username) ?></h2>
    <p><?= Html::encode($tagline) ?></p>
Alexander Makarov committed
385 386 387 388 389 390 391
</div>
```

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

```php
<div class="user-index">
392 393 394 395 396 397 398 399
    <?php
    foreach ($users as $user) {
        echo $this->render('_profile', [
            'username' => $user->name,
            'tagline' => $user->tagline,
        ]);
    }
    ?>
Alexander Makarov committed
400 401 402 403 404 405
</div>
```

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

```php
Alexander Makarov committed
406
echo $this->render('_profile', [
407 408
    'username' => $user->name,
    'tagline' => $user->tagline,
Alexander Makarov committed
409
]);
Alexander Makarov committed
410 411
```

412 413 414 415 416 417 418 419 420 421 422 423 424 425

When you call `render()` to render a partial in a current view, you may use different formats to refer to the partial.
The most commonly used format is the so-called relative view name which is as shown in the above example.
The partial view file is relative to the directory containing the current view. If the partial is located under
a subdirectory, you should include the subdirectory name in the view name, e.g., `public/_profile`.

You may use path alias to specify a view, too. For example, `@app/views/common/_profile`.

And you may also use the so-called absolute view names, e.g., `/user/_profile`, `//user/_profile`.
An absolute view name starts with a single slashes or double slashes. If it starts with a single slash,
the view file will be looked for under the view path of the currently active module. Otherwise, it will
will be looked for under the application view path.


Alexander Makarov committed
426 427 428 429 430 431 432 433 434 435
### 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();
```

Evgeniy Tkachenko committed
436 437
### Static Pages

438 439
If you need to render static pages you can use class `ViewAction`. It represents an action that displays a view according
to a user-specified parameter.
Evgeniy Tkachenko committed
440

441
Usage of the class is simple. In your controller use the class via `actions` method:
Evgeniy Tkachenko committed
442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458

```php
class SiteController extends Controller
{
    public function actions()
    {
        return [
            'static' => [
                'class' => '\yii\web\ViewAction',
            ],
        ];
    }

    //...
}
```

459 460
Then create `index.php` in `@app/views/site/pages/`:

Evgeniy Tkachenko committed
461 462
```php
//index.php
463
<h1>Hello, I am a static page!</h1>
Evgeniy Tkachenko committed
464 465
```

466
That's it. Now you can try it using `/index.php?r=site/static`.
Evgeniy Tkachenko committed
467 468

By default, the view being displayed is specified via the `view` GET parameter. 
469
If you open `/index.php?r=site/static?&view=about` then `@app/views/site/pages/about.php` view file will be used.
Evgeniy Tkachenko committed
470

471
If not changed or specified via GET defaults are the following:
Evgeniy Tkachenko committed
472

473 474 475 476
- GET parameter name: `view`.
- View file used if parameter is missing: `index.php`.
- Directory where views are stored (`viewPrefix`): `pages`.
- Layout for the page rendered matches the one used in controller.
Evgeniy Tkachenko committed
477

478
For more information see [[yii\web\ViewAction]].
Evgeniy Tkachenko committed
479

Alexander Makarov committed
480 481
### Caching blocks

Alexander Makarov committed
482
To learn about caching of view fragments please refer to [caching](caching.md) section of the guide.
483 484 485 486 487

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

Since view is also an application component named `view` you can replace it with your own component that extends
488
from [[yii\base\View]] or [[yii\web\View]]. It can be done via application configuration file such as `config/web.php`:
489 490

```php
Alexander Makarov committed
491
return [
492 493 494 495 496 497 498
    // ...
    'components' => [
        'view' => [
            'class' => 'app\components\View',
        ],
        // ...
    ],
Alexander Makarov committed
499
];
500
```