Views

As one of the three pillars of the Model-View-Controller design pattern, the View class (along with other supporting classes) is responsible for taking the data passed from the request and/or controller, inserting this into the requested template/layout, and then returning the fully rendered content.

Unless otherwise specified, each controller action method results in a rendered view (usually as HTML). View names and locations are determined by convention, according the controller and action names involved. The basic pattern is that views are organized inside app/views/{controller name}, with each template named {action name}.{media}.php. For example:

  • UsersController::login() —> /app/views/users/login.html.php
  • NewsItemsController::viewAll() —> /app/views/news_items/view_all.html.php

Accessing View Variables

Controller-layer data is made available to the template by means of view variables. The names of these variables and their contents depends on how they were passed along by the controller. As covered in the Controller guide, view variables are populated by the use of the set() method, or by returning associative arrays from your controller action methods.

Keys in those arrays determine the names of the view variables. The following lines of code placed in a controller action method all result in a view variable named $foo with the contents "bar":

  1. $this->set(['foo' => 'bar']);
  3. // -- or --
  5. $foo = 'bar';
  6. $this->set(compact('foo'));
  8. // -- or --
  10. return ['foo' => 'bar'];
  12. // -- or --
  14. $foo = 'bar';
  15. return compact('foo');

Once this has been done in the controller, you can access the data like so:

  1. <p>Spit out data like this: <?= $foo ?></p>

li3 templates are just PHP, so feel free to toss in conditionals, loops and other presentation-based logic as needed.

Auto-Escaping

You might have noticed that the above example uses the short tag syntax to output the contents of a view variable. This syntax is a bit misleading, as li3 does not depend on or use short tags: this output behavior works a bit differently from how it seems.

When the view layer is rendered, each template is processed by a tokenizer before it is compiled into its final form. During this step something like this:

  1. <?= $variable ?>

Is translated into something like this:

  1. <?php echo $h($variable) ?>

The $h() function you see used there escapes HTML. To make a long story short, this mechanism provides an easy way for you to make sure all dynamically-generated data is safely landing in your HTML template.

We highly recommend using the <?= ... ?> syntax in your views, as it aids greatly in hardening your application against cross-site scripting (and related) attack techniques.

Note: One exception to this rule is when a line of template code references the $this object. In those cases, output is written directly to the template, rather than being filtered through $h(). This is so that content from helpers is not double-escaped. As such, the following two statements are equivalent:

  1. <?= $this->form->create() ?>
  3. <?php echo $this->form->create() ?>

This is an important consideration when accessing properties and methods from the template renderer. If you intend to echo content directly from $this which is not coming from a helper (this is not a common occurence), you must manually escape it, like so:

  1. <?php echo $h($this->foo) ?>

Layouts & Elements

Because different components of the view layer are often reused, li3 includes the common functionality of wrapping view templates inside of layouts and including small, re-usable view components called ‘elements’ inside of views. Unless otherwise configured, elements are defined in app/views/elements.

$this->_render() is used within the views to include elements. Any variables passed from the controller to the parent view are also available in the element. The third argument of $this->_render() can be used to pass additional variables.

  1. // renders app/views/elements/nav.html.php
  2. echo $this->_render('element', 'nav');
  4. // pass additional variables to the element
  5. echo $this->_render('element', 'nav', [
  6.   'some' => 'additional',
  7.   'vars' => 'available',
  8.   'in' => 'nav.html.php'
  9. ]);

Layouts contain the header and footer of a rendered view, and are defined in app/views/layouts. Unless otherwise directed, li3 will wrap a view’s template with the layout defined in app/views/layouts/default.{type}.php.

  1. namespace app\controllers;
  3. class MyController extends \lithium\action\Controller {
  5.   /**
  6.    * Overriding the layout for all actions in this controller
  7.    *
  8.    * @var array
  9.    */
  10.   protected $_render = [
  11.     'layout' => 'yourLayoutName'
  12.   ];
  14.   /**
  15.    * This action uses another layout which is located
  16.    * at `app/views/layouts/anotherLayout.html.php` by default.
  17.    * @return array
  18.    */
  19.   public function someAction() {
  20.     $this->_render['layout'] = 'anotherLayout';
  21.   }
  22. }

Layouts should call <?= $this->content() ?> to render the content of the inner view template in the desired location.

Output Handlers

In the view rendering context, you’ll have a number of different tools at your disposal. Besides PHP itself, the view layer features a number of handlers you can use to print out information in templates.

If you’re in the view layer, $this refers to the current Renderer adapter. Renderers are used to process different types of templates. The default renderer that ships with li3 is the File renderer, which handles plain PHP files (you can also write your own renderers if you wish to use a custom templating engine). When a renderer is initialized it sets up a number of handlers to help you output content in your views. li3’s default view renderer features these handlers:

  • $this->url(): Used for reverse routing lookups in views. For example: 
  1. $this->url(['Posts::view', 'id' => 13]);
  2. // Returns the URL for the matching route, e.g. '/posts/view/13'

The url() output handler is a friendly wrapper for Router::match(), and automatically passes some contextual parameters behind-the-scenes.

  • $this->path(): This handler generates asset paths to physical files. This is especially helpful for applications that will live at different parts of the domain during its lifecycle.
  1. $this->path('videos/funny_cats.flv');
  3. // If we're running at http://example.com/lithium/, this will return:
  4. // /lithium/videos/funny_cats.flv
  6. // If we're running at http://example.com/, this will return:
  7. // /videos/funny_cats.flv

Like url(), this handler is a wrapper for another class method, Media::asset(). Therefore, options that this method accepts can be passed to path() as well. For example, if you want to verify that the asset exists before returning the path, you can do the following:

  1. // Returns the path if the file exists, otherwise false.
  2. $path = $this->path('files/download_835.pdf', ['check' => true]);

You can also add a timestamp to the end of the URL, which is useful for working with browser caches:

  1. // Returns i.e. '<app path>/css/application.css?1290108597'
  2. $style = $this->path('css/application.css', ['timestamp' => true]);

See the $options parameter of Media::asset() for more information.

  • $this->content(): Prints out the content of the template to be rendered. This is really a requirement for most layouts.

  • $this->title(): Prints out the title of the current template. If an argument is supplied, it sets the title for the current template.

  1. // In your view:
  2. <?php $this->title('Home') ?>
  4. // In your layout:
  5. <title>My Awesome Application: <?= $this->title() ?></title>
  • $this->scripts(): Prints out the scripts specified for the current template. Usually, this is used by the script() method of the Html helper when the 'inline' option is set to false. However, you can append tags manually as well:
  1. // In your view:
  2. <?php 
  3. $this->scripts('<script src="https://example.org/js/jquery.min.js"></script>'); 
  4. $this->scripts('<script src="https://example.org/js/jquery-ui.min.js"></script>')
  5. ?>
  7. // In your layout:
  8. <head>
  9.  <?= $this->scripts() ?>
  10. </head>

In particular, this is useful when page-specific scripts are created inline in the page, and you’d like to place them in the <head /> along with your other scripts:

  1. <?php ob_start() ?>
  2. <script type="text/javascript">
  3. $(document).ready(function() {
  4.     // Do work here...
  5. });
  6. </script>
  7. <?php $this->scripts(ob_get_clean()) ?>
  • $this->styles(): Much the same as scripts() above, the styles() handler acts as a repository for any page-specific style sheets to be included in the layout. While primarily used by the style() method of the Html helper (again, see the 'inline' option), it may be used manually as well:
  1. // In your view:
  2. <?php
  3.  $this->styles('<link rel="stylesheet" type="text/css" href="/reset.css" />');
  4.  $this->styles('<link rel="stylesheet" type="text/css" href="/users.css" />')
  5. ?>
  7. // In your layout:
  8. <head>
  9.   <?= $this->styles() ?>
  10. </head>