Documented namespacing features

Author: weierophinney

doc/book/template/interface.md

@@ -10,19 +10,34 @@ namespace Zend\Expressive\Template;
 interface TemplateInterface
 {
     /**
+     * Render a template, optionally with parameters.
+     *
+     * Implementations MUST support the `namespace::template` naming convention,
+     * and allow omitting the filename extension.
+     *
      * @param string $name
      * @param array|object $params
      * @return string
      */
     public function render($name, $params = []);
 
     /**
+     * Add a template path to the engine.
+     *
+     * Adds a template path, with optional namespace the templates in that path
+     * provide.
+     *
      * @param string $path
      * @param string $namespace
      */
     public function addPath($path, $namespace = null);
 
     /**
+     * Add a template path to the engine.
+     *
+     * Adds a template path, with optional namespace the templates in that path
+     * provide.
+     *
      * @return TemplatePath[]
      */
     public function getPaths();
@@ -34,13 +49,19 @@ interface TemplateInterface
 > Unfortunately, namespace syntax varies between different template engine
 > implementations. As an example:
 >
-> - Plates uses the syntax `namespace::template`
-> - Twig uses the syntax `@namespace/template`
-> - zend-view does not natively support namespaces; we mimic it using normal
->   directory syntax.
+> - Plates uses the syntax `namespace::template`.
+> - Twig uses the syntax `@namespace/template`.
+> - zend-view does not natively support namespaces, though custom resolvers
+>   can provide the functionality.
 >
-> As such, it's not entirely possible to have engine-agnostic templates if you
-> use namespaces.
+> To make different engines compatible, we require implementations to support
+> the syntax `namespace::template` (where `namespace::` is optional) when
+> rendering. Additionally, we require that engines allow omitting the filename
+> suffix.
+>
+> When using a `TemplateInterface` implementation, feel free to use namespaced
+> templates, and to omit the filename suffix; this will make your code portable
+> and allow it to use alternate template engines.
 
 
 ## Paths
@@ -53,10 +74,10 @@ the actual template. You may use the `addPath()` method to do so:
 $template->addPath('templates');
 ```
 
-Many template engines further allow *namespacing* templates; when adding a path,
-you specify the template *namespace* that it fulfills, and the engine will only
-return a template from that path if the namespace provided matches the namespace
-for the path.
+Template engines adapted for zend-expressive are also required to allow
+*namespacing* templates; when adding a path, you specify the template
+*namespace* that it fulfills, and the engine will only return a template from
+that path if the namespace provided matches the namespace for the path.
 
 ```php
 // Resolves to a path registered with the namespace "error";
@@ -81,9 +102,13 @@ of a template as the first argument:
 $content = $template->render('foo');
 ```
 
-One key reason to use templates, however, is to dynamically provide data to
-inject in the template. You may do so by passing either an associative array or
-an object as the second argument to `render()`:
+You can specify a namespaced template using the syntax `namespace::template`;
+the `template` segment of the template name may use additional directory
+separators when necessary.
+
+One key reason to use templates is to dynamically provide data to inject in the
+template. You may do so by passing either an associative array or an object as
+the second argument to `render()`:
 
 ```php
 $content = $template->render('message', [

doc/book/template/intro.md

@@ -6,9 +6,22 @@ very specific to the project and/or organization.
 
 We do, however, provide abstraction for templating via the interface
 `Zend\Expressive\Template\TemplateInterface`, which allows you to write
-middleware that is engine-agnostic. In this documentation, we'll detail the
-features of this interface, the various implementations we provide, and how you
-can configure, inject, and consume templating in your middleware.
+middleware that is engine-agnostic. For Expressive, this means:
+
+- All adapters MUST support template namespacing. Namespaces MUST be referenced
+  using the notation `namespace::template` when rendering.
+- Adapters MUST allow rendering templates that omit the extension; they will, of
+  course, resolve to whatever default extension they require (or as configured).
+- Adapters SHOULD allow passing an extension in the template name, but how that
+  is handled is left up to the adapter.
+- Adapters SHOULD abstract layout capabilities. Many templating systems provide
+  this out of the box, or similar, compatible features such as template
+  inheritance. This should be transparent to end-users; they should be able to
+  simply render a template and assume it has the full content to return.
+
+In this documentation, we'll detail the features of this interface, the various
+implementations we provide, and how you can configure, inject, and consume
+templating in your middleware.
 
 We currently support:
 

doc/book/template/zend-view.md

@@ -56,6 +56,26 @@ $zendView->setResolver($resolver);
 $templates = new ZendView($zendView);
 ```
 
+> ### Namespaced path resolving
+>
+> Expressive defines a custom zend-view resolver,
+> `Zend\Expressive\Template\ZendView\NamespacedPathStackResolver`. This resolver
+> provides the ability to segregate paths by namespace, and later resolve a
+> template according to the namespace, using the `namespace::template` notation
+> required of `TemplateInterface` implementations.
+>
+> The ZendView adapter ensures that:
+>
+> - An AggregateResolver is registered with the renderer. If the registered
+>   resolver is not an AggregateResolver, it creates one and adds the original
+>   resolver to it.
+> - A NamespacedPathStackResolver is registered with the AggregateResolver, 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

src/Template/TemplateInterface.php

@@ -15,19 +15,31 @@
 interface TemplateInterface
 {
     /**
+     * Render a template, optionally with parameters.
+     *
+     * Implementations MUST support the `namespace::template` naming convention,
+     * and allow omitting the filename extension.
+     *
      * @param string $name
      * @param array|object $params
      * @return string
      */
     public function render($name, $params = []);
 
     /**
+     * Add a template path to the engine.
+     *
+     * Adds a template path, with optional namespace the templates in that path
+     * provide.
+     *
      * @param string $path
      * @param string $namespace
      */
     public function addPath($path, $namespace = null);
 
     /**
+     * Retrieve configured paths from the engine.
+     *
      * @return TemplatePath[]
      */
     public function getPaths();