documentation/manual/fr/module_specs/Zend_View-Helpers-Placeholder.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- EN-Revision: 19433 -->
   3 <!-- Reviewed: no -->
   4 <sect3 id="zend.view.helpers.initial.placeholder">
   5     <title>L'aide de vue Placeholder</title>
   6
   7     <note>
   8         <para>
   9             NDT. : Le terme "placeholder est conservé car sa signification varie en fonction
  10             du contexte : conteneur générique ou emplacement réservé.
  11         </para>
  12     </note>
  13
  14     <para>
  15         L'aide de vue <code>Placeholder</code> est utilisé pour faire persister le contenu
  16         entre les scripts de vues et les instances de vues. Il offre aussi des fonctionnalités
  17         utiles comme l'agrégation de contenu, la capture de contenu de scripts de vues pour une
  18         utilisation ultérieure, et l'ajout de texte pré ou post contenu (et la personnalisation des
  19         séparateurs de contenu).
  20     </para>
  21
  22     <example id="zend.view.helpers.initial.placeholder.usage">
  23         <title>Utilisation basique des Placeholders</title>
  24
  25         <para>
  26             L'utilisation basique des placeholders est la persistance des données de vue.
  27             Chaque appel de l'aide <code>Placeholder</code> attend un nom de placeholder ; l'aide
  28             retourne un objet conteneur que vous pouvez soit manipuler ou simplement envoyé à
  29             l'affichage.
  30         </para>
  31
  32         <programlisting language="php"><![CDATA[
  33 <?php $this->placeholder('foo')->set("Du texte pour plus tard") ?>
  34
  35 <?php
  36     echo $this->placeholder('foo');
  37     // outputs "Du texte pour plus tard"
  38 ?>
  39 ]]></programlisting>
  40     </example>
  41
  42     <example id="zend.view.helpers.initial.placeholder.aggregation">
  43         <title>Utilisation des Placeholders pour agréger du contenu</title>
  44
  45         <para>
  46             L'agrégation du contenu via les placeholders peut être aussi utile parfois. Par
  47             exemple, votre script de vue peut avoir une variable sous forme de tableau à partir de
  48             laquelle vous souhaitez récupérer des messages à afficher plus tard ; un autre script de
  49             vue peut ensuite déterminer de la manière suivant laquelle ils seront affichés.
  50         </para>
  51
  52         <para>
  53             L'aide de vue <code>Placeholder</code> utilise des conteneurs qui étendent
  54             <code>ArrayObject</code>, fournissant de riches fonctionnalités de manipulations des
  55             tableaux. De plus, il offre une variété de méthodes pour le formatage du contenu stockée
  56             dans le conteneur :
  57         </para>
  58
  59         <itemizedlist>
  60             <listitem>
  61                 <para>
  62                     <methodname>setPrefix($prefix)</methodname> paramètre le texte qui sera placé
  63                     préalablement à tout le contenu. Utilisez <methodname>getPrefix()</methodname> à tout moment
  64                     pour déterminer le réglage courant.
  65                 </para>
  66             </listitem>
  67
  68             <listitem>
  69                 <para>
  70                     <methodname>setPostfix($prefix)</methodname> paramètre le texte qui sera placé après
  71                     tout le contenu. Utilisez <methodname>getPostfix()</methodname> à tout moment pour
  72                     déterminer le réglage courant.
  73                 </para>
  74             </listitem>
  75
  76             <listitem>
  77                 <para>
  78                     <methodname>setSeparator($prefix)</methodname> paramètre le texte qui sera placé entre
  79                     chaque élément de contenu. Utilisez <methodname>getSeparator()</methodname> à tout moment
  80                     pour déterminer le réglage courant.
  81                 </para>
  82             </listitem>
  83
  84             <listitem>
  85                 <para>
  86                     <methodname>setIndent($prefix)</methodname> peut être utilisé pour paramétrer une
  87                     indentation pour chaque élément du contenu. Si un entier est fourni, il s'agira
  88                     du nombre d'espaces à utiliser ; si une chaîne est fournie, elle sera utilisée.
  89                     Utilisez <methodname>getIndent()</methodname> à tout moment pour déterminer le réglage
  90                     courant.
  91                 </para>
  92             </listitem>
  93         </itemizedlist>
  94
  95         <programlisting language="php"><![CDATA[
  96 <!-- premier script de vue -->
  97 <?php $this->placeholder('foo')->exchangeArray($this->data) ?>
  98 ]]></programlisting>
  99
 100         <programlisting language="php"><![CDATA[
 101 <!-- autre script (plus tard) -->
 102 <?php
 103 $this->placeholder('foo')->setPrefix("<ul>\n    <li>")
 104                          ->setSeparator("</li><li>\n")
 105                          ->setIndent(4)
 106                          ->setPostfix("</li></ul>\n");
 107 ?>
 108
 109 <?php
 110     echo $this->placeholder('foo');
 111     // affiche une liste non-ordonnée avec une belle indentation
 112 ?>
 113 ]]></programlisting>
 114
 115         <para>
 116             Puisque l'objet conteneur <code>Placeholder</code> étend <code>ArrayObject</code>,
 117             vous pouvez ainsi facilement assigner du contenu à une clé du conteneur en particulier,
 118             plutôt que de simplement de les envoyer les unes après les autres ("push"). Les clés
 119             peuvent être accédées soit en utilisant les propriétés d'objet ou comme les clés d'un
 120             tableau.
 121         </para>
 122
 123         <programlisting language="php"><![CDATA[
 124 <?php $this->placeholder('foo')->bar = $this->data ?>
 125 <?php echo $this->placeholder('foo')->bar ?>
 126
 127 <?php
 128 $foo = $this->placeholder('foo');
 129 echo $foo['bar'];
 130 ?>
 131 ]]></programlisting>
 132     </example>
 133
 134     <example id="zend.view.helpers.initial.placeholder.capture">
 135         <title>Utilisation des Placeholders pour capturer le contenu</title>
 136
 137         <para>
 138             Occasionnellement vous pouvez avoir du contenu pour un placeholder dans un script
 139             de vue qui est simple à mettre sous forme de modèle ("template") ; l'aide de vue
 140             <code>Placeholder</code> vous permet de capturer tout contenu arbitraire pour un rendu
 141             ultérieur en utilisant l'API suivante.
 142         </para>
 143
 144         <itemizedlist>
 145             <listitem>
 146                 <para>
 147                     <methodname>captureStart($type, $key)</methodname> commence la capture de
 148                     contenu.
 149                 </para>
 150
 151                 <para>
 152                     <varname>$type</varname> doit être une des constantes de
 153                     <code>Placeholder</code> : <constant>APPEND</constant> ou <constant>SET</constant>. Si c'est
 154                     <constant>APPEND</constant>, le contenu capturé est ajouté à la liste de contenu courant
 155                     dans le placeholder ; si c'est <constant>SET</constant>, le contenu capturé remplace
 156                     toute valeur existante dans le placeholder (potentiellement permet de remplacer
 157                     tout contenu préalable). Par défaut, <varname>$type</varname> vaut
 158                     <constant>APPEND</constant>.
 159                 </para>
 160
 161                 <para>
 162                     <varname>$key</varname> peut être utilisé pour spécifier une clé en particulier
 163                     dans le conteneur placeholder dans laquelle vous souhaitez capturer le
 164                     contenu.
 165                 </para>
 166
 167                 <para>
 168                     <methodname>captureStart()</methodname> verrouille la capture jusqu'à l'appel de
 169                     <methodname>captureEnd()</methodname> ; vous ne pouvez pas imbriquer des captures avec le
 170                     même conteneur placeholder. Le faire entraînera la levée d'une exception.
 171                 </para>
 172             </listitem>
 173
 174             <listitem>
 175                 <para>
 176                     <methodname>captureEnd()</methodname> stoppe la capture de contenu, et le place dans
 177                     l'objet conteneur suivant la manière utilisée pour appeler
 178                     <methodname>captureStart()</methodname>.
 179                 </para>
 180             </listitem>
 181         </itemizedlist>
 182
 183         <programlisting language="php"><![CDATA[
 184 <!-- Default capture: append -->
 185 <?php $this->placeholder('foo')->captureStart();
 186 foreach ($this->data as $datum): ?>
 187 <div class="foo">
 188     <h2><?php echo $datum->title ?></h2>
 189     <p><?php echo $datum->content ?></p>
 190 </div>
 191 <?php endforeach; ?>
 192 <?php $this->placeholder('foo')->captureEnd() ?>
 193
 194 <?php echo $this->placeholder('foo') ?>
 195 ]]></programlisting>
 196
 197         <programlisting language="php"><![CDATA[
 198 <!-- Capture to key -->
 199 <?php $this->placeholder('foo')->captureStart('SET', 'data');
 200 foreach ($this->data as $datum): ?>
 201 <div class="foo">
 202     <h2><?php echo $datum->title ?></h2>
 203     <p><?php echo $datum->content ?></p>
 204 </div>
 205  <?php endforeach; ?>
 206 <?php $this->placeholder('foo')->captureEnd() ?>
 207
 208 <?php echo $this->placeholder('foo')->data ?>
 209 ]]></programlisting>
 210     </example>
 211
 212     <sect4 id="zend.view.helpers.initial.placeholder.implementations">
 213         <title>Implémentation concrète des Placeholder</title>
 214
 215         <para>
 216             Zend Framework embarque certaines implémentations concrètes de placeholders.
 217             Celles-ci sont destinées à des placeholders communément utilisés : doctype, titre de
 218             page, et les différents éléments &lt;head&gt;. Dans tous les cas, appeler le placeholder
 219             sans arguments retournera l'élément lui-même.
 220         </para>
 221
 222         <para>
 223             La documentation pour chacun des éléments existe séparément, suivez les liens
 224             ci-dessous :
 225         </para>
 226
 227         <itemizedlist>
 228             <listitem>
 229                 <para><link linkend="zend.view.helpers.initial.doctype">Doctype</link></para>
 230             </listitem>
 231
 232             <listitem>
 233                 <para><link linkend="zend.view.helpers.initial.headlink">HeadLink</link></para>
 234             </listitem>
 235
 236             <listitem>
 237                 <para><link linkend="zend.view.helpers.initial.headmeta">HeadMeta</link></para>
 238             </listitem>
 239
 240             <listitem>
 241                 <para>
 242                     <link
 243                     linkend="zend.view.helpers.initial.headscript">HeadScript</link>
 244                 </para>
 245             </listitem>
 246
 247             <listitem>
 248                 <para>
 249                     <link
 250                     linkend="zend.view.helpers.initial.headstyle">HeadStyle</link>
 251                 </para>
 252             </listitem>
 253
 254             <listitem>
 255                 <para>
 256                     <link
 257                     linkend="zend.view.helpers.initial.headtitle">HeadTitle</link>
 258                 </para>
 259             </listitem>
 260
 261             <listitem>
 262                 <para>
 263                     <link
 264                     linkend="zend.view.helpers.initial.inlinescript">InlineScript</link>
 265                 </para>
 266             </listitem>
 267         </itemizedlist>
 268     </sect4>
 269 </sect3>