documentation/manual/en/module_specs/Zend_Layout-Advanced.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="zend.layout.advanced">
   4     <title>Zend_Layout Advanced Usage</title>
   5
   6     <para>
   7         <classname>Zend_Layout</classname> has a number of use cases for the advanced
   8         developer who wishes to adapt it for different view implementations,
   9         file system layouts, and more.
  10     </para>
  11
  12     <para>
  13         The major points of extension are:
  14     </para>
  15
  16     <itemizedlist>
  17         <listitem>
  18             <para>
  19                 <emphasis>Custom view objects.</emphasis>
  20                 <classname>Zend_Layout</classname> allows you to utilize any class that
  21                 implements <classname>Zend_View_Interface</classname>.
  22             </para>
  23         </listitem>
  24
  25         <listitem>
  26             <para>
  27                 <emphasis>Custom front controller plugins.</emphasis>
  28                 <classname>Zend_Layout</classname> ships with a standard front controller
  29                 plugin that automates rendering of layouts prior to returning
  30                 the response. You can substitute your own plugin.
  31             </para>
  32         </listitem>
  33
  34         <listitem>
  35             <para>
  36                 <emphasis>Custom action helpers.</emphasis>
  37                 <classname>Zend_Layout</classname> ships with a standard action helper
  38                 that should be suitable for most needs as it is a dumb proxy
  39                 to the layout object itself.
  40             </para>
  41         </listitem>
  42
  43         <listitem>
  44             <para>
  45                 <emphasis>Custom layout script path resolution</emphasis>.
  46                 <classname>Zend_Layout</classname> allows you to use your own <link
  47                     linkend="zend.filter.inflector">inflector</link> for layout
  48                 script path resolution, or simply to modify the attached
  49                 inflector to specify your own inflection rules.
  50             </para>
  51         </listitem>
  52     </itemizedlist>
  53
  54     <sect2 id="zend.layout.advanced.view">
  55         <title>Custom View Objects</title>
  56
  57         <para>
  58             <classname>Zend_Layout</classname> allows you to use any class implementing
  59             <classname>Zend_View_Interface</classname> or extending
  60             <classname>Zend_View_Abstract</classname> for rendering your layout script.
  61             Simply pass in your custom view object as a parameter to the
  62             constructor/<methodname>startMvc()</methodname>, or set it using the
  63             <methodname>setView()</methodname> accessor:
  64         </para>
  65
  66         <programlisting language="php"><![CDATA[
  67 $view = new My_Custom_View();
  68 $layout->setView($view);
  69 ]]></programlisting>
  70
  71         <note>
  72             <title>Not all Zend_View implementations are equal</title>
  73
  74             <para>
  75                 While <classname>Zend_Layout</classname> allows you to use any class
  76                 implementing <classname>Zend_View_Interface</classname>, you may run into
  77                 issues if they can not utilize the various
  78                 <classname>Zend_View</classname> helpers, particularly the layout and
  79                 <link linkend="zend.view.helpers.initial.placeholder">placeholder</link>
  80                 helpers. This is because <classname>Zend_Layout</classname> makes
  81                 variables set in the object available via itself and
  82                 <link linkend="zend.view.helpers.initial.placeholder">placeholders</link>.
  83             </para>
  84
  85             <para>
  86                 If you need to use a custom <classname>Zend_View</classname>
  87                 implementation that does not support these helpers, you will
  88                 need to find a way to get the layout variables to the view. This
  89                 can be done by either extending the <classname>Zend_Layout</classname>
  90                 object and altering the <methodname>render()</methodname> method to pass
  91                 variables to the view, or creating your own plugin class that
  92                 passes them prior to rendering the layout.
  93             </para>
  94
  95             <para>
  96                 Alternately, if your view implementation supports any sort of plugin capability, you
  97                 can access the variables via the 'Zend_Layout' placeholder, using the <link
  98                     linkend="zend.view.helpers.initial.placeholder">placeholder helper</link>:
  99             </para>
 100
 101             <programlisting language="php"><![CDATA[
 102 $placeholders = new Zend_View_Helper_Placeholder();
 103 $layoutVars   = $placeholders->placeholder('Zend_Layout')->getArrayCopy();
 104 ]]></programlisting>
 105         </note>
 106     </sect2>
 107
 108     <sect2 id="zend.layout.advanced.plugin">
 109         <title>Custom Front Controller Plugins</title>
 110
 111         <para>
 112             When used with the <acronym>MVC</acronym> components, <classname>Zend_Layout</classname>
 113             registers a front controller plugin that renders the layout as the
 114             last action prior to exiting the dispatch loop. In most cases, the
 115             default plugin will be suitable, but should you desire to write
 116             your own, you can specify the name of the plugin class to load by
 117             passing the <code>pluginClass</code> option to the
 118             <methodname>startMvc()</methodname> method.
 119         </para>
 120
 121         <para>
 122             Any plugin class you write for this purpose will need to extend
 123             <classname>Zend_Controller_Plugin_Abstract</classname>, and should accept a
 124             layout object instance as an argument to the constructor. Otherwise,
 125             the details of your implementation are up to you.
 126         </para>
 127
 128         <para>
 129             The default plugin class used is
 130             <classname>Zend_Layout_Controller_Plugin_Layout</classname>.
 131         </para>
 132     </sect2>
 133
 134     <sect2 id="zend.layout.advanced.helper">
 135         <title>Custom Action Helpers</title>
 136
 137         <para>
 138             When used with the <acronym>MVC</acronym> components, <classname>Zend_Layout</classname>
 139             registers an action controller helper with the helper broker. The
 140             default helper,
 141             <classname>Zend_Layout_Controller_Action_Helper_Layout</classname>, acts as a
 142             dumb proxy to the layout object instance itself, and should be
 143             suitable for most use cases.
 144         </para>
 145
 146         <para>
 147             Should you feel the need to write custom functionality, simply write
 148             an action helper class extending
 149             <classname>Zend_Controller_Action_Helper_Abstract</classname> and pass the
 150             class name as the <code>helperClass</code> option to the
 151             <methodname>startMvc()</methodname> method. Details of the implementation are
 152             up to you.
 153         </para>
 154     </sect2>
 155
 156     <sect2 id="zend.layout.advanced.inflector">
 157         <title>Custom Layout Script Path Resolution: Using the Inflector</title>
 158
 159         <para>
 160             <classname>Zend_Layout</classname> uses <classname>Zend_Filter_Inflector</classname> to
 161             establish a filter chain for translating a layout name to a layout
 162             script path. By default, it uses the rules 'Word_CamelCaseToDash'
 163             followed by 'StringToLower', and the suffix 'phtml' to transform the
 164             name to a path. As some examples:
 165         </para>
 166
 167         <itemizedlist>
 168             <listitem>
 169                 <para>'foo' will be transformed to 'foo.phtml'.</para>
 170             </listitem>
 171
 172             <listitem>
 173                 <para>'FooBarBaz' will be transformed to 'foo-bar-baz.phtml'.</para>
 174             </listitem>
 175         </itemizedlist>
 176
 177         <para>
 178             You have three options for modifying inflection: modify the
 179             inflection target and/or view suffix via <classname>Zend_Layout</classname>
 180             accessors, modify the inflector rules and target of the inflector
 181             associated with the <classname>Zend_Layout</classname> instance, or create
 182             your own inflector instance and pass it to
 183             <methodname>Zend_Layout::setInflector()</methodname>.
 184         </para>
 185
 186         <example id="zend.layout.advanced.inflector.accessors">
 187             <title>Using Zend_Layout accessors to modify the inflector</title>
 188
 189             <para>
 190                 The default <classname>Zend_Layout</classname> inflector uses static
 191                 references for the target and view script suffix, and
 192                 has accessors for setting these values.
 193             </para>
 194
 195             <programlisting language="php"><![CDATA[
 196 // Set the inflector target:
 197 $layout->setInflectorTarget('layouts/:script.:suffix');
 198
 199 // Set the layout view script suffix:
 200 $layout->setViewSuffix('php');
 201 ]]></programlisting>
 202         </example>
 203
 204         <example id="zend.layout.advanced.inflector.directmodification">
 205             <title>Direct modification of Zend_Layout inflector</title>
 206
 207             <para>
 208                 Inflectors have a target and one or more rules. The default
 209                 target used with <classname>Zend_Layout</classname> is ':script.:suffix';
 210                 ':script' is passed the registered layout name, while ':suffix'
 211                 is a static rule of the inflector.
 212             </para>
 213
 214             <para>
 215                 Let's say you want the layout script to end in the suffix
 216                 'html', and that you want to separate MixedCase and camelCased words with
 217                 underscores instead of dashes, and not lowercase the name.
 218                 Additionally, you want it to look in a 'layouts' subdirectory
 219                 for the script.
 220             </para>
 221
 222             <programlisting language="php"><![CDATA[
 223 $layout->getInflector()->setTarget('layouts/:script.:suffix')
 224                        ->setStaticRule('suffix', 'html')
 225                        ->setFilterRule(array('Word_CamelCaseToUnderscore'));
 226 ]]></programlisting>
 227         </example>
 228
 229         <example id="zend.layout.advanced.inflector.custom">
 230             <title>Custom inflectors</title>
 231
 232             <para>
 233                 In most cases, modifying the existing inflector will be enough.
 234                 However, you may have an inflector you wish to use in several
 235                 places, with different objects of different types.
 236                 <classname>Zend_Layout</classname> supports this.
 237             </para>
 238
 239             <programlisting language="php"><![CDATA[
 240 $inflector = new Zend_Filter_Inflector('layouts/:script.:suffix');
 241 $inflector->addRules(array(
 242     ':script' => array('Word_CamelCaseToUnderscore'),
 243     'suffix'  => 'html'
 244 ));
 245 $layout->setInflector($inflector);
 246 ]]></programlisting>
 247         </example>
 248
 249         <note>
 250             <title>Inflection can be disabled</title>
 251
 252             <para>
 253                 Inflection can be disabled and enabled using accessors on the
 254                 <classname>Zend_Layout</classname> object. This can be useful if you want
 255                 to specify an absolute path for a layout view script, or know
 256                 that the mechanism you will be using for specifying the layout
 257                 script does not need inflection. Simply use the
 258                 <methodname>enableInflection()</methodname> and
 259                 <methodname>disableInflection()</methodname> methods.
 260             </para>
 261         </note>
 262     </sect2>
 263 </sect1>
 264 <!--
 265 vim:se ts=4 sw=4 et:
 266 -->