Skip to content
This repository was archived by the owner on Jan 29, 2020. It is now read-only.

Update docs to reflect template map resolver change in v3 #155

Merged
merged 1 commit into from
Jun 11, 2016
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 11 additions & 8 deletions doc/book/migration/to-v3-0.md
Original file line number Diff line number Diff line change
Expand Up @@ -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\`).
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The double-backslashes were actually required to ensure that the backtick isn't considered a literal. 😄 Re-instating during merge.

Copy link
Member Author

@Xerkus Xerkus Jun 11, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@weierophinney I noticed that github markdown renderer does not treat backslash as special character in backticked strings and docs site appears to be using same renderer:
https://zendframework.github.io/zend-mvc/migration/to-v3-0/#zendmvcviewinjecttemplatelistener

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'll double check. Syntastic was flashing it in my editor, and I've run
into issues before.
On Jun 11, 2016 5:50 PM, "Aleksei Khudiakov" notifications@github.com
wrote:

In doc/book/migration/to-v3-0.md
#155 (comment):

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\).

I noticed that github markdown renderer does not treat backslash as
special character in backticked strings and docs site appears to be using
same renderer:

https://zendframework.github.io/zend-mvc/migration/to-v3-0/#zendmvcviewinjecttemplatelistener


You are receiving this because you modified the open/close state.
Reply to this email directly, view it on GitHub
https://github.com/zendframework/zend-mvc/pull/155/files/157d3e194a080971b1c8c8d7f28d5c17d7ce15ef#r66712875,
or mute the thread
https://github.com/notifications/unsubscribe/AABlV4s6jUGnD36egpcb9L46xJccMRI-ks5qKzvBgaJpZM4IvKn3
.

- 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
Expand All @@ -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
Expand Down
30 changes: 10 additions & 20 deletions doc/book/quick-start.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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.
Expand Down
1 change: 0 additions & 1 deletion doc/book/services.md
Original file line number Diff line number Diff line change
Expand Up @@ -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' => [
],

Expand Down