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

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="zend.layout.options">
   4     <title>Zend_Layout Configuration Options</title>
   5
   6     <para>
   7         <classname>Zend_Layout</classname> has a variety of configuration options. These
   8         may be set by calling the appropriate accessors, passing an array or
   9         <classname>Zend_Config</classname> object to the constructor or
  10         <methodname>startMvc()</methodname>, passing an array of options to
  11         <methodname>setOptions()</methodname>, or passing a <classname>Zend_Config</classname>
  12         object to <methodname>setConfig()</methodname>.
  13     </para>
  14
  15     <itemizedlist>
  16         <listitem>
  17             <para>
  18                 <emphasis>layout</emphasis>: the layout to use. Uses the
  19                 current inflector to resolve the name provided to the
  20                 appropriate layout view script. By default, this value is
  21                 'layout' and resolves to 'layout.phtml'. Accessors
  22                 are <methodname>setLayout()</methodname> and <methodname>getLayout()</methodname>.
  23             </para>
  24         </listitem>
  25
  26         <listitem>
  27             <para>
  28                 <emphasis>layoutPath</emphasis>: the base path to layout view
  29                 scripts. Accessors are <methodname>setLayoutPath()</methodname> and
  30                 <methodname>getLayoutPath()</methodname>.
  31             </para>
  32         </listitem>
  33
  34         <listitem>
  35             <para>
  36                 <emphasis>contentKey</emphasis>: the layout variable used for
  37                 default content (when used with the <acronym>MVC</acronym>). Default value is
  38                 'content'. Accessors are <methodname>setContentKey()</methodname> and
  39                 <methodname>getContentKey()</methodname>.
  40             </para>
  41         </listitem>
  42
  43         <listitem>
  44             <para>
  45                 <emphasis>mvcSuccessfulActionOnly</emphasis>: when using the
  46                 <acronym>MVC</acronym>, if an action throws an exception and this flag is
  47                 <constant>TRUE</constant>, the layout will not be rendered (this is to prevent
  48                 double-rendering of the layout when the <link
  49                     linkend="zend.controller.plugins.standard.errorhandler">ErrorHandler
  50                     plugin</link> is in use). By default, the flat is <constant>TRUE</constant>.
  51                 Accessors are <methodname>setMvcSuccessfulActionOnly()</methodname> and
  52                 <methodname>getMvcSuccessfulActionOnly()</methodname>.
  53             </para>
  54         </listitem>
  55
  56         <listitem>
  57             <para>
  58                 <emphasis>view</emphasis>: the view object to use when rendering. When used with the
  59                 <acronym>MVC</acronym>, <classname>Zend_Layout</classname> will attempt to use the
  60                 view object registered with <link
  61                     linkend="zend.controller.actionhelpers.viewrenderer">the ViewRenderer</link> if
  62                 no view object has been passed to it explicitly. Accessors are
  63                 <methodname>setView()</methodname> and <methodname>getView()</methodname>.
  64             </para>
  65         </listitem>
  66
  67         <listitem>
  68             <para>
  69                 <emphasis>helperClass</emphasis>: the action helper class to use
  70                 when using <classname>Zend_Layout</classname> with the <acronym>MVC</acronym>
  71                 components. By default, this is
  72                 <classname>Zend_Layout_Controller_Action_Helper_Layout</classname>.
  73                 Accessors are <methodname>setHelperClass()</methodname> and
  74                 <methodname>getHelperClass()</methodname>.
  75             </para>
  76         </listitem>
  77
  78         <listitem>
  79             <para>
  80                 <emphasis>pluginClass</emphasis>: the front controller plugin
  81                 class to use when using <classname>Zend_Layout</classname> with the
  82                 <acronym>MVC</acronym> components. By default, this is
  83                 <classname>Zend_Layout_Controller_Plugin_Layout</classname>. Accessors
  84                 are <methodname>setPluginClass()</methodname> and
  85                 <methodname>getPluginClass()</methodname>.
  86             </para>
  87         </listitem>
  88
  89         <listitem>
  90             <para>
  91                 <emphasis>inflector</emphasis>: the inflector to use when
  92                 resolving layout names to layout view script paths; see <link
  93                     linkend="zend.layout.advanced.inflector">the
  94                     <classname>Zend_Layout</classname> inflector documentation for more
  95                     details</link>. Accessors are <methodname>setInflector()</methodname>
  96                 and <methodname>getInflector()</methodname>.
  97             </para>
  98         </listitem>
  99     </itemizedlist>
 100
 101     <note>
 102         <title>helperClass and pluginClass must be passed to startMvc()</title>
 103
 104         <para>
 105             In order for the <code>helperClass</code> and
 106             <code>pluginClass</code> settings to have effect, they must be
 107             passed in as options to <methodname>startMvc()</methodname>; if set later, they
 108             have no affect.
 109         </para>
 110     </note>
 111
 112     <sect2 id="zend.layout.options.examples">
 113         <title>Examples</title>
 114
 115         <para>
 116             The following examples assume the following <varname>$options</varname>
 117             array and <varname>$config</varname> object:
 118         </para>
 119
 120         <programlisting language="php"><![CDATA[
 121 $options = array(
 122     'layout'     => 'foo',
 123     'layoutPath' => '/path/to/layouts',
 124     'contentKey' => 'CONTENT',           // ignored when MVC not used
 125 );
 126 ]]></programlisting>
 127
 128         <programlisting language="php"><![CDATA[
 129 /**
 130 [layout]
 131 layout = "foo"
 132 layoutPath = "/path/to/layouts"
 133 contentKey = "CONTENT"
 134 */
 135 $config = new Zend_Config_Ini('/path/to/layout.ini', 'layout');
 136 ]]></programlisting>
 137
 138         <example id="zend.layout.options.examples.constructor">
 139             <title>Passing options to the constructor or startMvc()</title>
 140
 141             <para>
 142                 Both the constructor and the <methodname>startMvc()</methodname> static
 143                 method can accept either an array of options or a
 144                 <classname>Zend_Config</classname> object with options in order to
 145                 configure the <classname>Zend_Layout</classname> instance.
 146             </para>
 147
 148             <para>
 149                 First, let's look at passing an array:
 150             </para>
 151
 152             <programlisting language="php"><![CDATA[
 153 // Using constructor:
 154 $layout = new Zend_Layout($options);
 155
 156 // Using startMvc():
 157 $layout = Zend_Layout::startMvc($options);
 158 ]]></programlisting>
 159
 160             <para>
 161                 And now using a config object:
 162             </para>
 163
 164             <programlisting language="php"><![CDATA[
 165 $config = new Zend_Config_Ini('/path/to/layout.ini', 'layout');
 166
 167 // Using constructor:
 168 $layout = new Zend_Layout($config);
 169
 170 // Using startMvc():
 171 $layout = Zend_Layout::startMvc($config);
 172 ]]></programlisting>
 173
 174             <para>
 175                 Basically, this is the easiest way to customize your
 176                 <classname>Zend_Layout</classname> instance.
 177             </para>
 178         </example>
 179
 180         <example id="zend.layout.options.examples.setoptionsconfig">
 181             <title>Using setOption() and setConfig()</title>
 182
 183             <para>
 184                 Sometimes you need to configure the <classname>Zend_Layout</classname>
 185                 object after it has already been instantiated;
 186                 <methodname>setOptions()</methodname> and <methodname>setConfig()</methodname> give
 187                 you a quick and easy way to do so:
 188             </para>
 189
 190             <programlisting language="php"><![CDATA[
 191 // Using an array of options:
 192 $layout->setOptions($options);
 193
 194 // Using a Zend_Config object:
 195 $layout->setConfig($options);
 196 ]]></programlisting>
 197
 198             <para>
 199                 Note, however, that certain options, such as
 200                 <code>pluginClass</code> and <code>helperClass</code>, will have
 201                 no affect when passed using this method; they need to be passed
 202                 to the constructor or <methodname>startMvc()</methodname> method.
 203             </para>
 204         </example>
 205
 206         <example id="zend.layout.options.examples.accessors">
 207             <title>Using Accessors</title>
 208
 209             <para>
 210                 Finally, you can also configure your <classname>Zend_Layout</classname>
 211                 instance via accessors. All accessors implement a fluent
 212                 interface, meaning their calls may be chained:
 213             </para>
 214
 215             <programlisting language="php"><![CDATA[
 216 $layout->setLayout('foo')
 217        ->setLayoutPath('/path/to/layouts')
 218        ->setContentKey('CONTENT');
 219 ]]></programlisting>
 220         </example>
 221     </sect2>
 222 </sect1>
 223 <!--
 224 vim:se ts=4 sw=4 et:
 225 -->