<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 24249 -->
<!-- Reviewed: no -->
<sect1 id="learning.layout.usage">
    <title>Utiliser Zend_Layout</title>

    <para>
        L'utilisation classique de <classname>Zend_Layout</classname> est simple. En supposant
        que vous utilisez <classname>Zend_Application</classname>, il suffit simplement de
        passer des options de configuration et créer un script de layout.
    </para>

    <sect2 id="learning.layout.usage.configuration">
        <title>Layout Configuration</title>

        <para>
            L'endroit recommandé pour stocker les layouts est
            "<filename>layouts/scripts/</filename>" dans l'application:
        </para>

        <programlisting language="text"><![CDATA[
application
|-- Bootstrap.php
|-- configs
|   `-- application.ini
|-- controllers
|-- layouts
|   `-- scripts
|       |-- layout.phtml
]]></programlisting>

        <para>
            Pour initialiser <classname>Zend_Layout</classname>, ajouter ceci à votre fichier
            de configuration ("<filename>application/configs/application.ini</filename>"):
        </para>

        <programlisting language="dosini"><![CDATA[
resources.layout.layoutPath = APPLICATION_PATH "/layouts/scripts"
resources.layout.layout = "layout"
]]></programlisting>

        <para>
            La première ligne indique où chercher les scripts de layout; la seconde donne le
            nom du script à utiliser (l'extension est supposée "<filename>.phtml</filename>"
            par défaut).
        </para>
    </sect2>

    <sect2 id="learning.layout.usage.layout-script">
        <title>Créer un script de layout</title>

        <para>
            Il convient maintenant de créer un script de layout. D'abord, vérifiez l'existance du
            dossier "<filename>application/layouts/scripts</filename>"; puis ouvrez un éditeur et
            créez une mise en page balisée. Les scripts de layout sont des scripts de vue, avec
            quelques différences tout de même.
        </para>

        <programlisting language="php"><![CDATA[
<html>
<head>
    <title>My Site</title>
</head>
<body>
    <?php echo $this->layout()->content ?>
</body>
</html>
]]></programlisting>

        <para>
            Dans l'exemple ci-dessus, un appel à l'aide de vue <methodname>layout()</methodname> y
            est effectué. Lorsque vous activez l'instance de <classname>Zend_Layout</classname>,
            vous avez aussi accès à une aide d'acion et de vue qui permettent d'accéder à l'instance
            de <classname>Zend_Layout</classname>; et vous pouvez ainsi appeler des méthodes
            sur l'objet layout. Dans notre cas, nous récupérons une variable appelée
            <varname>$content</varname>, et nous l'affichons. Par défaut, <varname>$content</varname>
            est peuplée du contenu de la vue rendue pour l'action en cours. Sinon, tout ce que vous
            feriez dans un script de vue est valide dans un script de layout: appel d'aides ou
            de méthodes sur la vue.
        </para>

        <para>
            Maintenant, nous avons un script de layout fonctionnel et notre application sait où le
            trouver.
        </para>
    </sect2>

    <sect2 id="learning.layout.usage.access">
        <title>Accéder à l'objet Layout</title>

        <para>
            Il est probable que vous ayez besoin d'accéder à l'objet instance layout. Cela est
            possible de trois manières:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <emphasis>Dans des scripts de vue:</emphasis> utilisez l'aide de vue
                    <methodname>layout()</methodname>, qui retourne l'instance de
                    <classname>Zend_Layout</classname> enregistrée au moyen du plugin MVC.
                </para>

                <programlisting language="php"><![CDATA[
<?php $layout = $this->layout(); ?>
]]></programlisting>

                <para>
                    Comme cela retourne l'objet de layout, vous pouvez appeler dessus toute méthode
                    ou assigner des variables.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>Dans vos contrôleurs:</emphasis> utilisez ici l'aide d'action
                    <methodname>layout()</methodname>, qui agit comme l'aide de vue.
                </para>

                <programlisting language="php"><![CDATA[
// Appel de l'aide comme méthode sur le gestionnaire d'aides:
$layout = $this->_helper->layout();

// Ou, de manière plus détaillée:
$helper = $this->_helper->getHelper('Layout');
$layout = $helper->getLayoutInstance();
]]></programlisting>

                <para>
                    Comme avec l'aide de vue, vous pouvez appeler dès lors n'importe quelle
                    méthode de layout ou lui assigner des variables.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>Ailleurs: </emphasis> utilisez la méthode statique
                    <methodname>getMvcInstance()</methodname>. Cette méthode retourne l'instance
                    de layout comme déja vu plus haut maintenant.
                </para>

                <programlisting language="php"><![CDATA[
$layout = Zend_Layout::getMvcInstance();
]]></programlisting>
            </listitem>

            <listitem>
                <para>
                    <emphasis>Via le bootstrap: </emphasis> utilisez la ressource layout qui
                    crée, configure et retourne l'objet <classname>Zend_Layout</classname>.
                </para>

                <programlisting language="php"><![CDATA[
$layout = $bootstrap->getResource('Layout');
]]></programlisting>

                <para>
                    Partout où vous avez accès à l'objet bootstrap, il s'agit de la méthode
                    recommandée par rapport à <methodname>getMvcInstance()</methodname>.
                </para>
            </listitem>
        </itemizedlist>
    </sect2>

    <sect2 id="learning.layout.usage.other-operations">
        <title>Autres opérations</title>

        <para>
            Dans la plupart des cas, le script de configuration de layout ci-dessus (avec quelques
            modifications) répondra à vos besoins. Cependant, dans certains cas il peut être
            intéressant d'utiliser d'autres fonctionnalités. Dans les exemples qui suivent,
            vous allez utiliser une des<link
                linkend="learning.layout.usage.access">méthodes listées ci-dessus</link> pour
            récupérer l'objet layout.
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <emphasis>Affecter les variables de layout</emphasis>.
                    <classname>Zend_Layout</classname> garde en mémoire les variables de vue
                    spécifiques à la layout, la clé <varname>$content</varname> en est un
                    exemple. Vous pouvez assigner et récupérer ces variables grâce à la méthode
                    <methodname>assign()</methodname> ou en y accédant comme des attributs
                    classiques.
                </para>

                <programlisting language="php"><![CDATA[
// Affecter du contenu:
$layout->somekey = "foo"

// Afficher ce même contenu:
echo $layout->somekey; // 'foo'

// Utiliser la méthode assign() :
$layout->assign('someotherkey', 'bar');

// Accéder à la variable reste identique:
echo $layout->someotherkey; // 'bar'
]]></programlisting>
            </listitem>

            <listitem>
                <para>
                    <methodname>disableLayout()</methodname>. Occasionellement, vous pouriez vouloir
                    d"sactiver totalement les layouts, par exemple, pour répondre à une requête AJAX
                    ou autravers d'une API RESTful. Dans ces cas, appelez la méthode
                    <methodname>disableLayout()</methodname> de l'objet layout.
                </para>

                <programlisting language="php"><![CDATA[
$layout->disableLayout();
]]></programlisting>

                <para>
                    Le contraire de cette méthode, <methodname>enableLayout()</methodname>, permet
                    de ré-activer le rendu des layouts pour l'action en cours.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>Utiliser un autre script de layout</emphasis>: Si vous avez plusieurs scripts
                    de layout pour votre application, vous pouvez selectionner lequel rendre grâce à la
                    méthode <methodname>setLayout()</methodname>. Précisez alors le nom du script de layout,
                    sans l'extension.
                </para>

                <programlisting language="php"><![CDATA[
// Utiliser le script de layout "alternate.phtml":
$layout->setLayout('alternate');
]]></programlisting>

                <para>
                    Le script de layout doit se trouver dans le <varname>$layoutPath</varname> précisé via
                    la configuration (en bootstrap générallement). <classname>Zend_Layout</classname>
                    utilisera le nouveau script à rendre.
                </para>
            </listitem>
        </itemizedlist>
    </sect2>
</sect1>
