Add "foa/html-view-bundle": "2.*" to your composer.json and run composer update to install the dependencies.
When you generate output via templates, you must escape it appropriately for security purposes. This means that HTML templates should use HTML escaping, CSS templates should use CSS escaping, XML templates should use XML escaping, PDF templates should use PDF escaping, RTF templates should use RTF escaping, and so on.
Registering View Templates
Assuming you have a Aura\View\View object, we need to add named templates to its view template registry. These are typically PHP file paths, but templates can also be closures. For example:
The browse.php file may look something like this:
Note that we use echo, and not return, in templates.
The template logic will be executed inside the View object scope,
which means that $this in the template code will refer to the View
object. The same is true for closure-based templates.
We will almost always want to use dynamic data in our templates. To assign a data collection to the View, use the setData() method and either an array or an object. We can then use data elements as if they are properties on the
Recall that $this in the template logic refers to the View object,
so that data assigned to the View can be accessed as properties on $this.
The setData() method will overwrite all existing data in the View object. The addData() method, on the other hand, will merge with existing data in the View object.
Invoking A One-Step View
Now that we have registered a template and assigned some data to the View, we tell the View which template to use, and then invoke the View:
The $output in this case will be something like this:
Using Sub-Templates (aka “Partials”)
Sometimes we will want to split a template up into multiple pieces. We can
render these “partial” template pieces using the render() method in our main template code.
First, we place the sub-template in the view registry (or in the layout registry if it for use in layouts). Then we render() it from inside the main template code. Sub-templates can use any naming scheme we like. Some systems use the convention of prefixing partial templates with an underscore, and the following example will use that convention.
Second, we can pass an array of variables to be extracted into the local scope of the partial template. (The $this variable will always be available regardless.)
For example, let’s split up our browse.php template file so that it uses a sub-template for displaying items.
We extract the item-display code from browse.php into _item.php:
Then we modify browse.php to use the sub-template:
The output will be the same as earlier when we invoke the view.
Alternatively, we can use include or require to execute a
PHP file directly in the current template scope.
Sections are similar to sub-templates (aka “partials”) except that they are captured inline for later use. In general, they are used by view templates to capture output for layout templates.
For example, we can capture output in the view template to a named section …
… and then use that output in a layout template:
In addition, the setSection() method can be used to set the section body directly, instead of capturing it:
Rendering a Two-Step View
To wrap the main content in a layout as part of a two-step view, we register
layout templates with the View and then call setLayout() to pick one of
them for the second step. (If no layout is set, the second step will not be
Let’s say we have already set the browse template above into our view registry. We then set a layout template called default into the layout registry:
The default.php layout template might look like this:
We can then set the view and layout templates on the View object and then invoke it:
The output from the inner view template is automatically retained and becomes available via the getContent() method on the View object. The layout template then calls getContent() to place the inner view results in the outer layout template.
We can also call setLayout() from inside the view template, allowing
us to pick a layout as part of the view logic.
The view template and the layout template both execute inside the same View object. This means:
All data values are shared between the view and the layout. Any data assigned to the view, or modified by the view, is used as-is by the layout.
All helpers are shared between the view and the layout. This sharing situation allows the view to modify data and helpers before the layout is executed.
All section bodies are shared between the view and the layout. A section that is captured from the view template can therefore be used by the layout template.
Closures As Templates
The view and layout registries accept closures as templates. For example, these are closure-based equivlents of the browse.php and _item.php template files above:
When registering a closure-based template, continue to use echo instead of return when generating output. The closure is rebound to the View object, so $this in the closure will refer to the View just as it does in a file-based template.
A bit of extra effort is required with closure-based sub-templates (aka “partials”). Whereas file-based templates automatically extract the passed array of variables into the local scope, a closure-based template must:
Define a function parameter to receive the injected variables (the $vars param in the _item template); and,
Extract the injected variables using extract(). Alternatively, the closure may use the injected variables parameter directly.
Aside from that, closure-based templates work exactly like file-based templates.
Built in Helpers via Aura.Html
Escaping output is absolutely necessary from a security perspective. This package comes with an escape() helper that has four escaping methods:
$this->escape()->html('foo') to escape HTML values
$this->escape()->attr('foo') to escape unquoted HTML attributes
$this->escape()->css('foo') to escape CSS values
Here is a contrived example of the various escape() helper methods:
Unfortunately, escaper functionality is verbose, and can make the template code look cluttered. There are two ways to mitigate this.
The first is to assign the escape() helper to a variable, and then invoke it as a callable. Here is a contrived example of the various escaping methods as callables:
N.b.: In Aura, we generally avoid static methods. However, we feel the tradeoff of less-cluttered templates can be worth using static methods in this one case.
To call the static Escaper methods in a PHP-based template, use the Escaper as a short alias name, then call the static methods on the alias. (If you did not instantiate a HelperLocatorFactory, you will need to prepare the static escaper methods by calling Escaper::setStatic(new Escaper).)
Here is a contrived example of the various static methods:
Use a helper by calling it as a method on the HelperLocator. The available helpers are:
The checkbox type honors the value_unchecked pseudo-attribute as a way to specify a hidden element for the (you guessed it) unchecked value. It also honors the pseudo-element label to place a label after the checkbox.
This element type allows you to generate a single radio input, or multiple radio inputs if you pass an options element.
Helper for a <select> tag with <option> tags. The pseudo-attribute placeholder is honored as a placeholder label when no option is selected. Using the attribute 'multiple' => true will set up a multiple select, and automatically add  to the name if it is not already there.
The helper also supports option groups. If an options array value is itself an array, the key for that element will be used as an <optgroup> label and the array of values will be options under that group.
There are two steps to adding your own custom helpers:
Write a helper class.
Set a factory for that class into the HelperLocator under a service name.
A helper class needs only to implement the __invoke() method.
We suggest extending from Aura\Html\AbstractHelper to get access to indenting,
escaping, etc., but it’s not required.
We are going to create a router helper which can return the router object, and from which we can generate routes from the already defined routes.
Now that we have a helper class, we set a factory for it into the
HelperLocator under a service name.
Therein, we create and return the helper class.
The service name in the HelperLocator doubles as a method name.
This means we can call the helper via $this->router():
Note that we can use any service name for the helper, although it is generally useful to name the service for the helper class, and for a word that can be called as a method.