<!-- EN-Revision: 12116 -->
<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 MVC, 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 role="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 role="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" />
    <?= $this->headTitle() ?>
    <?= $this->headScript() ?>
    <?= $this->headStyle() ?>
</head>
<body>
    <?= $this->render('header.phtml') ?>

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

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

    <?= $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 MVC.</para>

        <para><classname>Zend_Layout::startMvc()</classname> 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 MVC </para>

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

        <para><code>startMvc()</code> 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 role="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 role="php"><![CDATA[
<?php $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 <code>getMvcInstance()</code> :</para>

        <programlisting role="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 <code>FooController::indexAction()</code>, qui va
        rendre du contenu dans le segment par défaut de la réponse. Ensuite il forward vers
        <code>NavController::menuAction()</code>, qui rend son contenu dans un segment nommé 'nav'. Enfin, vous
        forwardez vers <code>CommentController::fetchAction()</code> 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 role="php"><![CDATA[
<body>
    <!-- rend /nav/menu -->
    <div id="nav"><?= $this->layout()->nav ?></div>

    <!-- rend /foo/index + /comment/fetch -->
    <div id="content"><?= $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 MVC, 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 role="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 CSS. 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>