repo_zf1/documentation/manual/fr/tutorials/view-placeholders-basics.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 24249 -->
<!-- Reviewed: no -->
<sect1 id="learning.view.placeholders.basics">
    <title>Utilisation de base des Placeholders</title>

    <para>
        Zend Framework définit une aide de vue générique <methodname>placeholder()</methodname> que
        vous pouvez utiliser pour créer vos placeholders ("conteneurs") personnalisés. Il propose
        aussi une variété de placeholders pour des fonctionnalités très demandées comme préciser un
        <emphasis>DocType</emphasis>, le titre d'une page, etc.
    </para>

    <para>
        Tous les placeholders agissent de la même manière. Ce sont des conteneurs, et donc vous
        pouvez les manipuler comme des collections. Vous pouvez ainsi&#160;:
    </para>

    <itemizedlist>
        <listitem>
            <para>
                <emphasis>Ajouter (append)</emphasis> ou <emphasis>préfixer(prepend)</emphasis> des
                entités dans la collection.
            </para>
        </listitem>

        <listitem>
            <para>
                <emphasis>Remplacer (replace)</emphasis> toute la collection avec une seule valeur.
            </para>
        </listitem>

        <listitem>
            <para>
                Spécifier une chaîne utilisée pour <emphasis>préfixer le contenu</emphasis> de la
                collection lors de son rendu.
            </para>
        </listitem>

        <listitem>
            <para>
                Spécifier une chaîne utilisée pour <emphasis>ajouter le contenu</emphasis> de la
                collection lors de son rendu.
            </para>
        </listitem>

        <listitem>
            <para>
                Spécifier une chaîne utilisée pour <emphasis>séparer du contenu</emphasis> de la
                collection lors de son rendu.
            </para>
        </listitem>

        <listitem>
            <para>
                <emphasis>Capturer du contenu</emphasis> dans la collection.
            </para>
        </listitem>

        <listitem>
            <para>
                <emphasis>Rendre</emphasis> le contenu agrégé.
            </para>
        </listitem>
    </itemizedlist>

    <para>
        Typiquement, vous appelerez cette aide de vue sans argument, ce qui retournera le conteneur
        sur lequel opérer. Après vous afficherez (echo) ce contenu ou appelerez une méthode dessus
        pour le remplir ou le configurer. Si le conteneur est vide, son rendu sera une simple chaîne
        vide, sinon, le contenu sera aggrégé en fonction des règles que vous avez fixées.
    </para>

    <para>
        Par exemple, créons une barre de menu qui contient des "blocs" de contenu. Supposons que la
        structure de chaque bloc ressemble à ceci&#160;:
    </para>

    <programlisting language="html"><![CDATA[
<div class="sidebar">
    <div class="block">
        <p>
            Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vivamus
            consectetur aliquet odio ac consectetur. Nulla quis eleifend
            tortor. Pellentesque varius, odio quis bibendum consequat, diam
            lectus porttitor quam, et aliquet mauris orci eu augue.
        </p>
    </div>
    <div class="block">
        <ul>
            <li><a href="/some/target">Link</a></li>
            <li><a href="/some/target">Link</a></li>
        </ul>
    </div>
</div>
]]></programlisting>

    <para>
        Le contenu variera en fonction du contrôleur et de l'action, mais la structure est
        identique, elle. Configurons en premier lieu la barre de menu dans une méthode du
        bootstrap&#160;:
    </para>

    <programlisting language="php"><![CDATA[
class Bootstrap extends Zend_Application_Bootstrap_Bootstrap
{
    // ...

    protected function _initSidebar()
    {
        $this->bootstrap('View');
        $view = $this->getResource('View');

        $view->placeholder('sidebar')
             // "prefix" -> contenu à afficher une fois avant les données
             // dans la collection
             ->setPrefix("<div class=\"sidebar\">\n    <div class=\"block\">\n")
             // "separator" -> contenu à afficher entre chaque entité de
             // la collection
             ->setSeparator("</div>\n    <div class=\"block\">\n")
             // "postfix" -> contenu à afficher une fois après les données
             // dans la collection
             ->setPostfix("</div>\n</div>");
    }

    // ...
}
]]></programlisting>

    <para>
        Le code ci-dessus définit un placeholder, "sidebar", qui n'a pas d'entité. Ce code
        configure la structure de base du placeholder, selon nos désirs.
    </para>

    <para>
        Maintenant supposons que pour toutes les actions du contrôleur "user" nous voulons un
        bloc en haut qui contienne des informations. Nous pouvons faire cela de deux manières&#160;:
        (a) nous pourrions ajouter le contenu au placeholder directement dans la méthode
        <methodname>preDispatch()</methodname> du contrôleur, ou (b) nous pourrions rendre un
        script de vue depuis la méthode <methodname>preDispatch()</methodname>. Nous utiliserons le
        cas (b), car il propose une séparation propre des logiques en laissant la vue classique
        contenir ses données utiles.
    </para>

    <para>
        Nous appelerons le script de vue "<filename>user/_sidebar.phtml</filename>", et nous le
        remplirons comme ceci&#160;:
    </para>

    <programlisting language="php"><![CDATA[
<?php $this->placeholder('sidebar')->captureStart() ?>
<h4>User Administration</h4>
<ul>
    <li><a href="<?php $this->url(array('action' => 'list')) ?>">
        List</a></li>
    <li><a href="<?php $this->url(array('action' => 'create')) ?>">
        Create</a></a></li>
</ul>
<?php $this->placeholder('sidebar')->captureEnd() ?>
]]></programlisting>

    <para>
        L'exemple ci-dessus utilise les possibilités de capture dynamique de contenu des
        placeholders. Par défaut, le contenu est ajouté à la suite ce qui permet d'en agréger. Cet
        exemple utilise des aides de vues et du contenu <acronym>HTML</acronym> statique pour
        générer un menu qui est capturé et ajouté au placeholder.
    </para>

    <para>
        Pour utiliser le script de vue, nous écrirons ceci dans la méthode
        <methodname>preDispatch()</methodname>&#160;:
    </para>

    <programlisting language="php"><![CDATA[
class UserController extends Zend_Controller_Action
{
    // ...

    public function preDispatch()
    {
        // ...

        $this->view->render('user/_sidebar.phtml');

        // ...
    }

    // ...
}
]]></programlisting>

    <para>
        Notez que nous ne capturons pas le rendu, il n'y a pas besoin car le contenu complet de ce
        script de vue est déja capturé dans un placeholder.
    </para>

    <para>
        Maintenant imaginons que l'action "view" dans ce même contrôleur ait besoin de présenter des
        informations. Dans "<filename>user/view.phtml</filename>" il pourrait y avoir ceci&#160;:
    </para>

    <programlisting language="php"><![CDATA[
$this->placeholder('sidebar')
     ->append('<p>User: ' . $this->escape($this->username) .  '</p>');
]]></programlisting>

    <para>
        Cet exemple utilise la méthode <methodname>append()</methodname> et lui passe du contenu à
        agréger.
    </para>

    <para>
        Enfin, modifions le script de layout pour rendre le placeholder&#160;:
    </para>

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

    <para>
        Pour les contrôleurs et les actions que ne remplissent pas le placeholder "sidebar", aucun
        contenu ne sera rendu&#160;; cependant afficher le placeholder rendra le contenu "fixe"
        suivant les règles définies dans le bootstrap ainsi que le contenu agrégé dans
        l'application. Dans le cas de l'action "<filename>/user/view</filename>", en supposant que
        le nom de l'utilisateur est "matthew", nous pouvons récupérer le contenu de la barre de menu
        comme ceci (formaté pour la lisibilité de l'exemple)&#160;:
    </para>

    <programlisting language="html"><![CDATA[
<div class="sidebar">
    <div class="block">
        <h4>User Administration</h4>
        <ul>
            <li><a href="/user/list">List</a></li>
            <li><a href="/user/create">Create</a></a></li>
        </ul>
    </div>
    <div class="block">
        <p>User: matthew</p>
    </div>
</div>
]]></programlisting>

    <para>
        Les possibilités sont immenses en ce qui concerne les placeholders et les layouts, essayez
        les et lisez les <link linkend="zend.view.helpers.initial.placeholder">sections relatives
        du manuel</link> pour plus d'informations.
    </para>
</sect1>