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

<!-- EN-Revision: 12891 -->
<sect1 id="zend.layout.advanced">
    <title>Zend_Layout, utilisation avancée</title>

    <para><classname>Zend_Layout</classname> permet d'être utilisé de manière plus pointu.</para>

    <para>Vous pouvez agir sur ces éléments :</para>

    <itemizedlist>
        <listitem>
            <para><emphasis>Objet de vue personnalisé.</emphasis> <classname>Zend_Layout</classname> accepte tout objet de vue
            implémentant l'interface <classname>Zend_View_Interface</classname>.</para>
        </listitem>

        <listitem>
            <para><emphasis>Plugin contrôleur frontal personnalisé.</emphasis> <classname>Zend_Layout</classname> est livré avec
            un plugin qui rend le layout automatiquement avant de renvoyer la réponse (utilisation MVC). Vous pouvez
            injecter votre propre plugin.</para>
        </listitem>

        <listitem>
            <para><emphasis>Aide d'action personnalisée.</emphasis> <classname>Zend_Layout</classname> est livrée avec une aide
            d'action qui devrait en théorie suffire dans la majorité des cas. C'est un proxy vers l'objet
            <classname>Zend_Layout</classname>. Vous pouvez cependant utiliser votre propre classe d'aide.</para>
        </listitem>

        <listitem>
            <para><emphasis>Résolveur de chemin de script personnalisé</emphasis>. <classname>Zend_Layout</classname> vous permet
            d'utiliser votre <link linkend="zend.filter.inflector">inflecteur</link> pour la résolution des scripts de
            layout ou de modifier l'inflecteur par défaut.</para>
        </listitem>
    </itemizedlist>

    <sect2 id="zend.layout.advanced.view">
        <title>Objets de vue personnalisés</title>

        <para><classname>Zend_Layout</classname> accepte des objets de vue implémentant <classname>Zend_View_Interface</classname> ou
        étendant <classname>Zend_View_Abstract</classname> pour le rendu du script de layout. Passez le en paramètre au
        constructeur ou à <code>startMvc()</code>, ou utilisez l'accesseur <code>setView()</code> :</para>

        <programlisting role="php"><![CDATA[
$view = new My_Custom_View();
$layout->setView($view);
]]></programlisting>

        <note>
            <title>Attention à vos implémentations de Zend_View</title>

            <para>Même si <classname>Zend_Layout</classname> vous permet d'utiliser votre propre objet de vue (implémentant
            <classname>Zend_View_Interface</classname>), vous pouvez rencontrer des problèmes si votre vue n'a pas accès à
            certaines aides de vue, en particulier les aides "layout" et <link
            linkend="zend.view.helpers.initial.placeholder">"placeholder"</link>. <classname>Zend_Layout</classname> effectue des
            affectations de variables sur la vue via ces aides.</para>

            <para>Si vous avez besoin d'un objet <classname>Zend_View</classname> personnalisé qui ne supporte pas ces aides de
            vue, vous devrez alors trouver un moyen de passer les variables du layout à la vue. Par exemple, en étendant
            l'objet <classname>Zend_Layout</classname> et en rédéfinissant la méthode <code>render()</code> en passant des
            variables à la vue. Aussi, vous pouvez créer votre propre plugin qui s'occupe de passer ces variables avant
            le rendu du layout.</para>

            <para>De même, si votre implémentation de la vue permet l'extension via des plugins, vous pouvez à tout
            moment accéder aux variables du layout grâce à l'aide <link
            linkend="zend.view.helpers.initial.placeholder">placeholder</link> en utilisant la clé "Zend_Layout"
            :</para>

            <programlisting role="php"><![CDATA[
$placeholders = new Zend_View_Helper_Placeholder();
$layoutVars   = $placeholders->placeholder('Zend_Layout')
                             ->getArrayCopy();
]]></programlisting>
        </note>
    </sect2>

    <sect2 id="zend.layout.advanced.plugin">
        <title>Plugin de contrôleur frontal personnalisé</title>

        <para>Lorsqu'utilisé avec les composants MVC, <classname>Zend_Layout</classname> enregistre un plugin de contrôleur
        frontal qui se charge du rendu du layout juste avant la fin de la boucle de distribution. Ceci convient à la
        majorité des cas, si cependant vous avez besoin de construire votre propre plugin, passez son nom dans l'option
        <code>pluginClass</code> de la méthode <code>startMvc()</code>.</para>

        <para>Votre plugin doit alors étendre <classname>Zend_Controller_Plugin_Abstract</classname>, et devrait accepter un objet
        <classname>Zend_Layout</classname> lors de sa construction.</para>

        <para>La classe par défaut du plugin est <classname>Zend_Layout_Controller_Plugin_Layout</classname>.</para>
    </sect2>

    <sect2 id="zend.layout.advanced.helper">
        <title>Aide d'action personnalisée</title>

        <para>Si les composants MVC sont utilisés, alors <classname>Zend_Layout</classname> enregistre une classe d'aide d'action
        dans le gestionnaire d'aides (helper broker). Par défaut, il s'agit de
        <classname>Zend_Layout_Controller_Action_Helper_Layout</classname>. Cette aide agit comme un proxy vers l'instance de
        <classname>Zend_Layout</classname> et permet d'y accéder dans vos actions.</para>

        <para>Si vous voulez utiliser votre propre classe, celle-ci devra alors étendre
        <classname>Zend_Controller_Action_Helper_Abstract</classname>. Passez le nom de la classe dans l'option
        <code>helperClass</code> de la méthode <code>startMvc()</code>.</para>
    </sect2>

    <sect2 id="zend.layout.advanced.inflector">
        <title>Résolution de chemin de script personnalisé (inflecteur)</title>

        <para><classname>Zend_Layout</classname> utilise <classname>Zend_Filter_Inflector</classname> pour établir une chaine de filtre
        permettant la résolution du nom du layout, vers le fichier y correspondant. Par défaut, les règles
        "Word_CamelCaseToDash" suivie de "StringToLower" sont utilisées. Le suffixe "phtml" est ensuite ajouté :</para>

        <itemizedlist>
            <listitem>
                <para>"foo" sera transformé en "foo.phtml".</para>
            </listitem>

            <listitem>
                <para>"FooBarBaz" sera transformé vers "foo-bar-baz.phtml".</para>
            </listitem>
        </itemizedlist>

        <para>Vous pouvez personnaliser l'inflecteur de 3 manières différentes : Modifier la cible et/ou le suffixe
        grâce à des accesseurs dans <classname>Zend_Layout</classname> ; Modifier les règles de l'inflecteur associé à
        <classname>Zend_Layout</classname> ; Ou encore créer votre propre inflecteur et le passer à
        <classname>Zend_Layout::setInflector()</classname>.</para>

        <example id="zend.layout.advanced.inflector.accessors">
            <title>Utilisation des accesseurs pour modifier l'inflecteur</title>

            <para>L'inflecteur par défaut de <classname>Zend_Layout</classname> utilise des marqueurs statiques pour la cible et
            le suffixe. 2 accesseurs vous sont donc proposés :</para>

            <programlisting role="php"><![CDATA[
// Affecte une cible à l'inflecteur:
$layout->setInflectorTarget('layouts/:script.:suffix');

// Affecte le suffixe:
$layout->setViewSuffix('php');
]]></programlisting>
        </example>

        <example id="zend.layout.advanced.inflector.directmodification">
            <title>Modification directe de l'inflecteur de Zend_Layout</title>

            <para>Les inflecteurs fonctionnent avec un cible et plusieurs règles. La cible par défaut utilisée pour
            <classname>Zend_Layout</classname> est ":script.:suffix" ; ":script" représente le nom du script de layout, et
            ":suffix" est une règle statique.</para>

            <para>Imaginons que vous vouliez que le suffixe du script de layout soit "html", et que vous vouliez séparer
            les mots en CasseMélangée ou en notationCamel avec des tirets-bats au lieu des tirets. De plus, vous voulez
            chercher vos scripts dans un sous-dossier "layouts" :</para>

            <programlisting role="php"><![CDATA[
$layout->getInflector()->setTarget('layouts/:script.:suffix')
                       ->setStaticRule('suffix', 'html')
                       ->setFilterRule(array('Word_CamelCaseToUnderscore'));
]]></programlisting>
        </example>

        <example id="zend.layout.advanced.inflector.custom">
            <title>Inflecteur personnalisé</title>

            <para>Dans la plupart des cas, modifier l'inflecteur sera suffisant. Vous pouvez cependant créer votre
            propre inflecteur, pour l'utiliser à différents endroits par exemple, et le passer à
            <classname>Zend_Layout</classname>:</para>

            <programlisting role="php"><![CDATA[
$inflector = new Zend_Filter_Inflector('layouts/:script.:suffix');
$inflector->addRules(array(
    ':script' => array('Word_CamelCaseToUnderscore'),
    'suffix'  => 'html'
));
$layout->setInflector($inflector);
]]></programlisting>
        </example>

        <note>
            <title>L'inflecteur peut être désactivé</title>

            <para>L'inflecteur peut être désactivé si vous spécifiez, par exemple, un chemin absolu pour un script
            utilisé par <classname>Zend_Layout</classname>. Les méthodes <code>enableInflection()</code> et
            <code>disableInflection()</code> vous y aideront.</para>
        </note>
    </sect2>
</sect1>