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

<?xml version="1.0" encoding="UTF-8"?>
<!-- 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:
    </para>

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

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

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

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

        <listitem>
            <para>
                Spécifier une chaine 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 chaine 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:
    </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:
    </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: (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:
    </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. Cette 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>:
    </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:
    </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.
    </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; cependant afficher le placeholder rendra le contenu "fixe" suivant les règles définies dans le
        bootstrap ainsi que le contenu aggré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):
    </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>