From ee9efafd05137af72220a766eec5993ff1ac7e77 Mon Sep 17 00:00:00 2001 From: Ore Landau Date: Tue, 6 Nov 2012 12:35:15 +0200 Subject: [PATCH] Improved zend.view.quick-start A variety of fixes in formatting, code examples, uniformity, typos and more. --- .../en/modules/zend.view.quick-start.rst | 282 +++++++++--------- 1 file changed, 136 insertions(+), 146 deletions(-) diff --git a/docs/languages/en/modules/zend.view.quick-start.rst b/docs/languages/en/modules/zend.view.quick-start.rst index 29d112e78..8102bd045 100644 --- a/docs/languages/en/modules/zend.view.quick-start.rst +++ b/docs/languages/en/modules/zend.view.quick-start.rst @@ -8,33 +8,34 @@ Zend\\View Quick Start Overview ======== -``Zend\View`` provides the "View" layer of Zend Framework's MVC system. It is a multi-tiered system allowing a +``Zend\View`` provides the "View" layer of Zend Framework 2's MVC system. It is a multi-tiered system allowing a variety of mechanisms for extension, substitution, and more. The components of the view layer are as follows: -- **Variables containers**, which hold variables and callbacks that you wish to represent in the view. Often-times, - a Variables container will also provide mechanisms for context-specific escaping of variables and more. +- **Variables Containers** hold variables and callbacks that you wish to represent in the view. Often-times, + a Variables Container will also provide mechanisms for context-specific escaping of variables and more. -- **View Models**, which hold Variables containers, specify the template to use, if any, and optionally provide +- **View Models** hold Variables Containers, specify the template to use (if any), and optionally provide rendering options (more on that below). View Models may be nested in order to represent complex structures. -- **Renderers**, which take View Models and provide a representation of them to return. Zend Framework ships three - renderers by default: a "PHP" renderer which utilizes PHP templates in order to generate markup; a JSON renderer; - and a Feed renderer, capable of generating RSS and Atom feeds. +- **Renderers** take View Models and provide a representation of them to return. Zend Framework 2 ships with three + renderers by default: a ``PhpRenderer`` which utilizes PHP templates in order to generate markup, a ``JsonRenderer``, + and a ``FeedRenderer`` for generating RSS and Atom feeds. -- **Resolvers**, which resolve a template name to a resource a Renderer may consume. As an example, a resolver may - take the name "blog/entry" and resolve it to a PHP view script. +- **Resolvers** utilizes Resolver Strategies to resolve a template name to a resource a Renderer may consume. + As an example, a Resolver may take the name "blog/entry" and resolve it to a PHP view script. -- **The View**, which consists of strategies that map the current Request to a Renderer, and strategies for - injecting the Response with the result of rendering. +- The **View** consists of strategies that map the current Request to a Renderer, and strategies for + injecting the result of rendering to the Response. -- **Renderer and Response Strategies**. Renderer Strategies listen to the "renderer" event of the View, and decide - which Renderer should be selected, based on the Request or other criteria. Response strategies are used to inject - the Response object with the results of rendering -- which may also include taking actions such as setting - Content-Type headers. +- **Rendering Strategies** listen to the "renderer" event of the View and decide which Renderer should be selected + based on the Request or other criteria. -Additionally, Zend Framework provides integration with the MVC via a number of event listeners in the +- **Response Strategies** are used to inject the Response object with the results of rendering. + That may also include taking actions such as setting Content-Type headers. + +Additionally, Zend Framework 2 provides integration with the MVC via a number of event listeners in the ``Zend\Mvc\View`` namespace. .. _zend.view.quick-start.usage: @@ -42,20 +43,20 @@ Additionally, Zend Framework provides integration with the MVC via a number of e Usage ===== -This manual section is designed to show you typical usage patterns of the view layer when using it within the Zend -Framework MVC. The assumptions are that you are using :ref:`Dependency Injection `, and that you are using -the :ref:`default MVC view strategies `. +This section of the manual is designed to show you typical usage patterns of the view layer when using it within +the Zend Framework 2 MVC. The assumptions are that you are using :ref:`Dependency Injection ` and the +default MVC view strategies. .. _zend.view.quick-start.usage.config: Configuration ------------- -The default configuration for the framework will typically work out-of-the-box. However, you will still need to -select resolver strategies and configure them, as well as potentially indicate alternate template names for things +The default configuration will typically work out-of-the-box. However, you will still need to +select Resolver Strategies and configure them, as well as potentially indicate alternate template names for things like the site layout, 404 (not found) pages, and error pages. The code snippets below can be added to your configuration to accomplish this. We recommend adding it to a site-specific module, such as the "Application" -module from the framework's "ZendSkeletonApplication", or to one of your autoloaded configurations within the +module from the framework's `ZendSkeletonApplication`_, or to one of your autoloaded configurations within the ``config/autoload/`` directory. .. code-block:: php @@ -70,7 +71,7 @@ module from the framework's "ZendSkeletonApplication", or to one of your autoloa // 404 page ("error/404"), resolving them to view scripts. 'template_map' => array( 'application/index/index' => __DIR__ . '/../view/application/index/index.phtml', - 'layout/layout' => __DIR__ . '/../view/layout/layout.phtml', + 'site/layout' => __DIR__ . '/../view/layout/layout.phtml', 'error/index' => __DIR__ . '/../view/error/index.phtml', 'error/404' => __DIR__ . '/../view/error/404.phtml', ), @@ -79,7 +80,7 @@ module from the framework's "ZendSkeletonApplication", or to one of your autoloa // are then searched in LIFO order (it's a stack) for the requested // view script. This is a nice solution for rapid application // development, but potentially introduces performance expense in - // production due to the number of stat calls necessary. + // production due to the number of static calls necessary. // // The following adds an entry pointing to the view directory // of the current module. Make sure your keys differ between modules @@ -88,8 +89,13 @@ module from the framework's "ZendSkeletonApplication", or to one of your autoloa 'application' => __DIR__ . '/../view', ), - // Set the template name for layouts. - 'layout' => 'layout/layout', + // Set the template name for the site's layout. + // + // By default, the MVC's default Rendering Strategy uses the + // template name "layout/layout" for the site's layout. + // Here, we tell it to use the "site/layout" template, + // which we mapped via the TemplateMapResolver above. + 'layout' => 'site/layout', // By default, the MVC registers an "exception strategy", which is // triggered when a requested action raises an exception; it creates @@ -104,17 +110,17 @@ module from the framework's "ZendSkeletonApplication", or to one of your autoloa // Another strategy the MVC registers by default is a "route not // found" strategy. Basically, this gets triggered if (a) no route // matches the current request, (b) the controller specified in the - // route match cannot be found in the locator, (c) the controller + // route match cannot be found in the service locator, (c) the controller // specified in the route match does not implement the DispatchableInterface // interface, or (d) if a response from a controller sets the // response status to 404. // // The default template used in such situations is "error", just - // like the exception strategy. Let's tell it to use the "error/404" - // template, (which we mapped via the TemplateMapResolver, above). + // like the exception strategy. Here, we tell it to use the "error/404" + // template (which we mapped via the TemplateMapResolver, above). // // You can opt in to inject the reason for a 404 situation; see the - // various Application::ERROR_* constants for a list of values. + // various `Application::ERROR_*`_ constants for a list of values. // Additionally, a number of 404 situations derive from exceptions // raised during routing or dispatching. You can opt-in to display // these. @@ -128,7 +134,7 @@ module from the framework's "ZendSkeletonApplication", or to one of your autoloa Controllers and View Models --------------------------- -``Zend\View\View`` consumes ``ViewModels``, passing them to the selected renderer. Where do you create these, +``Zend\View\View`` consumes ``ViewModel``s, passing them to the selected renderer. Where do you create these, though? The most explicit way is to create them in your controllers and return them. @@ -153,25 +159,25 @@ The most explicit way is to create them in your controllers and return them. } } -This sets a "message" variable in the view model, and sets the template name "foo/baz-bat/do-something-crazy". The view model is -then returned. +This sets a "message" variable in the View Model, and sets the template name "foo/baz-bat/do-something-crazy". +The View Model is then returned. -Considering that in most cases, you'll likely have a template name based on the module namespace, controller, and action, and simply -be passing some variables, could this be made simpler? Definitely. +In most cases, you'll likely have a template name based on the module namespace, controller, and action. +Considering that, and if you're simply passing some variables, could this be made simpler? Definitely. The MVC registers a couple of listeners for controllers to automate this. The first will look to see if you -returned an associative array from your controller; if so, it will create a view model and inject this associative -array as the view variables container; this view model then replaces the MVC event's result. It will also look to -see if you returned nothing or null; if so, it will create a view model without any variables attached; this view -model also replaces the MVC event's result. +returned an associative array from your controller; if so, it will create a View Model and make this associative +array the Variables Container; this View Model then replaces the :ref:`MvcEvent `'s result. +It will also look to see if you returned nothing or null; if so, it will create a View Model without any variables +attached; this View Model also replaces the ``MvcEvent``'s result. -The second listener checks to see if the MVC event result is a view model, and, if so, if it has a template -associated with it. If not, it will inspect the controller matched during routing to determine the module namespace and the controller class name, and, if available, it's "action" -parameter in order to create a template name. This will be "module/controller/action", with the module, controller, and action -normalized to lowercase, dash-separated words. +The second listener checks to see if the ``MvcEvent`` result is a View Model, and, if so, if it has a template +associated with it. If not, it will inspect the controller matched during routing to determine the module namespace +and the controller class name, and, if available, it's "action" parameter in order to create a template name. +This will be "module/controller/action", all normalized to lowercase, dash-separated words. -As an example, the controller ``Foo\Controller\BazBatController``, with action "doSomethingCrazy", would be mapped -to the template ``foo/baz-bat/do-something-crazy``. +As an example, the controller ``Foo\Controller\BazBatController`` with action "doSomethingCrazyAction", would be mapped +to the template ``foo/baz-bat/do-something-crazy``. As you can see, the words "Controller" and "Action" are omitted. In practice, that means our previous example could be re-written as follows: @@ -192,14 +198,20 @@ In practice, that means our previous example could be re-written as follows: } } -The above method will likely work for a majority of use cases. When you need to specify a different template, -explicitly create and return a view model, and specify the template manually. +The above method will likely work for the majority of use cases. When you need to specify a different template, +explicitly create and return a View Model and specify the template manually, as in the first example. + +.. _zend.view.quick-start.usage.nesting: + +Nesting View Models +------------------- -The other use case you may have for explicit view models is if you wish to **nest** view models. Use cases include -if you want to render templates to include within the main view you return. +The other use case you may have for setting explicit View Models is if you wish to **nest** them. +In other words, you might want to render templates to be included within the main View you return. + +As an example, you may want the View from an action to be one primary section that includes both an "article" and +a couple of sidebars; one of the sidebars may include content from multiple Views as well: -As an example, you may want the view from the action to be one primary section that includes both an "article" and -a couple of sidebars; one of the sidebars may include content from multiple views as well. .. code-block:: php :linenos: @@ -239,22 +251,22 @@ a couple of sidebars; one of the sidebars may include content from multiple view } } -The above will create and return a view model specifying the template "content/article". When the view is rendered, -it will render three child views, the ``$articleView``, ``$primarySidebarView``, and ``$secondarySidebarView``; +The above will create and return a View Model specifying the template "content/article". When the View is rendered, +it will render three child Views, the ``$articleView``, ``$primarySidebarView``, and ``$secondarySidebarView``; these will be captured to the ``$view``'s "article", "sidebar_primary", and "sidebar_secondary" variables, respectively, so that when it renders, you may include that content. Additionally, the ``$secondarySidebarView`` -will include an additional view model, ``$sidebarBlockView``, which will be captured to its "block" view variable. +will include an additional View Model, ``$sidebarBlockView``, which will be captured to its "block" view variable. To better visualize this, let's look at what the final content might look like, with comments detailing where each nested view model is injected. -Here are the templates: +Here are the templates, rendered based on a 12-column grid: .. code-block:: php :linenos: - -
+ +
article ?> sidebar_primary ?> @@ -263,29 +275,29 @@ Here are the templates:
- -
+
escapeHtml('article') ?>
- - -
+ + +
sidebar content...
- -
+ +
block ?>
- +
block content...
@@ -295,24 +307,24 @@ And here is the aggregate, generated content: .. code-block:: html :linenos: - -
- +
+ -
+
Lorem ipsum ....
- -
+
sidebar content...
- -
-
block content... @@ -320,53 +332,30 @@ And here is the aggregate, generated content:
-As you can see, you can achieve very complex markup using nested views, while simultaneously keeping the details of -rendering isolated from the request/reponse lifecycle of the controller. +As you can see, you can achieve very complex markup using nested Views, while simultaneously keeping the details of +rendering isolated from the Request/Response lifecycle of the controller. .. _zend.view.quick-start.usage.layouts: Dealing with Layouts -------------------- -Most sites enforce a cohesive look-and-feel, which we typically call the site "layout". The site layout includes -the default stylesheets and JavaScript necessary, if any, as well as the basic markup structure into which all site +Most sites enforce a cohesive look-and-feel which we typically call the site's "layout". It includes the default +stylesheets and JavaScript necessary, if any, as well as the basic markup structure into which all site content will be injected. -Within Zend Framework, layouts are handled via nesting of view models (see the :ref:`previous example -` for examples of view model nesting). The MVC event composes a View Model -which acts as the "root" for nested view models, as such, it should contain the skeleton, or layout, template for -the site (configuration refers to this as the "layoutTemplate"). All other content is then rendered and captured to -view variables of this root view model. - -The default rendering strategy sets the layout template as "layout". To change this, you can add some configuration -for the Dependency Injector. - -.. code-block:: php - :linenos: +Within Zend Framework 2, layouts are handled via nesting of View Models (see the :ref:`previous example +` for examples of View Model nesting). The ``Zend\Mvc\View\Http\ViewManager`` +composes a View Model which acts as the "root" for nested View Models. As such, it should contain the skeleton +(or layout) template for the site. All other content is then rendered and captured to view variables of this root +View Model. - return array( - 'di' => array( - 'instance' => array( - // The above lines will likely already be present; it's the following - // definitions that you will want to ensure are present within the DI - // instance configuration. - - // By default, the MVC's default rendering strategy uses the - // template name "layout" for the site layout. Let's tell it to use - // "site/layout" (which we mapped via the TemplateMapResolver, - // above). - 'Zend\Mvc\View\DefaultRenderingStrategy' => array( - 'parameters' => array( - 'baseTemplate' => 'site/layout', - ), - ), - ), - ), - ); +The ``ViewManager`` sets the layout template as "layout/layout" by default. To change this, you can add some +configuration to the "view_manager" area of your :ref:`configuration `. -A listener on the controllers, ``Zend\Mvc\View\InjectViewModelListener``, will take a view model returned from a -controller and inject it as a child of the root (layout) view model. By default, view models will capture to the -"content" variable of the root view model. This means you can do the following in your layout view script: +A listener on the controllers, ``Zend\Mvc\View\Http\InjectViewModelListener``, will take a View Model returned from a +controller and inject it as a child of the root (layout) View Model. By default, View Models will capture to the +"content" variable of the root View Model. This means you can do the following in your layout view script: .. code-block:: php :linenos: @@ -380,7 +369,7 @@ controller and inject it as a child of the root (layout) view model. By default, -If you want to specify a different view variable for which to capture, explicitly create a view model in your +If you want to specify a different View variable for which to capture, explicitly create a view model in your controller, and set its "capture to" value: .. code-block:: php @@ -409,8 +398,8 @@ controller, and set its "capture to" value: There will be times you don't want to render a layout. For example, you might be answering an API call which expects JSON or an XML payload, or you might be answering an XHR request that expects a partial HTML payload. The simplest way to do this is to explicitly create and return a view model from your controller, and mark it as -"terminal", which will hint to the MVC listener that normally injects the returned view model into the layout view -model to instead replace the layout view model. +"terminal", which will hint to the MVC listener that normally injects the returned View Model into the layout View +Model, to instead replace the layout view model. .. code-block:: php :linenos: @@ -428,17 +417,17 @@ model to instead replace the layout view model. 'message' => 'Hello world', )); - // Disable layouts; use this view model in the MVC event instead + // Disable layouts; `MvcEvent` will use this View Model instead $view->setTerminal(true); return $view; } } -:ref:`When discussing controllers and view models `, we detailed a nested -view model which contained an article and sidebars. Sometimes, you may want to provide additional view models to +:ref:`When discussing nesting View Models `, we detailed a nested +View Model which contained an article and sidebars. Sometimes, you may want to provide additional View Models to the layout, instead of nesting in the returned layout. This may be done by using the "layout" controller plugin, -which returns the root view model; you can then call the same ``addChild()`` method on it as we did in that +which returns the root View Model. You can then call the same ``addChild()`` method on it as we did in that previous example. .. code-block:: php @@ -469,11 +458,12 @@ previous example. } You could also use this technique to select a different layout, by simply calling the ``setTemplate()`` method of -the layout view model. +the layout View Model: .. code-block:: php :linenos: + //In a controller namespace Content\Controller; use Zend\Mvc\Controller\AbstractActionController; @@ -497,13 +487,15 @@ the layout view model. } Sometimes, you may want to access the layout from within your actual view scripts when using the ``PhpRenderer``. -Reasons might include wanting to change the layout template, or wanting to access or inject layout view variables. -Similar to controllers, you can use the "layout" view plugin/helper. If you provide a string argument to it, you -will change the template; if you provide no arguments the root layout view model is returned. +Reasons might include wanting to change the layout template or wanting to either access or inject layout view variables. +Similar to the "layout" controller plugin, you can use the "layout" View Helper. If you provide a string argument to it, +you will change the template; if you provide no arguments, the root layout View Model is returned. .. code-block:: php :linenos: + //In a view script + // Change the layout: $this->layout('alternate/layout'); // OR $this->layout()->setTemplate('alternate/layout'); @@ -521,11 +513,9 @@ will change the template; if you provide no arguments the root layout view model // Set a layout variable $this->layout()->footer = $this->render('article/footer'); -Commonly, you may want to alter the layout based on the module currently selected. - -Another frequently requested feature is the ability to change a layout based on the current **module**. This +Commonly, you may want to alter the layout based on the current **module**. This requires (a) detecting if the controller matched in routing belongs to this module, and then (b) changing the -template of the view model. +template of the View Model. The place to do these actions is in a listener. It should listen either to the "route" event at low (negative) priority, or on the "dispatch" event, at any priority. Typically, you will register this during the bootstrap @@ -542,14 +532,14 @@ event. { // Register a dispatch event $app = $e->getParam('application'); - $app->getEventManager()->attach('dispatch', array($this, 'setLayout'), -100); + $app->getEventManager()->attach('dispatch', array($this, 'setLayout')); } public function setLayout($e) { $matches = $e->getRouteMatch(); $controller = $matches->getParam('controller'); - if (0 !== strpos($controller, __NAMESPACE__, 0)) { + if (false !== strpos($controller, __NAMESPACE__)) { // not a controller from this module return; } @@ -567,14 +557,14 @@ Creating and Registering Alternate Rendering and Response Strategies ``Zend\View\View`` does very little. Its workflow is essentially to martial a ``ViewEvent``, and then trigger two events, "renderer" and "response". You can attach "strategies" to these events, using the methods -``addRendererStrategy()`` and ``addResponseStrategy()``, respectively. A "renderer strategy" investigates the -Request object (or any other criteria) in order to select a renderer (or fail to select one). A "response strategy" +``addRenderingStrategy()`` and ``addResponseStrategy()``, respectively. A Rendering Strategy investigates the +Request object (or any other criteria) in order to select a Renderer (or fail to select one). A Response Strategy determines how to populate the Response based on the result of rendering. -Zend Framework ships with three rendering/response strategies that you can use within your application. +Zend Framework 2 ships with three Rendering and Response Strategies that you can use within your application. - ``Zend\View\Strategy\PhpRendererStrategy``. This strategy is a "catch-all" in that it will always return the - ``Zend\View\Renderer\PhpRenderer``, and populate the Response body with the results of rendering. + ``Zend\View\Renderer\PhpRenderer`` and populate the Response body with the results of rendering. - ``Zend\View\Strategy\JsonStrategy``. This strategy inspects the Accept HTTP header, if present, and determines if the client has indicated it accepts an "application/json" response. If so, it will return the @@ -587,10 +577,9 @@ Zend Framework ships with three rendering/response strategies that you can use w what was matched. Its Response strategy will populate the Response body with the generated feed, as well as set a Content-Type header with the appropriate value based on feed type. -By default, only the ``PhpRendererStrategy`` is registered, meaning you will need to register the other strategies +By default, only the ``PhpRendererStrategy`` is registered, meaning you will need to register the other Strategies yourself if you want to use them. Additionally, it means that you will likely want to register these at higher -priority to ensure they match before the ``PhpRendererStrategy``. As an example, let's register the -``JsonStrategy``. +priority to ensure they match before the ``PhpRendererStrategy``. As an example, let's register the ``JsonStrategy``: .. code-block:: php :linenos: @@ -603,7 +592,7 @@ priority to ensure they match before the ``PhpRendererStrategy``. As an example, { // Register a "render" event, at high priority (so it executes prior // to the view attempting to render) - $app = $e->getParam('application'); + $app = $e->getApplication(); $app->getEventManager()->attach('render', array($this, 'registerJsonStrategy'), 100); } @@ -625,7 +614,7 @@ The above will register the ``JsonStrategy`` with the "render" event, such that What if you want this to happen only in specific modules, or specific controllers? One way is similar to the last example in the :ref:`previous section on layouts `, where we detailed changing -the layout for a specific module. +the layout for a specific module: .. code-block:: php :linenos: @@ -645,7 +634,7 @@ the layout for a specific module. { $matches = $e->getRouteMatch(); $controller = $matches->getParam('controller'); - if (0 !== strpos($controller, __NAMESPACE__, 0)) { + if (false !== strpos($controller, __NAMESPACE__)) { // not a controller from this module return; } @@ -665,11 +654,11 @@ the layout for a specific module. } } -While the above examples detail using the JSON strategy, the same could be done for the ``FeedStrategy``. +While the above examples detail using the ``JsonStrategy``, the same could be done for the ``FeedStrategy``. -What if you want to use a custom renderer? or if your app might allow a combination of JSON, Atom feeds, and HTML? -At this point, you'll need to create your own custom strategies. Below is an example that more appropriately loops -through the HTTP Accept header, and selects the appropriate renderer based on what is matched first. +What if you want to use a custom renderer? Or if your app might allow a combination of JSON, Atom feeds, and HTML? +At this point, you'll need to create your own custom strategies. Below is an example that appropriately loops +through the HTTP Accept header, and selects the appropriate Renderer based on what is matched first. .. code-block:: php :linenos: @@ -788,4 +777,5 @@ This strategy would be registered just as we demonstrated registering the ``Json need to define DI configuration to ensure the various renderers are injected when you retrieve the strategy from the application's locator instance. - +.. _`ZendSkeletonApplication`: https://github.com/zendframework/ZendSkeletonApplication +.. _`Application::ERROR_*`: https://github.com/zendframework/zf2/blob/master/library/Zend/Mvc/Application.php