Merge pull request #155 from Xerkus/fix-docs

Update docs to reflect template map resolver change in v3

Author: weierophinney

doc/book/migration/to-v3-0.md

@@ -412,22 +412,22 @@ the section above on [dependency reduction](#dependency-reduction).
 
 ## Zend\Mvc\View\InjectTemplateListener
 
-The `InjectTemplateListener` attempts to map a controller *service* name to a
+The `InjectTemplateListener` attempts to map a controller name to a
 template using a variety of heuristics, including an explicit map provided
-during configuration, or auto-detection based on the service name. 
+during configuration, or auto-detection based on the controller class name.
 
 In version 2, the autodetection took into consideration the `__NAMESPACE__`
-provided in routing configuration, and would omit the module subnamespace if a
-match was found. This caused issues when multiple modules shared a top-level
-namespace (e.g., `ZF\Apigility` and `ZF\Apigility\Admin`) if each had a
-controller with the same name.
+route match parameter to derive subnamespaces or would omit them completely if
+`__NAMESPACE__` is not present. This caused issues when multiple modules shared
+a top-level namespace (e.g., `ZF\Apigility` and `ZF\Apigility\Admin`) if each
+had a controller with the same name.
 
 To avoid naming conflicts, version 3 removes this aspect of autodetection, and
 instead provides exactly one workflow for mapping:
 
 - Strip the `Controller` subnamespace, if present (e.g.,
-  the namespace `Application\Controller\\` is normalized to
-  `Application\\`).
+  the namespace `Application\Controller\` is normalized to
+  `Application\`).
 - Strip the `Controller` suffix in the class name, if present (e.g.,
   `IndexController` is normalized to `Index`).
 - Inflect CamelCasing to dash-separated (e.g., `ShowUsers` becomes
@@ -439,6 +439,9 @@ As a full example, the controller service name
 `test-something/with/camel-case`, regardless of the `__NAMESPACE__` value
 provided in routing configuration.
 
+Similar behavior in version 2 could be achieved with namespace whitelisting in
+controller to template map
+
 ## Zend\Mvc\View\SendResponseListener
 
 `Zend\Mvc\View\SendResponseListener` was deprecated with the 2.2 release, and

doc/book/quick-start.md

@@ -146,7 +146,7 @@ So, what are we doing here?
 
 We return a `ViewModel`. The view layer will use this when rendering the view,
 pulling variables and the template name from it. By default, you can omit the
-template name, and it will resolve to "lowercase-controller-name/lowercase-action-name".
+template name, and it will resolve to "lowercase-module-name/lowercase-controller-name/lowercase-action-name".
 However, you can override this to specify something different by calling
 `setTemplate()` on the `ViewModel` instance. Typically, templates will resolve
 to files with a ".phtml" suffix in your module's `view` directory.
@@ -177,34 +177,24 @@ That's it. Save the file.
 ## View scripts for module names with subnamespaces
 
 As per PSR-0, modules should be named following the rule: `<Vendor Name>\<Namespace>\*`.
-However, the default controller class to template mapping does not work very
-well with those: it will remove subnamespace.
 
-To address that issue, new mapping rules were introduced with version 2.3.0. To
-maintain backwards compatibility, that mapping is not enabled by default. To
-enable it, you need to add your module namespace to a whitelist in your module
-configuration:
+Since version 3.0 default template name resolver uses fully qualified controller
+class name, stripping only `\Controller\` subnamespace, if present.
+For example, `AwesomeMe\MyModule\Controller\HelloWorldController` is resolved
+to template name `awesome-me/my-module/hello-world`.
+
+For prior versions default was to strip subnamespaces but optional mapping rules
+allowed to whitelist namespaces in module configuration to enable current
+resolver behavior:
 
 ```php
 'view_manager' => array(
-    // Controller namespace to template map
-    // or whitelisting for controller FQCN to template mapping
     'controller_map' => array(
-        '<Module\Name>' => true,
+        '<AwesomeMe\MyModule>' => true,
     ),
 ),
 ```
 
-Once you have, you can create the directory `view/<module>/<name>/hello`. Inside
-that directory, create a file named `world.phtml`. Inside that, paste the
-following:
-
-```php
-<h1>Greetings!</h1>
-
-<p>You said "<?php echo $this->escapeHtml($message) ?>".</p>
-```
-
 ## Create a Route
 
 Now that we have a controller and a view script, we need to create a route to it.

doc/book/services.md

@@ -753,7 +753,6 @@ return [
         'default_template_suffix' => $templateSuffix, // e.g. 'php'
 
         // Controller namespace to template map
-        // or whitelisting for controller FQCN to template mapping
         'controller_map' => [
         ],