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

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect1 id="zend.layout.options">
    <title>Zend_Layout Configuration Options</title>

    <para>
        <classname>Zend_Layout</classname> has a variety of configuration options. These
        may be set by calling the appropriate accessors, passing an array or
        <classname>Zend_Config</classname> object to the constructor or
        <methodname>startMvc()</methodname>, passing an array of options to
        <methodname>setOptions()</methodname>, or passing a <classname>Zend_Config</classname> object
        to <methodname>setConfig()</methodname>.
    </para>

    <itemizedlist>
        <listitem><para>
                <emphasis>layout</emphasis>: the layout to use. Uses the
                current inflector to resolve the name provided to the
                appropriate layout view script. By default, this value is
                'layout' and resolves to 'layout.phtml'. Accessors
                are <methodname>setLayout()</methodname> and <methodname>getLayout()</methodname>.
        </para></listitem>

        <listitem><para>
                <emphasis>layoutPath</emphasis>: the base path to layout view
                scripts. Accessors are <methodname>setLayoutPath()</methodname> and
                <methodname>getLayoutPath()</methodname>.
        </para></listitem>

        <listitem><para>
                <emphasis>contentKey</emphasis>: the layout variable used for
                default content (when used with the <acronym>MVC</acronym>). Default value is
                'content'. Accessors are <methodname>setContentKey()</methodname> and
                <methodname>getContentKey()</methodname>.
        </para></listitem>

        <listitem><para>
                <emphasis>mvcSuccessfulActionOnly</emphasis>: when using the
                <acronym>MVC</acronym>, if an action throws an exception and this flag is
                <constant>TRUE</constant>, the layout will not be rendered (this is to prevent
                double-rendering of the layout when the <link
                    linkend="zend.controller.plugins.standard.errorhandler">ErrorHandler
                    plugin</link> is in use). By default, the flat is <constant>TRUE</constant>.
                Accessors are <methodname>setMvcSuccessfulActionOnly()</methodname> and
                <methodname>getMvcSuccessfulActionOnly()</methodname>.
        </para></listitem>

        <listitem><para>
                <emphasis>view</emphasis>: the view object to use when
                rendering. When used with the <acronym>MVC</acronym>, <classname>Zend_Layout</classname> will
                attempt to use the view object registered with <link
                    linkend="zend.controller.actionhelpers.viewrenderer">the
                    ViewRenderer</link> if no view object has been passed to it
                explicitly. Accessors are <methodname>setView()</methodname> and
                <methodname>getView()</methodname>.
        </para></listitem>

        <listitem><para>
                <emphasis>helperClass</emphasis>: the action helper class to use
                when using <classname>Zend_Layout</classname> with the <acronym>MVC</acronym> components. By
                default, this is
                <classname>Zend_Layout_Controller_Action_Helper_Layout</classname>.
                Accessors are <methodname>setHelperClass()</methodname> and
                <methodname>getHelperClass()</methodname>.
        </para></listitem>

        <listitem><para>
                <emphasis>pluginClass</emphasis>: the front controller plugin
                class to use when using <classname>Zend_Layout</classname> with the <acronym>MVC</acronym>
                components. By default, this is
                <classname>Zend_Layout_Controller_Plugin_Layout</classname>. Accessors
                are <methodname>setPluginClass()</methodname> and
                <methodname>getPluginClass()</methodname>.
        </para></listitem>

        <listitem><para>
                <emphasis>inflector</emphasis>: the inflector to use when
                resolving layout names to layout view script paths; see <link
                    linkend="zend.layout.advanced.inflector">the
                    <classname>Zend_Layout</classname> inflector documentation for more
                    details</link>. Accessors are <methodname>setInflector()</methodname>
                and <methodname>getInflector()</methodname>.
        </para></listitem>
    </itemizedlist>

    <note>
        <title>helperClass and pluginClass must be passed to startMvc()</title>

        <para>
            In order for the <code>helperClass</code> and
            <code>pluginClass</code> settings to have effect, they must be
            passed in as options to <methodname>startMvc()</methodname>; if set later, they
            have no affect.
        </para>
    </note>

    <sect2 id="zend.layout.options.examples">
        <title>Examples</title>

        <para>
            The following examples assume the following <varname>$options</varname>
            array and <varname>$config</varname> object:
        </para>

        <programlisting language="php"><![CDATA[
$options = array(
    'layout'     => 'foo',
    'layoutPath' => '/path/to/layouts',
    'contentKey' => 'CONTENT',           // ignored when MVC not used
);
]]></programlisting>

        <programlisting language="php"><![CDATA[
/**
[layout]
layout = "foo"
layoutPath = "/path/to/layouts"
contentKey = "CONTENT"
*/
$config = new Zend_Config_Ini('/path/to/layout.ini', 'layout');
]]></programlisting>

        <example id="zend.layout.options.examples.constructor">
            <title>Passing options to the constructor or startMvc()</title>

            <para>
                Both the constructor and the <methodname>startMvc()</methodname> static
                method can accept either an array of options or a
                <classname>Zend_Config</classname> object with options in order to
                configure the <classname>Zend_Layout</classname> instance.
            </para>

            <para>
                First, let's look at passing an array:
            </para>

            <programlisting language="php"><![CDATA[
// Using constructor:
$layout = new Zend_Layout($options);

// Using startMvc():
$layout = Zend_Layout::startMvc($options);
]]></programlisting>

            <para>
                And now using a config object:
            </para>

            <programlisting language="php"><![CDATA[
$config = new Zend_Config_Ini('/path/to/layout.ini', 'layout');

// Using constructor:
$layout = new Zend_Layout($config);

// Using startMvc():
$layout = Zend_Layout::startMvc($config);
]]></programlisting>

            <para>
                Basically, this is the easiest way to customize your
                <classname>Zend_Layout</classname> instance.
            </para>
        </example>

        <example id="zend.layout.options.examples.setoptionsconfig">
            <title>Using setOption() and setConfig()</title>

            <para>
                Sometimes you need to configure the <classname>Zend_Layout</classname>
                object after it has already been instantiated;
                <methodname>setOptions()</methodname> and <methodname>setConfig()</methodname> give you
                a quick and easy way to do so:
            </para>

            <programlisting language="php"><![CDATA[
// Using an array of options:
$layout->setOptions($options);

// Using a Zend_Config object:
$layout->setConfig($options);
]]></programlisting>

            <para>
                Note, however, that certain options, such as
                <code>pluginClass</code> and <code>helperClass</code>, will have
                no affect when passed using this method; they need to be passed
                to the constructor or <methodname>startMvc()</methodname> method.
            </para>
        </example>

        <example id="zend.layout.options.examples.accessors">
            <title>Using Accessors</title>

            <para>
                Finally, you can also configure your <classname>Zend_Layout</classname>
                instance via accessors. All accessors implement a fluent
                interface, meaning their calls may be chained:
            </para>

            <programlisting language="php"><![CDATA[
$layout->setLayout('foo')
       ->setLayoutPath('/path/to/layouts')
       ->setContentKey('CONTENT');
]]></programlisting>
        </example>
    </sect2>
</sect1>
<!--
vim:se ts=4 sw=4 et:
-->