Caution
The documentation you are viewing is for an older version of this component.
Switch to the latest (v3) version.
Templating
In This Article
Using zend-view
zend-view provides a native PHP
template system via its PhpRenderer
, and is maintained by Zend Framework. It
provides:
- Layout facilities.
- Helpers for escaping, and the ability to provide custom helper extensions.
We provide a TemplateRendererInterface wrapper for zend-view's
PhpRenderer
via Zend\Expressive\ZendView\ZendViewRenderer
.
Installing zend-view
To use the zend-view wrapper, you must first install the zend-view integration:
$ composer require zendframework/zend-expressive-zendviewrenderer
Using the wrapper
If instantiated without arguments, Zend\Expressive\ZendView\ZendViewRenderer
will create
an instance of the PhpRenderer
, which it will then proxy to.
use Zend\Expressive\ZendView\ZendViewRenderer;
$renderer = new ZendViewRenderer();
Alternately, you can instantiate and configure the engine yourself, and pass it
to the Zend\Expressive\ZendView\ZendViewRenderer
constructor:
use Zend\Expressive\ZendView\ZendViewRenderer;
use Zend\View\Renderer\PhpRenderer;
use Zend\View\Resolver;
// Create the engine instance:
$renderer = new PhpRenderer();
// Configure it:
$resolver = new Resolver\AggregateResolver();
$resolver->attach(
new Resolver\TemplateMapResolver(include 'config/templates.php'),
100
);
$resolver->attach(
(new Resolver\TemplatePathStack())
->setPaths(include 'config/template_paths.php')
);
$renderer->setResolver($resolver);
// Inject:
$renderer = new ZendViewRenderer($renderer);
Namespaced path resolving
Expressive defines a custom zend-view resolver,
Zend\Expressive\ZendView\NamespacedPathStackResolver
. This resolver provides the ability to segregate paths by namespace, and later resolve a template according to the namespace, using thenamespace::template
notation required ofTemplateRendererInterface
implementations.The
ZendView
adapter ensures that:
- An
AggregateResolver
is registered with the renderer. If the registered resolver is not anAggregateResolver
, it creates one and adds the original resolver to it.- A
NamespacedPathStackResolver
is registered with theAggregateResolver
, at a low priority (0), ensuring attempts to resolve hit it later.With resolvers such as the
TemplateMapResolver
, you can also resolve namespaced templates, mapping them directly to the template on the filesystem that matches; adding such a resolver can be a nice performance boost!
Layouts
Unlike the other supported template engines, zend-view does not support layouts out-of-the-box. Expressive abstracts this fact away, providing two facilities for doing so:
- You may pass a layout template name or
Zend\View\Model\ModelInterface
instance representing the layout as the second argument to the constructor. - You may pass a "layout" parameter during rendering, with a value of either a
layout template name or a
Zend\View\Model\ModelInterface
instance representing the layout. Passing a layout this way will override any layout provided to the constructor.
In each case, the zend-view implementation will do a depth-first, recursive render in order to provide content within the selected layout.
- Since 1.3: You may also pass a boolean
false
value to eitheraddDefaultParam()
or via the template variables for thelayout
key; doing so will disable the layout.
Layout name passed to constructor
use Zend\Expressive\ZendView\ZendViewRenderer;
// Create the engine instance with a layout name:
$renderer = new ZendViewRenderer(null, 'layout::layout');
Layout view model passed to constructor
use Zend\Expressive\ZendView\ZendViewRenderer;
use Zend\View\Model\ViewModel;
// Create the layout view model:
$layout = new ViewModel([
'encoding' => 'utf-8',
'cssPath' => '/css/prod/',
]);
$layout->setTemplate('layout::layout');
// Create the engine instance with the layout:
$renderer = new ZendViewRenderer(null, $layout);
Provide a layout name when rendering
$content = $renderer->render('blog/entry', [
'layout' => 'layout::blog',
'entry' => $entry,
]);
Provide a layout view model when rendering
use Zend\View\Model\ViewModel;
// Create the layout view model:
$layout = new ViewModel([
'encoding' => 'utf-8',
'cssPath' => '/css/blog/',
]);
$layout->setTemplate('layout::layout');
$content = $renderer->render('blog/entry', [
'layout' => $layout,
'entry' => $entry,
]);
Helpers
Expressive provides overrides of specific view helpers in order to better integrate with PSR-7. These include:
Zend\Expressive\ZendView\UrlHelper
. This helper consumes the application'sZend\Expressive\Router\RouterInterface
instance in order to generate URIs. Its signature is:url($routeName, array $routeParams = [], array $queryParams = [], $fragmentIdentifier = null, array $options = [])
Zend\Expressive\ZendView\ServerUrlHelper
. This helper consumes the URI from the application's request in order to provide fully qualified URIs. Its signature is:serverUrl($path = null)
.
To use this particular helper, you will need to inject it with the request URI somewhere within your application:
$serverUrlHelper->setUri($request->getUri());
We recommend doing this within a pre-pipeline middleware.
Recommendations
We recommend the following practices when using the zend-view adapter:
- If using a layout, create a factory to return the layout view model as a service; this allows you to inject it into middleware and add variables to it.
- While we support passing the layout as a rendering parameter, be aware that if you change engines, this may not be supported.
Found a mistake or want to contribute to the documentation? Edit this page on GitHub!