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

<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 24249 -->
<!-- Reviewed: no -->
<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 <acronym>MVC</acronym>). 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 à <methodname>startMvc()</methodname>, ou utilisez l'accesseur
            <methodname>setView()</methodname> :
        </para>

        <programlisting language="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
                <methodname>render()</methodname> 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 language="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 <acronym>MVC</acronym>, <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 <methodname>startMvc()</methodname>.
        </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 <acronym>MVC</acronym> 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
            <methodname>startMvc()</methodname>.
        </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 à
            <methodname>Zend_Layout::setInflector()</methodname>.
        </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 language="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 language="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 language="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
                <methodname>enableInflector()</methodname> et <methodname>disableInflector()</methodname> vous y
                aideront.
            </para>
        </note>
    </sect2>
</sect1>