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

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- EN-Revision: 20109 -->
   3 <!-- Reviewed: no -->
   4 <sect1 id="learning.view.placeholders.basics">
   5     <title>Utilisation de base des Placeholders</title>
   6
   7     <para>
   8         Zend Framework définit une aide de vue générique <methodname>placeholder()</methodname> que
   9         vous pouvez utiliser pour créer vos placeholders ("conteneurs") personnalisés. Il propose
  10         aussi une variété de placeholders pour des fonctionnalités très demandées comme préciser un
  11         <emphasis>DocType</emphasis>, le titre d'une page, etc.
  12     </para>
  13
  14     <para>
  15         Tous les placeholders agissent de la même manière. Ce sont des conteneurs, et donc vous
  16         pouvez les manipuler comme des collections. Vous pouvez ainsi&#160;:
  17     </para>
  18
  19     <itemizedlist>
  20         <listitem>
  21             <para>
  22                 <emphasis>Ajouter (append)</emphasis> ou <emphasis>préfixer(prepend)</emphasis> des
  23                 entités dans la collection.
  24             </para>
  25         </listitem>
  26
  27         <listitem>
  28             <para>
  29                 <emphasis>Remplacer (replace)</emphasis> toute la collection avec une seule valeur.
  30             </para>
  31         </listitem>
  32
  33         <listitem>
  34             <para>
  35                 Spécifier une chaîne utilisée pour <emphasis>préfixer le contenu</emphasis> de la
  36                 collection lors de son rendu.
  37             </para>
  38         </listitem>
  39
  40         <listitem>
  41             <para>
  42                 Spécifier une chaîne utilisée pour <emphasis>ajouter le contenu</emphasis> de la
  43                 collection lors de son rendu.
  44             </para>
  45         </listitem>
  46
  47         <listitem>
  48             <para>
  49                 Spécifier une chaîne utilisée pour <emphasis>séparer du contenu</emphasis> de la
  50                 collection lors de son rendu.
  51             </para>
  52         </listitem>
  53
  54         <listitem>
  55             <para>
  56                 <emphasis>Capturer du contenu</emphasis> dans la collection.
  57             </para>
  58         </listitem>
  59
  60         <listitem>
  61             <para>
  62                 <emphasis>Rendre</emphasis> le contenu agrégé.
  63             </para>
  64         </listitem>
  65     </itemizedlist>
  66
  67     <para>
  68         Typiquement, vous appelerez cette aide de vue sans argument, ce qui retournera le conteneur
  69         sur lequel opérer. Après vous afficherez (echo) ce contenu ou appelerez une méthode dessus
  70         pour le remplir ou le configurer. Si le conteneur est vide, son rendu sera une simple chaîne
  71         vide, sinon, le contenu sera aggrégé en fonction des règles que vous avez fixées.
  72     </para>
  73
  74     <para>
  75         Par exemple, créons une barre de menu qui contient des "blocs" de contenu. Supposons que la
  76         structure de chaque bloc ressemble à ceci&#160;:
  77     </para>
  78
  79     <programlisting language="html"><![CDATA[
  80 <div class="sidebar">
  81     <div class="block">
  82         <p>
  83             Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vivamus
  84             consectetur aliquet odio ac consectetur. Nulla quis eleifend
  85             tortor. Pellentesque varius, odio quis bibendum consequat, diam
  86             lectus porttitor quam, et aliquet mauris orci eu augue.
  87         </p>
  88     </div>
  89     <div class="block">
  90         <ul>
  91             <li><a href="/some/target">Link</a></li>
  92             <li><a href="/some/target">Link</a></li>
  93         </ul>
  94     </div>
  95 </div>
  96 ]]></programlisting>
  97
  98     <para>
  99         Le contenu variera en fonction du contrôleur et de l'action, mais la structure est
 100         identique, elle. Configurons en premier lieu la barre de menu dans une méthode du
 101         bootstrap&#160;:
 102     </para>
 103
 104     <programlisting language="php"><![CDATA[
 105 class Bootstrap extends Zend_Application_Bootstrap_Bootstrap
 106 {
 107     // ...
 108
 109     protected function _initSidebar()
 110     {
 111         $this->bootstrap('View');
 112         $view = $this->getResource('View');
 113
 114         $view->placeholder('sidebar')
 115              // "prefix" -> contenu à afficher une fois avant les données
 116              // dans la collection
 117              ->setPrefix("<div class=\"sidebar\">\n    <div class=\"block\">\n")
 118              // "separator" -> contenu à afficher entre chaque entité de
 119              // la collection
 120              ->setSeparator("</div>\n    <div class=\"block\">\n")
 121              // "postfix" -> contenu à afficher une fois après les données
 122              // dans la collection
 123              ->setPostfix("</div>\n</div>");
 124     }
 125
 126     // ...
 127 }
 128 ]]></programlisting>
 129
 130     <para>
 131         Le code ci-dessus définit un placeholder, "sidebar", qui n'a pas d'entité. Ce code
 132         configure la structure de base du placeholder, selon nos désirs.
 133     </para>
 134
 135     <para>
 136         Maintenant supposons que pour toutes les actions du contrôleur "user" nous voulons un
 137         bloc en haut qui contienne des informations. Nous pouvons faire cela de deux manières&#160;:
 138         (a) nous pourrions ajouter le contenu au placeholder directement dans la méthode
 139         <methodname>preDispatch()</methodname> du contrôleur, ou (b) nous pourrions rendre un
 140         script de vue depuis la méthode <methodname>preDispatch()</methodname>. Nous utiliserons le
 141         cas (b), car il propose une séparation propre des logiques en laissant la vue classique
 142         contenir ses données utiles.
 143     </para>
 144
 145     <para>
 146         Nous appelerons le script de vue "<filename>user/_sidebar.phtml</filename>", et nous le
 147         remplirons comme ceci&#160;:
 148     </para>
 149
 150     <programlisting language="php"><![CDATA[
 151 <?php $this->placeholder('sidebar')->captureStart() ?>
 152 <h4>User Administration</h4>
 153 <ul>
 154     <li><a href="<?php $this->url(array('action' => 'list')) ?>">
 155         List</a></li>
 156     <li><a href="<?php $this->url(array('action' => 'create')) ?>">
 157         Create</a></a></li>
 158 </ul>
 159 <?php $this->placeholder('sidebar')->captureEnd() ?>
 160 ]]></programlisting>
 161
 162     <para>
 163         L'exemple ci-dessus utilise les possibilités de capture dynamique de contenu des
 164         placeholders. Par défaut, le contenu est ajouté à la suite ce qui permet d'en agréger. Cet
 165         exemple utilise des aides de vues et du contenu <acronym>HTML</acronym> statique pour
 166         générer un menu qui est capturé et ajouté au placeholder.
 167     </para>
 168
 169     <para>
 170         Pour utiliser le script de vue, nous écrirons ceci dans la méthode
 171         <methodname>preDispatch()</methodname>&#160;:
 172     </para>
 173
 174     <programlisting language="php"><![CDATA[
 175 class UserController extends Zend_Controller_Action
 176 {
 177     // ...
 178
 179     public function preDispatch()
 180     {
 181         // ...
 182
 183         $this->view->render('user/_sidebar.phtml');
 184
 185         // ...
 186     }
 187
 188     // ...
 189 }
 190 ]]></programlisting>
 191
 192     <para>
 193         Notez que nous ne capturons pas le rendu, il n'y a pas besoin car le contenu complet de ce
 194         script de vue est déja capturé dans un placeholder.
 195     </para>
 196
 197     <para>
 198         Maintenant imaginons que l'action "view" dans ce même contrôleur ait besoin de présenter des
 199         informations. Dans "<filename>user/view.phtml</filename>" il pourrait y avoir ceci&#160;:
 200     </para>
 201
 202     <programlisting language="php"><![CDATA[
 203 $this->placeholder('sidebar')
 204      ->append('<p>User: ' . $this->escape($this->username) .  '</p>');
 205 ]]></programlisting>
 206
 207     <para>
 208         Cet exemple utilise la méthode <methodname>append()</methodname> et lui passe du contenu à
 209         agréger.
 210     </para>
 211
 212     <para>
 213         Enfin, modifions le script de layout pour rendre le placeholder&#160;:
 214     </para>
 215
 216     <programlisting language="php"><![CDATA[
 217 <html>
 218 <head>
 219     <title>My Site</title>
 220 </head>
 221 <body>
 222     <div class="content">
 223         <?php echo $this->layout()->content ?>
 224     </div>
 225     <?php echo $this->placeholder('sidebar') ?>
 226 </body>
 227 </html>
 228 ]]></programlisting>
 229
 230     <para>
 231         Pour les contrôleurs et les actions que ne remplissent pas le placeholder "sidebar", aucun
 232         contenu ne sera rendu&#160;; cependant afficher le placeholder rendra le contenu "fixe"
 233         suivant les règles définies dans le bootstrap ainsi que le contenu agrégé dans
 234         l'application. Dans le cas de l'action "<filename>/user/view</filename>", en supposant que
 235         le nom de l'utilisateur est "matthew", nous pouvons récupérer le contenu de la barre de menu
 236         comme ceci (formaté pour la lisibilité de l'exemple)&#160;:
 237     </para>
 238
 239     <programlisting language="html"><![CDATA[
 240 <div class="sidebar">
 241     <div class="block">
 242         <h4>User Administration</h4>
 243         <ul>
 244             <li><a href="/user/list">List</a></li>
 245             <li><a href="/user/create">Create</a></a></li>
 246         </ul>
 247     </div>
 248     <div class="block">
 249         <p>User: matthew</p>
 250     </div>
 251 </div>
 252 ]]></programlisting>
 253
 254     <para>
 255         Les possibilités sont immenses en ce qui concerne les placeholders et les layouts, essayez
 256         les et lisez les <link linkend="zend.view.helpers.initial.placeholder">sections relatives
 257         du manuel</link> pour plus d'informations.
 258     </para>
 259 </sect1>