<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 17175 -->
<!-- Reviewed: no -->
<sect1 id="zend.layout.quickstart">
    <title>Zend_Layout - Démarrage rapide</title>

    <para>
        Il y a deux modes d'utilisation de <classname>Zend_Layout</classname> : avec Zend
        Framework <acronym>MVC</acronym>, et sans.
    </para>

    <sect2 id="zend.layout.quickstart.layouts">
        <title>Scripts de layout</title>

        <para>
            Dans tous les cas, un script de layout est nécessaire. Les scripts de layout
            utilisent simplement Zend_View (ou une implémentation particulière personnalisée). Les
            variables de layout sont enregistrées dans le <link
            linkend="zend.view.helpers.initial.placeholder">placeholder</link> <code>Layout</code>,
            et peuvent être accédées via l'aide de vue placeholder ou directement en tant que
            propriétés de l'objet layout.
        </para>

        <para>Par exemple :</para>

        <programlisting language="php"><![CDATA[
<!DOCTYPE html
    PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html>
<head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    <title>Mon Site</title>
</head>
<body>
<?php
    // récupère la clé "content" via l'aide de vue layout :
    echo $this->layout()->content;

    // récupère la clé "foo" via l'aide de vue placeholder :
    echo $this->placeholder('Zend_Layout')->foo;

    // récupère l'objet layout, et accède à diverses clés :
    $layout = $this->layout();
    echo $layout->bar;
    echo $layout->baz;
?>
</body>
</html>
]]></programlisting>

        <para>
            Toutes les aides de vue enregistrées sont accessibles dans
            <classname>Zend_Layout</classname> car il utilise <classname>Zend_View</classname> pour
            son propre rendu. Vous pouvez aussi accéder aux variables de la vue. Les aides <link
            linkend="zend.view.helpers.initial.placeholder">placeholder </link> sont très pratiques
            pour l'accès aux éléments tels que &lt;head&gt;, les scripts, les méta, etc. :
        </para>

        <programlisting language="php"><![CDATA[
<!DOCTYPE html
    PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html>
<head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    <?php echo $this->headTitle() ?>
    <?php echo $this->headScript() ?>
    <?php echo $this->headStyle() ?>
</head>
<body>
    <?= $this->render('header.phtml') ?>

    <div id="nav"><?php echo $this->placeholder('nav') ?></div>

    <div id="content"><?php echo $this->layout()->content ?></div>

    <?php echo $this->render('footer.phtml') ?>
</body>
</html>
]]></programlisting>
    </sect2>

    <sect2 id="zend.layout.quickstart.mvc">
        <title>Utilisation de Zend_Layout avec le système MVC de Zend Framework</title>

        <para>
            <classname>Zend_Controller</classname> propose une manière d'étendre ses
            fonctionnalités au travers de <link linkend="zend.controller.plugins">plugins de
            contrôleur frontal</link> et <link linkend="zend.controller.actionhelpers">d'aides
            d'action</link>. <classname>Zend_View</classname> propose aussi des <link
            linkend="zend.view.helpers">aides</link>. <classname>Zend_Layout</classname> utilise
            toutes ces possibilités lorsqu'employé avec les composants <acronym>MVC</acronym>.
        </para>

        <para>
            <methodname>Zend_Layout::startMvc()</methodname> crée une instance de
            <classname>Zend_Layout</classname> avec des paramètres de configuration optionnels.
            Cette méthode enregistre aussi un plugin de contrôleur frontal qui s'occupe du rendu du
            layout rempli, lorsque la boucle de distribution est terminée. Elle enregistre également
            une aide d'action qui permet aux actions d'accéder à l'objet <code>layout</code>. Enfin,
            l'aide de vue layout, elle, donne accès à l'objet layout depuis la vue.
        </para>

        <para>
            Regardons d'abord comment initialiser Zend_Layout afin de l'utiliser dans un
            contexte <acronym>MVC</acronym>
        </para>

        <programlisting language="php"><![CDATA[
// Dans le fichier de démarrage (bootstrap)
Zend_Layout::startMvc();
]]></programlisting>

        <para>
            <methodname>startMvc()</methodname> peut prendre en paramètre un tableau d'options ou un objet
            <classname>Zend_Config</classname> pour personnaliser l'instance. Ces options sont
            détaillées dans <xref linkend="zend.layout.options" />.
        </para>

        <para>
            Dans le contrôleur d'action, vous pouvez donc accéder à l'instance de layout via
            l'aide d'action :
        </para>

        <programlisting language="php"><![CDATA[
class FooController extends Zend_Controller_Action
{
    public function barAction()
    {
        // désactive les layouts pour cette action
        $this->_helper->layout->disableLayout();
    }

    public function bazAction()
    {
        // utilise un script de layout différent pour
        // cette action
        $this->_helper->layout->setLayout('foobaz');
    };
}
]]></programlisting>

        <para>
            Dans vos scripts de vue, utiliser l'aide <code>layout</code> pour accéder à
            l'instance de <classname>Zend_Layout</classname>. Notez que cette aide est différente
            des autres car elle ne retourne pas une chaîne, mais bien un objet. Vous pouvez donc
            enchaîner une méthode immédiatement :
        </para>

        <programlisting language="php"><![CDATA[
$this->layout()->setLayout('foo'); // utilise un script de layout spécifique
]]></programlisting>

        <para>
            Autrement, vous pouvez n'importe où accéder à votre instance de
            <classname>Zend_Layout</classname> via la méthode statique <methodname>getMvcInstance()</methodname>
            :
        </para>

        <programlisting language="php"><![CDATA[
// Retourne null si startMvc() n'a pas été appelée auparavant
$layout = Zend_Layout::getMvcInstance();
]]></programlisting>

        <para>
            Enfin, le plugin de contrôleur frontal <classname>Zend_Layout</classname> dispose
            d'une caractéristique annexe au rendu automatique du layout : il analyse les segments de
            l'objet de réponse et les assigne en tant que variables de layout dans vos scripts de
            layout. Le segment "default" est assigné à la variable "content". Ceci permet de mettre
            la main sur le contenu rendu dans l'action principale.
        </para>

        <para>
            Par exemple, supposons que votre code rencontre d'abord
            <methodname>FooController::indexAction()</methodname>, qui va rendre du contenu dans le segment par
            défaut de la réponse. Ensuite il forward vers <methodname>NavController::menuAction()</methodname>,
            qui rend son contenu dans un segment nommé 'nav'. Enfin, vous forwardez vers
            <methodname>CommentController::fetchAction()</methodname> pour récupérer des commentaires, mais vous
            les rendez aussi dans le segment par défaut de la réponse (ce qui va rajouter du
            contenu). Votre script de layout peut alors rendre chaque segment de manière séparée
            :
        </para>

        <programlisting language="php"><![CDATA[
<body>
    <!-- rend /nav/menu -->
    <div id="nav"><?php echo $this->layout()->nav ?></div>

    <!-- rend /foo/index + /comment/fetch -->
    <div id="content"><?php echo $this->layout()->content ?></div>
</body>
]]></programlisting>

        <para>
            Cette approche est particulièrement utile avec <link
            linkend="zend.controller.actionhelpers.actionstack">l'aide d'action</link> ActionStack
            et son <link linkend="zend.controller.plugins.standard.actionstack"> plugin</link> du
            même nom. Vous pouvez les utiliser pour gérer une pile d'actions et ainsi décomposer vos
            processus.
        </para>
    </sect2>

    <sect2 id="zend.layout.quickstart.standalone">
        <title>Utilisation de Zend_Layout en composant indépendant</title>

        <para>
            Pris indépendamment des composants <acronym>MVC</acronym>, Zend_Layout n'offre pas tout à fait les
            mêmes possibilités et la même flexibilité. Cependant, vous bénéficiez de deux avantages
            :
        </para>

        <itemizedlist>
            <listitem>
                <para>Des variables propres aux layouts.</para>
            </listitem>

            <listitem>
                <para>
                    Isolation du script de layout, de son contenu issu des scripts de
                    vue.
                </para>
            </listitem>
        </itemizedlist>

        <para>
            En tant que composant indépendant, instanciez un objet
            <classname>Zend_Layout</classname>, configurez le au moyen d'accesseurs, passez vos
            variables comme des propriétés de l'objet, et rendez le layout :
        </para>

        <programlisting language="php"><![CDATA[
$layout = new Zend_Layout();

// Spécification du chemin des scripts layout:
$layout->setLayoutPath('/chemin/vers/layouts');

// passage de quelques variables :
$layout->content = $content;
$layout->nav     = $nav;

// Utilisation d'un script de layout "foo" :
$layout->setLayout('foo');

// rendu du layout :
echo $layout->render();
]]></programlisting>
    </sect2>

    <sect2 id="zend.layout.quickstart.example">
        <title>Layout d'exemple</title>

        <para>
            Une image valant mieux qu'un paragraphe, voyez donc celle-ci qui décrit
            l'utilisation :
        </para>

        <para>
            <inlinegraphic align="center" fileref="figures/zend.layout.quickstart.example.png"
            format="PNG" valign="middle" />
        </para>

        <para>
            Avec cette approche, vous pouvez régler vos mises en forme <acronym>CSS</acronym>. En positionnement
            absolu, par exemple, vous pourriez rendre la barre de navigation plus tard, en fin. Le
            mécanisme d'obtention du contenu reste le même cependant.
        </para>
    </sect2>
</sect1>