Views

• Basics
• View renderers
  • Plain PHP
  • Templates
• Custom view renderers

Views is where the HTML of your application goes. A view can be an entire web page or just a small section of a page like a header, menu or footer.

Using views allows you to separate the presentation and business logic of your application, permitting independent development, testing and maintenance of each.

All views must be located in the phpapp/resources/views directory. You can of course create subdirectories to better organize your view files.

Basics

Creating a view object is done by passing the name of the view file to the phpcreate method of the view factory.

$view = $this->view->create('welcome');

If you're organizing your views in subdirectories then you'll have to separate the directory and template names by a dot. The following example loads the phpbar view located in the phpfoo directory.

$view = $this->view->create('foo.bar');

Assigning variables can be done using the optional second parameter.

$view = $this->view->create('foo.bar', ['foo' => 'bar']);

You can also assign variables to a view object by using the phpassign method of the view class. You can assign any kind of variable, even another view object. The assigned variable is only available in the view you assigned it to and its child views.

$view->assign('foo', 'bar');

You can also assign global view variables that will be available in all views using the phpassign method on the view factory instance.

$this->view->assign('user', $user);

The phprender method returns the rendered output of the view and it also accepts the same optional second parameter as the create method.

$output = $view->render();

You can also render a view directly from the view factory, and as expected it accepts the same optional second parameter as the render method of the view object.

$rendered = $this->view->render('foo.bar');

View renderers

Plain PHP

As the name suggests, plain PHP views are just HTML (or whatever you're using to present your data) and PHP.

<div>
	<p>Hello, <?= $name; ?>!</p>
</div>

You also have access to a few handy methods that you should use to escape untrusted data in your output.

<div>
	<p>Hello, <?= $this->escapeHTML($name, $__charset__); ?>!</p>
</div>

The phpescapeAttribute method is not enough to securely escape complex attributes such as phphref, phpsrc, phpstyle, or any of the event handlers like phponmouseover, phponmouseout etc. It is extremely important that event handler attributes should be escaped with the phpescapeJS filter.

Templates

Mako includes a simple templating language that offers a simpler and less verbose syntax than plain PHP in addition to automatic escaping of all variables.

There is almost no overhead associated with using template views as they get compiled into regular PHP views and they won't be re-compiled until you update them.

You must use the special php.tpl.php extension on your views for them to get rendered using the template engine.

Printing an escaped variable for use in a HTML content context is done using the following syntax:

{{$foo}}

The phppreserve filter will escape output but not double-encode existing html entities.

{{preserve:$foo}}

The phpattribute filter will escape output for use in a HTML attribute context.

{{attribute:$foo}}

The phpattribute filter is not enough to securely escape complex attributes such as phphref, phpsrc, phpstyle, or any of the event handlers like phponmouseover, phponmouseout etc. It is extremely important that event handler attributes should be escaped with the phpjs filter.

The phpjs filter will escape output for use in a JavaScript context.

{{js:$foo}}

The phpcss filter will escape output for use in a CSS context.

{{css:$foo}}

The phpurl filter will escape output for use in a URI parameter context.

{{url:$foo}}

If you want to print an un-escaped variable then you can use the phpraw filter.

{{raw:$foo}}

Sometimes you'll want to set a default value for a variable that might be empty. This can be done like this.

{{$foo || 'Default value'}}

You can also use functions and methods in your templates.

<a href="{{$urlbuilder->to('about')}}">{{$i18n->get('about')}}</a>

Conditional statements (phpif, phpelseif and phpelse) are also supported.

{% if($foo === $bar) %}
	$foo equals $bar
{% else %}
	$foo is not equal to $bar
{% endif %}

Loops is something you'll often need when displaying data. Templates support phpforeach, phpfor and phpwhile loops. You can skip an iteration using phpcontinue or break out of the loop using phpbreak.

<ul>
{% foreach($articles as $article) %}
	<li>{{$article->title}}</li>
{% endforeach %}
</ul>

You can easily include a partial template in a view.

{{view:'partials.footer'}}

Included views will automatically inherit all the variables available in the parent view but you override them or add new ones.

{{view:'partials.footer', ['foo' => 'bar']}}

If you want the template compiler to ignore a section of your template then you can use the verbatim blocks.

{% verbatim %}
	This {{$will}} not be {{$parsed}}.
{% endverbatim %}

Another useful feature is template inheritance. This allows you to define a parent wrapper view that you can easily extend. Let's say you save the template below as phpparent.tpl.php.

<!DOCTYPE html>
<html lang="en">
	<head>
		<meta charset="{{$__charset__}}">
		<title>{{block:title}}My Site{{endblock}}</title>
	</head>
	<body>
		<h1>Header</h1>
		<ul>
		{{block:list}}{{endblock}}
		</ul>
		<hr>
		{{block:content}}{{endblock}}
		<hr>
		Footer
	</body>
</html>

You can then create a phpchild.tpl.php template that extends the parent template.

{% extends:'parent' %}

{% block:title %}My Page - __PARENT__{% endblock %}

{% block:list %}
	<li>Item 1</li>
	<li>Item 2</li>
{% endblock %}

{% block:content %}
	This is the content.
{% endblock %}

The php__PARENT__ string will be replaced by the contents of the parent block.

Rendering the child template will result in the HTML document displayed below.

<!DOCTYPE html>
<html lang="en">
	<head>
		<meta charset="UTF-8">
		<title>My Page - My Site</title>
	</head>
	<body>
		<h1>Header</h1>
		<ul>
			<li>Item 1</li>
			<li>Item 2</li>
		</ul>
		<hr>
		This is the content
		<hr>
		Footer
	</body>
</html>

Custom view renderers

Mako also makes it easy to use custom view renderers such as Twig or Smarty.

Registering a custom renderer is done using the phpextend method. The first parameter is the file extension you want to associate with your custom renderer and the second parameter is the class name of your renderer class.

The renderer will be instantiated by the dependency injection container so all dependencies will automatically be injected.

$this->view->extend('.twig', TwigRenderer::class);

You can also use a closure if your renderer requires parameters that the container is unable to resolve.

$this->view->extend('.twig', function()
{
	$renderer = new foo\bar\TwigRenderer;

	$renderer->setCachePath('/tmp');

	return $renderer;
});

All custom renderers must implement the phpmako\view\renderers\RendererInterface interface.