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

<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 24249 -->
<!-- Reviewed: no -->
<sect1 id="zend.layout.options">
    <title>Zend_Layout options de configuration</title>

    <para>
        <classname>Zend_Layout</classname> possède quelques options. Vous pouvez les spécifier
        grâce à des accesseurs. Autrement, en passant un tableau ou un objet
        <classname>Zend_Config</classname> au constructeur, ou à <methodname>startMvc()</methodname>. Un tableau
        d'options peut aussi être passé à <methodname>setOptions()</methodname>, un objet
        <classname>Zend_Config</classname> peut être passé à <methodname>setConfig()</methodname>. Les options
        de configuration sont les suivantes :
    </para>

    <itemizedlist>
        <listitem>
            <para>
                <emphasis>layout</emphasis> : le nom du script de layout. L'inflecteur traduit
                alors ceci en nom de fichier. Par défaut, il s'agit de "layout" traduit vers
                "layout.phtml". Les accesseurs sont <methodname>setLayout()</methodname> et
                <methodname>getLayout()</methodname>.
            </para>
        </listitem>

        <listitem>
            <para>
                <emphasis>layoutPath</emphasis> : l'url de base vers les scripts de layout.
                Les accesseurs sont <methodname>setLayoutPath()</methodname> et
                <methodname>getLayoutPath()</methodname>.
            </para>
        </listitem>

        <listitem>
            <para>
                <emphasis>contentKey</emphasis> : la variable de layout utilisée pour accéder
                au contenu par défaut (lorsqu'utilisée couplée avec <acronym>MVC</acronym>). La valeur par défaut est
                "content". Pour les accesseurs : <methodname>setContentKey()</methodname> et
                <methodname>getContentKey()</methodname>.
            </para>
        </listitem>

        <listitem>
            <para>
                <emphasis>mvcSuccessfulActionOnly</emphasis> : si une action envoie une
                exception et que cette option vaut <constant>TRUE</constant>, alors le layout ne sera pas
                rendu. (Ceci évite un double rendu alors que le plugin <link
                linkend="zend.controller.plugins.standard.errorhandler">ErrorHandler</link> est
                activé). Par défaut cette option est à <constant>TRUE</constant>. Ses accesseurs :
                <methodname>setMvcSuccessfulActionOnly()</methodname> et
                <methodname>getMvcSuccessfulActionOnly()</methodname>.
            </para>
        </listitem>

        <listitem>
            <para>
                <emphasis>view</emphasis> : l'objet de vue (<classname>Zend_View</classname>)
                utilisée par le layout pour rendre son script. Utilisé avec <acronym>MVC</acronym>,
                <classname>Zend_Layout</classname> cherchera à récupérer la vue via l'aide <link
                linkend="zend.controller.actionhelpers.viewrenderer">ViewRenderer</link>, si aucun
                objet de vue ne lui est passé explicitement. Les accesseurs sont
                <methodname>setView()</methodname> et <methodname>getView()</methodname>.
            </para>
        </listitem>

        <listitem>
            <para>
                <emphasis>helperClass</emphasis> : la classe représentant l'aide d'action
                lorsque <classname>Zend_Layout</classname> est utilisé avec les composants <acronym>MVC</acronym>. Par
                défaut il s'agit de
                <classname>Zend_Layout_Controller_Action_Helper_Layout</classname>. Les accesseurs
                sont <methodname>setHelperClass()</methodname> et <methodname>getHelperClass()</methodname>.
            </para>
        </listitem>

        <listitem>
            <para>
                <emphasis>pluginClass</emphasis> : la classe représentant le plugin de
                contrôleur frontal lorsque <classname>Zend_Layout</classname> est utilisé avec les
                composants <acronym>MVC</acronym>. Par défaut, il s'agit de
                <classname>Zend_Layout_Controller_Plugin_Layout</classname>. Les accesseurs sont
                <methodname>setPluginClass()</methodname> et <methodname>getPluginClass()</methodname>.
            </para>
        </listitem>

        <listitem>
            <para>
                <emphasis>inflector</emphasis> : l'inflecteur utilisé pour la résolution des
                noms de layout vers les scripts de layout. Voyez <link
                linkend="zend.layout.advanced.inflector">la documentation spécifique pour plus de
                détails</link>. Les accesseurs sont <methodname>setInflector()</methodname> et
                <methodname>getInflector()</methodname>.
            </para>
        </listitem>
    </itemizedlist>

    <note>
        <title>Vous devez passer les helperClass et pluginClass à startMvc()</title>

        <para>
            Pour que les paramètres <code>helperClass</code> et <code>pluginClass</code>
            agissent, vous devez les passer en options à <methodname>startMvc()</methodname>. Si vous les
            spécifiez après, ils seront ignorés.
        </para>
    </note>

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

        <para>
            Les exemples sont basés sur les paramètres <varname>$options</varname> et
            <varname>$config</varname> suivants :
        </para>

        <programlisting language="php"><![CDATA[
$options = array(
    'layout'     => 'foo',
    'layoutPath' => '/chemin/vers/layouts',
    'contentKey' => 'CONTENT'
    // ignorés si MVC n'est pas utilisé
);
]]></programlisting>

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

        <example id="zend.layout.options.examples.constructor">
            <title>Passer des options au constructeur ou à startMvc()</title>

            <para>
                Le constructeur et la méthode statique <methodname>startMvc()</methodname> acceptent soit
                un tableau d'options, soit un objet <classname>Zend_Config</classname>.
            </para>

            <para>Voyons le cas du tableau :</para>

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

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

            <para>Et maintenant avec l'objet de configuration :</para>

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

// Cas du constructeur:
$layout = new Zend_Layout($config);

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

            <para>
                C'est la manière la plus simple de configurer votre objet
                <classname>Zend_Layout</classname>.
            </para>
        </example>

        <example id="zend.layout.options.examples.setoptionsconfig">
            <title>Utilisation de setOptions() et setConfig()</title>

            <para>
                Pour configurer <classname>Zend_Layout</classname> après l'avoir instanciée,
                utilisez les méthodes <methodname>setOptions()</methodname> et <methodname>setConfig()</methodname> sur
                l'objet :
            </para>

            <programlisting language="php"><![CDATA[
// Utilisation d'un tableau d'options:
$layout->setOptions($options);

// Utilisation d'un objet Zend_Config:
$layout->setConfig($options);
]]></programlisting>

            <para>
                Notez cependant que certaines options comme <code>pluginClass</code> et
                <code>helperClass</code> n'auront aucun effet avec ses méthodes. Elles doivent être
                passées au constructeur ou à la méthode <methodname>startMvc()</methodname>.
            </para>
        </example>

        <example id="zend.layout.options.examples.accessors">
            <title>Utilisation des accesseurs</title>

            <para>
                Enfin, vous pouvez aussi configurer votre objet de
                <classname>Zend_Layout</classname> grâce à ses accesseurs. Ils peuvent s'utiliser
                chaînés (interface fluide):
            </para>

            <programlisting language="php"><![CDATA[
$layout->setLayout('foo')
       ->setLayoutPath('/chemin/vers/layouts')
       ->setContentKey('CONTENT');
]]></programlisting>
        </example>
    </sect2>
</sect1>