documentation/manual/en/module_specs/Zend_Controller-ActionHelpers-ViewRenderer.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect3 id="zend.controller.actionhelpers.viewrenderer">
   4     <title>ViewRenderer</title>
   5
   6     <sect4 id="zend.controller.actionhelper.viewrenderer.introduction">
   7         <title>Introduction</title>
   8
   9         <para>
  10             The <emphasis>ViewRenderer</emphasis> helper is designed to satisfy the
  11             following goals:
  12         </para>
  13
  14         <itemizedlist>
  15             <listitem>
  16                 <para>
  17                     Eliminate the need to instantiate view objects within
  18                     controllers; view objects will be automatically registered
  19                     with the controller.
  20                 </para>
  21             </listitem>
  22
  23             <listitem>
  24                 <para>
  25                     Automatically set view script, helper, and filter paths
  26                     based on the current module, and automatically associate
  27                     the current module name as a class prefix for helper and
  28                     filter classes.
  29                 </para>
  30             </listitem>
  31
  32             <listitem>
  33                 <para>
  34                     Create a globally available view object for all dispatched
  35                     controllers and actions.
  36                 </para>
  37             </listitem>
  38
  39             <listitem>
  40                 <para>
  41                     Allow the developer to set default view rendering options
  42                     for all controllers.
  43                 </para>
  44             </listitem>
  45
  46             <listitem>
  47                 <para>
  48                     Add the ability to automatically render a view script with
  49                     no intervention.
  50                 </para>
  51             </listitem>
  52
  53             <listitem>
  54                 <para>
  55                     Allow the developer to create her own specifications for
  56                     the view base path and for view script paths.
  57                 </para>
  58             </listitem>
  59         </itemizedlist>
  60
  61         <note>
  62             <para>
  63                 If you perform a <methodname>_forward()</methodname>,
  64                 <methodname>redirect()</methodname>, or
  65                 <methodname>render()</methodname> manually, autorendering will not occur, as
  66                 by performing any of these actions you are telling the
  67                 <emphasis>ViewRenderer</emphasis> that you are determining your own
  68                 output.
  69             </para>
  70         </note>
  71
  72         <note>
  73             <para>
  74                 The <emphasis>ViewRenderer</emphasis> is enabled by default. You may
  75                 disable it via the front controller <emphasis>noViewRenderer</emphasis>
  76                 param (<command>$front->setParam('noViewRenderer', true);</command>) or
  77                 removing the helper from the helper broker stack
  78                 (<methodname>Zend_Controller_Action_HelperBroker::removeHelper('viewRenderer')</methodname>).
  79             </para>
  80
  81             <para>
  82                 If you wish to modify settings of the <emphasis>ViewRenderer</emphasis>
  83                 prior to dispatching the front controller, you may do so in one
  84                 of two ways:
  85             </para>
  86
  87             <itemizedlist>
  88                 <listitem>
  89                     <para>
  90                         Instantiate and register your own
  91                         <emphasis>ViewRenderer</emphasis> object and pass it to the
  92                         helper broker:
  93                     </para>
  94
  95                     <programlisting language="php"><![CDATA[
  96 $viewRenderer = new Zend_Controller_Action_Helper_ViewRenderer();
  97 $viewRenderer->setView($view)
  98              ->setViewSuffix('php');
  99 Zend_Controller_Action_HelperBroker::addHelper($viewRenderer);
 100 ]]></programlisting>
 101                 </listitem>
 102
 103                 <listitem>
 104                     <para>
 105                         Initialize and/or retrieve a <emphasis>ViewRenderer</emphasis>
 106                         object on demand via the helper broker:
 107                     </para>
 108
 109                     <programlisting language="php"><![CDATA[
 110 $viewRenderer =
 111     Zend_Controller_Action_HelperBroker::getStaticHelper('viewRenderer');
 112 $viewRenderer->setView($view)
 113              ->setViewSuffix('php');
 114 ]]></programlisting>
 115                 </listitem>
 116             </itemizedlist>
 117         </note>
 118     </sect4>
 119
 120     <sect4 id="zend.controller.actionhelper.viewrenderer.api">
 121         <title>API</title>
 122
 123         <para>
 124             At its most basic usage, you simply instantiate the
 125             <emphasis>ViewRenderer</emphasis> and pass it to the action helper broker.
 126             The easiest way to instantiate it and register in one go is to use
 127             the helper broker's <methodname>getStaticHelper()</methodname> method:
 128         </para>
 129
 130         <programlisting language="php"><![CDATA[
 131 Zend_Controller_Action_HelperBroker::getStaticHelper('viewRenderer');
 132 ]]></programlisting>
 133
 134         <para>
 135             The first time an action controller is instantiated, it will trigger
 136             the <emphasis>ViewRenderer</emphasis> to instantiate a view object. Each
 137             time a controller is instantiated, the <emphasis>ViewRenderer</emphasis>'s
 138             <methodname>init()</methodname> method is called, which will cause it to set the
 139             view property of the action controller, and call
 140             <methodname>addScriptPath()</methodname> with a path relative to the current
 141             module; this will be called with a class prefix named after the
 142             current module, effectively namespacing all helper and filter
 143             classes you define for the module.
 144         </para>
 145
 146         <para>
 147             Each time <methodname>postDispatch()</methodname> is called, it will call
 148             <methodname>render()</methodname> for the current action.
 149         </para>
 150
 151         <para>
 152             As an example, consider the following class:
 153         </para>
 154
 155         <programlisting language="php"><![CDATA[
 156 // A controller class, foo module:
 157 class Foo_BarController extends Zend_Controller_Action
 158 {
 159     // Render bar/index.phtml by default; no action required
 160     public function indexAction()
 161     {
 162     }
 163
 164     // Render bar/populate.phtml with variable 'foo' set to 'bar'.
 165     // Since view object defined at preDispatch(), it's already available.
 166     public function populateAction()
 167     {
 168         $this->view->foo = 'bar';
 169     }
 170 }
 171
 172 ...
 173
 174 // in one of your view scripts:
 175 $this->foo(); // call Foo_View_Helper_Foo::foo()
 176 ]]></programlisting>
 177
 178         <para>
 179             The <emphasis>ViewRenderer</emphasis> also defines a number of accessors to
 180             allow setting and retrieving view options:
 181         </para>
 182
 183         <itemizedlist>
 184             <listitem>
 185                 <para>
 186                     <methodname>setView($view)</methodname> allows you to set the view
 187                     object for the <emphasis>ViewRenderer</emphasis>. It gets set as
 188                     the public class property <varname>$view</varname>.
 189                 </para>
 190             </listitem>
 191
 192             <listitem>
 193                 <para>
 194                     <methodname>setNeverRender($flag = true)</methodname> can be used to
 195                     disable or enable autorendering globally, i.e., for all
 196                     controllers. If set to <constant>TRUE</constant>,
 197                     <methodname>postDispatch()</methodname>
 198                     will not automatically call <methodname>render()</methodname> in the
 199                     current controller. <methodname>getNeverRender()</methodname> retrieves
 200                     the current value.
 201                 </para>
 202             </listitem>
 203
 204             <listitem>
 205                 <para>
 206                     <methodname>setNoRender($flag = true)</methodname> can be used to
 207                     disable or enable autorendering. If set to <constant>TRUE</constant>,
 208                     <methodname>postDispatch()</methodname> will not automatically call
 209                     <methodname>render()</methodname> in the current controller. This
 210                     setting is reset each time <methodname>preDispatch()</methodname> is
 211                     called (i.e., you need to set this flag for each controller
 212                     for which you don't want autorenderering to occur).
 213                     <methodname>getNoRender()</methodname> retrieves the current value.
 214                 </para>
 215             </listitem>
 216
 217             <listitem>
 218                 <para>
 219                     <methodname>setNoController($flag = true)</methodname> can be used to
 220                     tell <methodname>render()</methodname> not to look for the action script
 221                     in a subdirectory named after the controller (which is the
 222                     default behaviour). <methodname>getNoController()</methodname> retrieves
 223                     the current value.
 224                 </para>
 225             </listitem>
 226
 227             <listitem>
 228                 <para>
 229                     <methodname>setNeverController($flag = true)</methodname> is analogous
 230                     to <methodname>setNoController()</methodname>, but works on a global
 231                     level -- i.e., it will not be reset for each dispatched
 232                     action. <methodname>getNeverController()</methodname> retrieves
 233                     the current value.
 234                 </para>
 235             </listitem>
 236
 237             <listitem>
 238                 <para>
 239                     <methodname>setScriptAction($name)</methodname> can be used to
 240                     specify the action script to render. <varname>$name</varname>
 241                     should be the name of the script minus the file suffix (and
 242                     without the controller subdirectory, unless
 243                     <emphasis>noController</emphasis> has been turned on). If not
 244                     specified, it looks for a view script named after the action
 245                     in the request object. <methodname>getScriptAction()</methodname>
 246                     retrieves the current value.
 247                 </para>
 248             </listitem>
 249
 250             <listitem>
 251                 <para>
 252                     <methodname>setResponseSegment($name)</methodname> can be used to
 253                     specify which response object named segment to render into.
 254                     If not specified, it renders into the default segment.
 255                     <methodname>getResponseSegment()</methodname> retrieves the current
 256                     value.
 257                 </para>
 258             </listitem>
 259
 260             <listitem>
 261                 <para>
 262                     <methodname>initView($path, $prefix, $options)</methodname> may be called
 263                     to specify the base view path, class prefix for helper and
 264                     filter scripts, and <emphasis>ViewRenderer</emphasis> options. You
 265                     may pass any of the following flags:
 266                     <emphasis>neverRender</emphasis>, <emphasis>noRender</emphasis>,
 267                     <emphasis>noController</emphasis>, <emphasis>scriptAction</emphasis>, and
 268                     <emphasis>responseSegment</emphasis>.
 269                 </para>
 270             </listitem>
 271
 272             <listitem>
 273                 <para>
 274                     <methodname>setRender($action = null, $name = null, $noController
 275                         = false)</methodname> allows you to set any of
 276                     <emphasis>scriptAction</emphasis>, <emphasis>responseSegment</emphasis>, and
 277                     <emphasis>noController</emphasis> in one pass. <methodname>direct()</methodname>
 278                     is an alias to this method, allowing you to call this method
 279                     easily from your controller:
 280                 </para>
 281
 282                 <programlisting language="php"><![CDATA[
 283 // Render 'foo' instead of current action script
 284 $this->_helper->viewRenderer('foo');
 285
 286 // render form.phtml to the 'html' response segment, without using a
 287 // controller view script subdirectory:
 288 $this->_helper->viewRenderer('form', 'html', true);
 289 ]]></programlisting>
 290
 291                 <note>
 292                     <para>
 293                         <methodname>setRender()</methodname> and <methodname>direct()</methodname>
 294                         don't actually render the view script, but instead set hints
 295                         that <methodname>postDispatch()</methodname> and
 296                         <methodname>render()</methodname> will use to render the view.
 297                     </para>
 298                 </note>
 299             </listitem>
 300         </itemizedlist>
 301
 302         <para>
 303             The constructor allows you to optionally pass the view object and
 304             <emphasis>ViewRenderer</emphasis> options; it accepts the same flags as
 305             <methodname>initView()</methodname>:
 306         </para>
 307
 308         <programlisting language="php"><![CDATA[
 309 $view    = new Zend_View(array('encoding' => 'UTF-8'));
 310 $options = array('noController' => true, 'neverRender' => true);
 311 $viewRenderer =
 312     new Zend_Controller_Action_Helper_ViewRenderer($view, $options);
 313 ]]></programlisting>
 314
 315         <para>
 316             There are several additional methods for customizing path
 317             specifications used for determining the view base path to add to the
 318             view object, and the view script path to use when autodetermining
 319             the view script to render. These methods each take one or more of
 320             the following placeholders:
 321         </para>
 322
 323         <itemizedlist>
 324             <listitem>
 325                 <para>
 326                     <emphasis>:moduleDir</emphasis> refers to the current module's base
 327                     directory (by convention, the parent directory of the
 328                     module's controller directory).
 329                 </para>
 330             </listitem>
 331
 332             <listitem>
 333                 <para>
 334                     <emphasis>:module</emphasis> refers to the current module name.
 335                 </para>
 336             </listitem>
 337
 338             <listitem>
 339                 <para>
 340                     <emphasis>:controller</emphasis> refers to the current controller name.
 341                 </para>
 342             </listitem>
 343
 344             <listitem>
 345                 <para>
 346                     <emphasis>:action</emphasis> refers to the current action name.
 347                 </para>
 348             </listitem>
 349
 350             <listitem>
 351                 <para>
 352                     <emphasis>:suffix</emphasis> refers to the view script suffix (which
 353                     may be set via <methodname>setViewSuffix()</methodname>).
 354                 </para>
 355             </listitem>
 356         </itemizedlist>
 357
 358         <para>
 359             The methods for controlling path specifications are:
 360         </para>
 361
 362         <itemizedlist>
 363             <listitem>
 364                 <para>
 365                     <methodname>setViewBasePathSpec($spec)</methodname> allows you to change
 366                     the path specification used to determine the base path to
 367                     add to the view object. The default specification is
 368                     <filename>:moduleDir/views</filename>. You may retrieve the current
 369                     specification at any time using
 370                     <methodname>getViewBasePathSpec()</methodname>.
 371                 </para>
 372             </listitem>
 373
 374             <listitem>
 375                 <para>
 376                     <methodname>setViewScriptPathSpec($spec)</methodname> allows you to
 377                     change the path specification used to determine the path to
 378                     an individual view script (minus the base view script path).
 379                     The default specification is
 380                     <filename>:controller/:action.:suffix</filename>. You may retrieve
 381                     the current specification at any time using
 382                     <methodname>getViewScriptPathSpec()</methodname>.
 383                 </para>
 384             </listitem>
 385
 386             <listitem>
 387                 <para>
 388                     <methodname>setViewScriptPathNoControllerSpec($spec)</methodname> allows
 389                     you to change the path specification used to determine the
 390                     path to an individual view script when
 391                     <emphasis>noController</emphasis> is in effect (minus the base view
 392                     script path). The default specification is
 393                     <filename>:action.:suffix</filename>. You may retrieve the current
 394                     specification at any time using
 395                     <methodname>getViewScriptPathNoControllerSpec()</methodname>.
 396                 </para>
 397             </listitem>
 398         </itemizedlist>
 399
 400         <para>
 401             For fine-grained control over path specifications, you may use
 402             <link linkend="zend.filter.inflector">Zend_Filter_Inflector</link>.
 403             Under the hood, the <emphasis>ViewRenderer</emphasis> uses an inflector to
 404             perform path mappings already. To interact with the inflector --
 405             either to set your own for use, or to modify the default inflector,
 406             the following methods may be used:
 407         </para>
 408
 409         <itemizedlist>
 410             <listitem>
 411                 <para>
 412                     <methodname>getInflector()</methodname> will retrieve the inflector. If
 413                     none exists yet in the <emphasis>ViewRenderer</emphasis>, it creates
 414                     one using the default rules.
 415                 </para>
 416
 417                 <para>
 418                     By default, it uses static rule references for the suffix
 419                     and module directory, as well as a static target; this
 420                     allows various <emphasis>ViewRenderer</emphasis> properties the
 421                     ability to dynamically modify the inflector.
 422                 </para>
 423             </listitem>
 424
 425             <listitem>
 426                 <para>
 427                     <methodname>setInflector($inflector, $reference)</methodname> allows you
 428                     to set a custom inflector for use with the
 429                     <emphasis>ViewRenderer</emphasis>. If <varname>$reference</varname> is
 430                     <constant>TRUE</constant>, it will set the suffix and module directory as static
 431                     references to <emphasis>ViewRenderer</emphasis> properties, as well
 432                     as the target.
 433                 </para>
 434             </listitem>
 435         </itemizedlist>
 436
 437         <note>
 438             <title>Default Lookup Conventions</title>
 439
 440             <para>
 441                 The <emphasis>ViewRenderer</emphasis> does some path normalization to
 442                 make view script lookups easier. The default rules are as
 443                 follows:
 444             </para>
 445
 446             <itemizedlist>
 447                 <listitem>
 448                     <para>
 449                         <emphasis>:module</emphasis>: MixedCase and camelCasedWords are separated by
 450                         dashes, and the entire string cast to lowercase. E.g.:
 451                         "FooBarBaz" becomes "foo-bar-baz".
 452                     </para>
 453
 454                     <para>
 455                         Internally, the inflector uses the filters
 456                         <classname>Zend_Filter_Word_CamelCaseToDash</classname> and
 457                         <classname>Zend_Filter_StringToLower</classname>.
 458                     </para>
 459                 </listitem>
 460
 461                 <listitem>
 462                     <para>
 463                         <emphasis>:controller</emphasis>: MixedCase and camelCasedWords are
 464                         separated by dashes; underscores are converted to directory
 465                         separators, and the entire string cast to lower case.
 466                         Examples: "<classname>FooBar</classname>" becomes "foo-bar";
 467                         "<classname>FooBar_Admin</classname>" becomes
 468                         "<filename>foo-bar/admin</filename>".
 469                     </para>
 470
 471                     <para>
 472                         Internally, the inflector uses the filters
 473                         <classname>Zend_Filter_Word_CamelCaseToDash</classname>,
 474                         <classname>Zend_Filter_Word_UnderscoreToSeparator</classname>, and
 475                         <classname>Zend_Filter_StringToLower</classname>.
 476                     </para>
 477                 </listitem>
 478
 479                 <listitem>
 480                     <para>
 481                         <emphasis>:action</emphasis>: MixedCase and camelCasedWords are separated
 482                         by dashes; non-alphanumeric characters are translated to
 483                         dashes, and the entire string cast to lower case.
 484                         Examples: "fooBar" becomes "foo-bar"; "foo-barBaz"
 485                         becomes "foo-bar-baz".
 486                     </para>
 487
 488                     <para>
 489                         Internally, the inflector uses the filters
 490                         <classname>Zend_Filter_Word_CamelCaseToDash</classname>,
 491                         <classname>Zend_Filter_PregReplace</classname>, and
 492                         <classname>Zend_Filter_StringToLower</classname>.
 493                     </para>
 494                 </listitem>
 495             </itemizedlist>
 496         </note>
 497
 498         <para>
 499             The final items in the <emphasis>ViewRenderer</emphasis> <acronym>API</acronym> are the
 500             methods for actually determining view script paths and rendering views.
 501             These include:
 502         </para>
 503
 504         <itemizedlist>
 505             <listitem>
 506                 <para>
 507                     <methodname>renderScript($script, $name)</methodname> allows you to
 508                     render a script with a path you specify, optionally to a
 509                     named path segment. When using this method, the
 510                     <emphasis>ViewRenderer</emphasis> does no autodetermination of the
 511                     script name, but instead directly passes the
 512                     <varname>$script</varname> argument directly to the view object's
 513                     <methodname>render()</methodname> method.
 514                 </para>
 515
 516                 <note>
 517                     <para>
 518                         Once the view has been rendered to the response object, it
 519                         sets the <emphasis>noRender</emphasis> to prevent accidentally
 520                         rendering the same view script multiple times.
 521                     </para>
 522                 </note>
 523
 524                 <note>
 525                     <para>
 526                         By default,
 527                         <methodname>Zend_Controller_Action::renderScript()</methodname>
 528                         proxies to the <emphasis>ViewRenderer</emphasis>'s
 529                         <methodname>renderScript()</methodname> method.
 530                     </para>
 531                 </note>
 532             </listitem>
 533
 534             <listitem>
 535                 <para>
 536                     <methodname>getViewScript($action, $vars)</methodname> creates the path
 537                     to a view script based on the action passed and/or any
 538                     variables passed in <varname>$vars</varname>. Keys for this array
 539                     may include any of the path specification keys ('moduleDir',
 540                     'module', 'controller', 'action', and 'suffix'). Any
 541                     variables passed will be used; otherwise, values based on
 542                     the current request will be utlized.
 543                 </para>
 544
 545                 <para>
 546                     <methodname>getViewScript()</methodname> will use either the
 547                     <emphasis>viewScriptPathSpec</emphasis> or
 548                     <emphasis>viewScriptPathNoControllerSpec</emphasis> based on the
 549                     setting of the <emphasis>noController</emphasis> flag.
 550                 </para>
 551
 552                 <para>
 553                     Word delimiters occurring in module, controller, or action names will be
 554                     replaced with dashes ('-'). Thus, if you have the controller name
 555                     '<command>foo.bar</command>' and the action '<command>baz:bat</command>', using
 556                     the default path specification will result in a view script path of
 557                     '<filename>foo-bar/baz-bat.phtml</filename>'.
 558                 </para>
 559
 560                 <note>
 561                     <para>
 562                         By default,
 563                         <methodname>Zend_Controller_Action::getViewScript()</methodname>
 564                         proxies to the <emphasis>ViewRenderer</emphasis>'s
 565                         <methodname>getViewScript()</methodname> method.
 566                     </para>
 567                 </note>
 568             </listitem>
 569
 570             <listitem>
 571                 <para>
 572                     <methodname>render($action, $name, $noController)</methodname> checks
 573                     first to see if either <varname>$name</varname> or
 574                     <varname>$noController</varname> have been passed, and if so, sets
 575                     the appropriate flags (responseSegment and noController,
 576                     respectively) in the ViewRenderer. It then passes the
 577                     <varname>$action</varname> argument, if any, on to
 578                     <methodname>getViewScript()</methodname>. Finally, it passes the
 579                     calculated view script path to <methodname>renderScript()</methodname>.
 580                 </para>
 581
 582                 <note>
 583                     <para>
 584                         Be aware of the side-effects of using <methodname>render()</methodname>: the
 585                         values you pass for the response segment name and for
 586                         the noController flag will persist in the object.
 587                         Additionally, noRender will be set after rendering is
 588                         completed.
 589                     </para>
 590                 </note>
 591
 592                 <note>
 593                     <para>
 594                         By default,
 595                         <methodname>Zend_Controller_Action::render()</methodname> proxies to
 596                         the <emphasis>ViewRenderer</emphasis>'s <methodname>render()</methodname>
 597                         method.
 598                     </para>
 599                 </note>
 600             </listitem>
 601
 602             <listitem>
 603                 <para>
 604                     <methodname>renderBySpec($action, $vars, $name)</methodname> allows you
 605                     to pass path specification variables in order to determine
 606                     the view script path to create. It passes
 607                     <varname>$action</varname> and <varname>$vars</varname> to
 608                     <methodname>getScriptPath()</methodname>, and then passes the resulting
 609                     script path and <varname>$name</varname> on to
 610                     <methodname>renderScript()</methodname>.
 611                 </para>
 612             </listitem>
 613         </itemizedlist>
 614     </sect4>
 615
 616     <sect4 id="zend.controller.actionhelper.viewrenderer.basicusage">
 617         <title>Basic Usage Examples</title>
 618
 619         <example id="zend.controller.actionhelper.viewrenderer.basicusage.example-1">
 620             <title>Basic Usage</title>
 621
 622             <para>
 623                 At its most basic, you simply initialize and register the
 624                 <emphasis>ViewRenderer</emphasis> helper with the helper broker in your
 625                 bootstrap, and then set variables in your action methods.
 626             </para>
 627
 628             <programlisting language="php"><![CDATA[
 629 // In your bootstrap:
 630 Zend_Controller_Action_HelperBroker::getStaticHelper('viewRenderer');
 631
 632 ...
 633
 634 // 'foo' module, 'bar' controller:
 635 class Foo_BarController extends Zend_Controller_Action
 636 {
 637     // Render bar/index.phtml by default; no action required
 638     public function indexAction()
 639     {
 640     }
 641
 642     // Render bar/populate.phtml with variable 'foo' set to 'bar'.
 643     // Since view object defined at preDispatch(), it's already available.
 644     public function populateAction()
 645     {
 646         $this->view->foo = 'bar';
 647     }
 648
 649     // Renders nothing as it forwards to another action; the new action
 650     // will perform any rendering
 651     public function bazAction()
 652     {
 653         $this->_forward('index');
 654     }
 655
 656     // Renders nothing as it redirects to another location
 657     public function batAction()
 658     {
 659         $this->_redirect('/index');
 660     }
 661 }
 662 ]]></programlisting>
 663         </example>
 664
 665         <note>
 666             <title>Naming Conventions: Word Delimiters in Controller and Action Names</title>
 667
 668             <para>
 669                 If your controller or action name is composed of several
 670                 words, the dispatcher requires that these are separated on
 671                 the <acronym>URL</acronym> by specific path and word delimiter characters. The
 672                 <emphasis>ViewRenderer</emphasis> replaces any path delimiter found
 673                 in the controller name with an actual path delimiter ('/'),
 674                 and any word delimiter found with a dash ('-') when creating
 675                 paths. Thus, a call to the action
 676                 <filename>/foo.bar/baz.bat</filename> would dispatch to
 677                 <methodname>FooBarController::bazBatAction()</methodname> in
 678                 <filename>FooBarController.php</filename>, which would render
 679                 <filename>foo-bar/baz-bat.phtml</filename>; a call to the action
 680                 <filename>/bar_baz/baz-bat</filename> would dispatch to
 681                 <methodname>Bar_BazController::bazBatAction()</methodname> in
 682                 <filename>Bar/BazController.php</filename> (note the path
 683                 separation) and render <filename>bar/baz/baz-bat.phtml</filename>.
 684             </para>
 685
 686             <para>
 687                 Note that the in the second example, the module is still the
 688                 default module, but that, because of the existence of a path
 689                 separator, the controller receives the name
 690                 <classname>Bar_BazController</classname>, in
 691                 <filename>Bar/BazController.php</filename>. The ViewRenderer mimics
 692                 the controller directory hierarchy.
 693             </para>
 694         </note>
 695
 696         <example id="zend.controller.actionhelper.viewrenderer.basicusage.example-2">
 697             <title>Disabling Autorender</title>
 698
 699             <para>
 700                 For some actions or controllers, you may want to turn off the
 701                 autorendering -- for instance, if you're wanting to emit a
 702                 different type of output (<acronym>XML</acronym>, <acronym>JSON</acronym>, etc),
 703                 or if you simply want
 704                 to emit nothing. You have two options: turn off all cases of
 705                 autorendering (<methodname>setNeverRender()</methodname>), or simply turn it
 706                 off for the current action (<methodname>setNoRender()</methodname>).
 707             </para>
 708
 709             <programlisting language="php"><![CDATA[
 710 // Baz controller class, bar module:
 711 class Bar_BazController extends Zend_Controller_Action
 712 {
 713     public function fooAction()
 714     {
 715         // Don't auto render this action
 716         $this->_helper->viewRenderer->setNoRender();
 717     }
 718 }
 719
 720 // Bat controller class, bar module:
 721 class Bar_BatController extends Zend_Controller_Action
 722 {
 723     public function preDispatch()
 724     {
 725         // Never auto render this controller's actions
 726         $this->_helper->viewRenderer->setNoRender();
 727     }
 728 }
 729 ]]></programlisting>
 730         </example>
 731
 732         <note>
 733             <para>
 734                 In most cases, it makes no sense to turn off autorendering
 735                 globally (ala <methodname>setNeverRender()</methodname>), as the only thing
 736                 you then gain from <emphasis>ViewRenderer</emphasis> is the autosetup of
 737                 the view object.
 738             </para>
 739         </note>
 740
 741         <example id="zend.controller.actionhelper.viewrenderer.basicusage.example-3">
 742             <title>Choosing a Different View Script</title>
 743
 744             <para>
 745                 Some situations require that you render a different script than
 746                 one named after the action. For instance, if you have a
 747                 controller that has both add and edit actions, they may both
 748                 display the same 'form' view, albeit with different values set.
 749                 You can easily change the script name used with either
 750                 <methodname>setScriptAction()</methodname>, <methodname>setRender()</methodname>,
 751                 or calling the helper as a method, which will invoke
 752                 <methodname>setRender()</methodname>.
 753             </para>
 754
 755             <programlisting language="php"><![CDATA[
 756 // Bar controller class, foo module:
 757 class Foo_BarController extends Zend_Controller_Action
 758 {
 759     public function addAction()
 760     {
 761         // Render 'bar/form.phtml' instead of 'bar/add.phtml'
 762         $this->_helper->viewRenderer('form');
 763     }
 764
 765     public function editAction()
 766     {
 767         // Render 'bar/form.phtml' instead of 'bar/edit.phtml'
 768         $this->_helper->viewRenderer->setScriptAction('form');
 769     }
 770
 771     public function processAction()
 772     {
 773         // do some validation...
 774         if (!$valid) {
 775             // Render 'bar/form.phtml' instead of 'bar/process.phtml'
 776             $this->_helper->viewRenderer->setRender('form');
 777             return;
 778         }
 779
 780         // otherwise continue processing...
 781     }
 782
 783 }
 784 ]]></programlisting>
 785         </example>
 786
 787         <example id="zend.controller.actionhelper.viewrenderer.basicusage.example-4">
 788             <title>Modifying the Registered View</title>
 789
 790             <para>
 791                 What if you need to modify the view object -- for instance,
 792                 change the helper paths, or the encoding? You can do so either
 793                 by modifying the view object set in your controller, or by
 794                 grabbing the view object out of the <emphasis>ViewRenderer</emphasis>;
 795                 both are references to the same object.
 796             </para>
 797
 798             <programlisting language="php"><![CDATA[
 799 // Bar controller class, foo module:
 800 class Foo_BarController extends Zend_Controller_Action
 801 {
 802     public function preDispatch()
 803     {
 804         // change view encoding
 805         $this->view->setEncoding('UTF-8');
 806     }
 807
 808     public function bazAction()
 809     {
 810         // Get view object and set escape callback to 'htmlspecialchars'
 811         $view = $this->_helper->viewRenderer->view;
 812         $view->setEscape('htmlspecialchars');
 813     }
 814 }
 815 ]]></programlisting>
 816         </example>
 817     </sect4>
 818
 819     <sect4 id="zend.controller.actionhelper.viewrenderer.advancedusage">
 820         <title>Advanced Usage Examples</title>
 821
 822         <example id="zend.controller.actionhelper.viewrenderer.advancedusage.example-1">
 823             <title>Changing the Path Specifications</title>
 824
 825             <para>
 826                 In some circumstances, you may decide that the default path
 827                 specifications do not fit your site's needs. For instance, you
 828                 may want to have a single template tree to which you may then
 829                 give access to your designers (this is very typical when using
 830                 <ulink url="http://smarty.php.net/">Smarty</ulink>, for
 831                 instance). In such a case, you may want to hardcode the view
 832                 base path specification, and create an alternate specification
 833                 for the action view script paths themselves.
 834             </para>
 835
 836             <para>
 837                 For purposes of this example, let's assume that the base path to
 838                 views should be '<filename>/opt/vendor/templates</filename>', and that you wish for
 839                 view scripts to be referenced by
 840                 '<filename>:moduleDir/:controller/:action.:suffix</filename>'; if the
 841                 <emphasis>noController</emphasis>
 842                 flag has been set, you want to render out of the top level
 843                 instead of in a subdirectory ('<filename>:action.:suffix</filename>'). Finally, you
 844                 want to use 'tpl' as the view script filename suffix.
 845             </para>
 846
 847             <programlisting language="php"><![CDATA[
 848 /**
 849  * In your bootstrap:
 850  */
 851
 852 // Different view implementation
 853 $view = new ZF_Smarty();
 854
 855 $viewRenderer = new Zend_Controller_Action_Helper_ViewRenderer($view);
 856 $viewRenderer->setViewBasePathSpec('/opt/vendor/templates')
 857              ->setViewScriptPathSpec(':module/:controller/:action.:suffix')
 858              ->setViewScriptPathNoControllerSpec(':action.:suffix')
 859              ->setViewSuffix('tpl');
 860 Zend_Controller_Action_HelperBroker::addHelper($viewRenderer);
 861 ]]></programlisting>
 862         </example>
 863
 864         <example id="zend.controller.actionhelper.viewrenderer.advancedusage.example-2">
 865             <title>Rendering Multiple View Scripts from a Single Action</title>
 866
 867             <para>
 868                 At times, you may need to render multiple view scripts from a
 869                 single action. This is very straightforward -- simply make
 870                 multiple calls to <methodname>render()</methodname>:
 871             </para>
 872
 873             <programlisting language="php"><![CDATA[
 874 class SearchController extends Zend_Controller_Action
 875 {
 876     public function resultsAction()
 877     {
 878         // Assume $this->model is the current model
 879         $this->view->results =
 880             $this->model->find($this->_getParam('query', '');
 881
 882         // render() by default proxies to the ViewRenderer
 883         // Render first the search form and then the results
 884         $this->render('form');
 885         $this->render('results');
 886     }
 887
 888     public function formAction()
 889     {
 890         // do nothing; ViewRenderer autorenders the view script
 891     }
 892 }
 893 ]]></programlisting>
 894         </example>
 895     </sect4>
 896 </sect3>
 897 <!--
 898 vim:se ts=4 sw=4 et:
 899 -->