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

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- EN-Revision: 22189 -->
   3 <!-- Reviewed: no -->
   4 <sect1 id="learning.view.placeholders.standard">
   5     <title>Placeholders standards</title>
   6
   7     <para>
   8         Dans la <link linkend="learning.view.placeholders.basics">section précédente</link>, nous
   9         avons vu l'aide de vue <methodname>placeholder()</methodname> et comment l'utiliser pour
  10         aggréger du contenu personnalisable. Dans ce chapitre, nous allons passer en revue quelques
  11         placeholders concrets fournis avec Zend Framework, ainsi que la manière de les utiliser à
  12         votre avantage pour créer des layouts complexes.
  13     </para>
  14
  15     <para>
  16         La plupart des placeholders fournis permettent de gérer le contenur de la section
  17         <emphasis>&lt;head&gt;</emphasis> de la layout -- une zone qui ne peut typiquement pas être
  18         manipulée directement par vos scripts de vue, mais que vous voulez tout de même traiter.
  19         Par exemples: vous voudriez que votre titre se compose d'un certain contenu sur toutes les
  20         pages mais aussi d'une partie dynamique relative au contrôleur/action en cours; aussi vous
  21         voudriez préciser des fichiers <acronym>CSS</acronym> à charger basés sur la section de
  22         l'application en cours; enfin vous pourriez avoir recours à des scripts JavaScript spécifiques
  23         parfois, ou encore changer la déclaration de <acronym>DocType</acronym>.
  24     </para>
  25
  26     <para>
  27         Zend Framework est livré avec des implémentations de placeholder pour chacune de ces situations
  28         et encore d'autres.
  29     </para>
  30
  31     <sect2 id="learning.view.placeholders.standard.doctype">
  32         <title>Changer le DocType</title>
  33
  34         <para>
  35             Les déclarations de <acronym>DocType</acronym> sont difficiles à mémoriser et souvent
  36             essentielles pour s'assurer que le navigateur rende correctement le contenu. L'aide de vue
  37             <methodname>doctype()</methodname> permet d'utiliser des mnemonics pour spécifier un
  38             <acronym>DocType</acronym>; aussi, d'autres aides de vues interrogeront l'aide
  39             <methodname>doctype()</methodname> pour s'assurer que le contenu qu'elles génèrent est
  40             conforme au <acronym>DocType</acronym> utilisé.
  41         </para>
  42
  43         <para>
  44             Par exemple si vous souhaitez utiliser la <acronym>DTD</acronym>
  45             <acronym>XHTML1</acronym> Strict, vous pouvez simplement la préciser
  46             comme ceci:
  47         </para>
  48
  49         <programlisting language="php"><![CDATA[
  50 $this->doctype('XHTML1_STRICT');
  51 ]]></programlisting>
  52
  53         <para>
  54             Voici les autres mnemonics utilisables:
  55         </para>
  56
  57         <variablelist>
  58             <varlistentry>
  59                 <term>XHTML1_STRICT</term>
  60
  61                 <listitem>
  62                     <para>
  63                         <acronym>XHTML</acronym> 1.0 Strict
  64                     </para>
  65                 </listitem>
  66             </varlistentry>
  67
  68             <varlistentry>
  69                 <term>XHTML1_TRANSITIONAL</term>
  70
  71                 <listitem>
  72                     <para>
  73                         <acronym>XHTML</acronym> 1.0 Transitional
  74                     </para>
  75                 </listitem>
  76             </varlistentry>
  77
  78             <varlistentry>
  79                 <term>HTML4_STRICT</term>
  80
  81                 <listitem>
  82                     <para>
  83                         <acronym>HTML</acronym> 4.01 Strict
  84                     </para>
  85                 </listitem>
  86             </varlistentry>
  87
  88             <varlistentry>
  89                 <term>HTML4_Loose</term>
  90
  91                 <listitem>
  92                     <para>
  93                         <acronym>HTML</acronym> 4.01 Loose
  94                     </para>
  95                 </listitem>
  96             </varlistentry>
  97
  98             <varlistentry>
  99                 <term>HTML5</term>
 100
 101                 <listitem>
 102                     <para>
 103                         <acronym>HTML</acronym> 5
 104                     </para>
 105                 </listitem>
 106             </varlistentry>
 107         </variablelist>
 108
 109         <para>
 110             Vous pouvez changer le type et rendre la déclaration en un seul appel:
 111         </para>
 112
 113         <programlisting language="php"><![CDATA[
 114 echo $this->doctype('XHTML1_STRICT');
 115 ]]></programlisting>
 116
 117         <para>
 118             Cependant l'approche conseillée est de préciser le type dans le bootstrap et rendre l'aide
 119             de vue dans la layout. Essayez d'ajouter ceci à votre classe de bootstrap:
 120         </para>
 121
 122         <programlisting language="php"><![CDATA[
 123 class Bootstrap extends Zend_Application_Bootstrap_Bootstrap
 124 {
 125     protected function _initDocType()
 126     {
 127         $this->bootstrap('View');
 128         $view = $this->getResource('View');
 129         $view->doctype('XHTML1_STRICT');
 130     }
 131 }
 132 ]]></programlisting>
 133
 134         <para>
 135             Puis, dans le script de layout, affichez simplement avec <function>echo</function> l'aide en
 136             haut du fichier:
 137         </para>
 138
 139         <programlisting language="php"><![CDATA[
 140 <?php echo $this->doctype() ?>
 141 <html>
 142     <!-- ... -->
 143 ]]></programlisting>
 144
 145         <para>
 146             Ceci permet d'être sûr que les aides de vue diverses utiliseront cette déclaration,
 147             que le docType est précisé avant le rendu du layout et qu'il n'existe qu'un seul endroit
 148             logique pour le changer.
 149         </para>
 150     </sect2>
 151
 152     <sect2 id="learning.view.placeholders.standard.head-title">
 153         <title>Spécifier le titre de la page</title>
 154
 155         <para>
 156             Souvent, le site incluera le nom de la société dans le titre de la page et ajoutera
 157             ensuite des informations basées sur la page en cours de lecture. Par exemple, le site
 158             zend.com inclut la chaine "Zend.com" sur toutes les pages et y fait précèder des
 159             informations relatives à la page en cours: "Zend Server - Zend.com". Dans Zend Framework,
 160             l'aide de vue <methodname>headTitle()</methodname> peut vous simplifier cette tâche.
 161         </para>
 162
 163         <para>
 164             Au plus simple, l'aide <methodname>headTitle()</methodname> permet d'aggréger du contenu
 165             pour la balise <emphasis>&lt;title&gt;</emphasis>; lorsque vous l'affichez, il assemble
 166             son contenu dans l'ordre des ajouts. Pour contrôler l'ordre, les méthodes
 167             <methodname>prepend()</methodname> et <methodname>append()</methodname> sont là, pour changer
 168             le séparateur à utiliser entre les segments, utilisez la méthode
 169             <methodname>setSeparator()</methodname>.
 170         </para>
 171
 172         <para>
 173             Typiquement vous devriez renseigner tous les segments communs à toutes les pages en bootstrap,
 174             de la même manière que nous avions agit avec le doctype. Dans ce cas, nous allons écrire une
 175             méthode <methodname>_initPlaceholders()</methodname> pour gérer tous les placeholders et préciser
 176             un titre initial ainsi qu'un séparateur.
 177         </para>
 178
 179         <programlisting language="php"><![CDATA[
 180 class Bootstrap extends Zend_Application_Bootstrap_Bootstrap
 181 {
 182     // ...
 183
 184     protected function _initPlaceholders()
 185     {
 186         $this->bootstrap('View');
 187         $view = $this->getResource('View');
 188         $view->doctype('XHTML1_STRICT');
 189
 190         // Précise le titre initial et le séparateur:
 191         $view->headTitle('My Site')
 192              ->setSeparator(' :: ');
 193     }
 194
 195     // ...
 196 }
 197 ]]></programlisting>
 198
 199         <para>
 200             Dans un script de vue, nous voulons ajouter un nouveau segment:
 201         </para>
 202
 203         <programlisting language="php"><![CDATA[
 204 <?php $this->headTitle()->append('Some Page'); // placé après les autres segments ?>
 205 <?php $this->headTitle()->prepend('Some Page'); // placé avant ?>
 206 ]]></programlisting>
 207
 208         <para>
 209             Dans notre layout, nous affichons simplement l'aide <methodname>headTitle()</methodname>:
 210         </para>
 211
 212         <programlisting language="php"><![CDATA[
 213 <?php echo $this->doctype() ?>
 214 <html>
 215     <?php echo $this->headTitle() ?>
 216     <!-- ... -->
 217 ]]></programlisting>
 218
 219         <para>
 220             Le contenu suivant aura été généré:
 221         </para>
 222
 223         <programlisting language="html"><![CDATA[
 224 <!-- Si append() a été utilisé: -->
 225 <title>My Site :: Some Page</title>
 226
 227 <!-- Si prepend() a été utilisé: -->
 228 <title>Some Page :: My Site</title>
 229 ]]></programlisting>
 230     </sect2>
 231
 232     <sect2 id="learning.view.placeholders.standard.head-link">
 233         <title>Spécifier des feuilles de style avec HeadLink</title>
 234
 235         <para>
 236             Les bons développeurs <acronym>CSS</acronym> créront souvent une feuille de style
 237             globale et des feuilles individuelles pour les sections spécifiques ou certaines pages
 238             du site puis chargeront celles-ci plus tard conditionnellement afin de réduire
 239             le nombre de données à transférer entre chaque requête. Le placeholder
 240             <methodname>headLink()</methodname> permet de réaliser de telles aggrégations
 241             conditionnelles de feuilles de style.
 242         </para>
 243
 244         <para>
 245             Pour cela, <methodname>headLink()</methodname> definit une certain nombre de méthodes
 246             "virtuelles" (via surcharge) pour simplifier le tout. Celles qui vont nous concernet
 247             sont <methodname>appendStylesheet()</methodname> et
 248             <methodname>prependStylesheet()</methodname>. Chacune peut accepter jusqu'à quatre
 249             arguments, <varname>$href</varname> (chemin relatif vers la feuille de style),
 250             <varname>$media</varname> (le type <acronym>MIME</acronym>, par défaut "text/css"),
 251             <varname>$conditionalStylesheet</varname> (à utiliser pour préciser une "condition"
 252             à évaluer pour la feuille de style), et <varname>$extras</varname> (un tableau
 253             associatif utiliser générallement pour renseigner une clé pour "media"). Dans la
 254             plupart des cas, seul le premier argument suffira, le chemin relatif vers la feuille
 255             de style.
 256         </para>
 257
 258         <para>
 259             Dans notre exemple, nous supposerons que toutes les pages ont besoin de charger une feuille
 260             de style stockée dans "<filename>/styles/site.css</filename>" (relativement au document root);
 261             nous allons préciser cela dans notre méthode de bootstrap
 262             <methodname>_initPlaceholders()</methodname>.
 263         </para>
 264
 265         <programlisting language="php"><![CDATA[
 266 class Bootstrap extends Zend_Application_Bootstrap_Bootstrap
 267 {
 268     // ...
 269
 270     protected function _initPlaceholders()
 271     {
 272         $this->bootstrap('View');
 273         $view = $this->getResource('View');
 274         $view->doctype('XHTML1_STRICT');
 275
 276         // Affecte le titre original et le séparateur:
 277         $view->headTitle('My Site')
 278              ->setSeparator(' :: ');
 279
 280         // Affecte la feuille de style originale:
 281         $view->headLink()->prependStylesheet('/styles/site.css');
 282     }
 283
 284     // ...
 285 }
 286 ]]></programlisting>
 287
 288         <para>
 289             Plus tard, dans un contrôleur par exemple, nous pouvons rajouter des feuilles de
 290             style:
 291         </para>
 292
 293         <programlisting language="php"><![CDATA[
 294 <?php $this->headLink()->appendStylesheet('/styles/user-list.css') ?>
 295 ]]></programlisting>
 296
 297         <para>
 298             Dans notre layout, là encore, un simple echo sur le placeholer:
 299         </para>
 300
 301         <programlisting language="php"><![CDATA[
 302 <?php echo $this->doctype() ?>
 303 <html>
 304     <?php echo $this->headTitle() ?>
 305     <?php echo $this->headLink() ?>
 306     <!-- ... -->
 307 ]]></programlisting>
 308
 309         <para>
 310             Ceci génèrera quelque chose comme:
 311         </para>
 312
 313         <programlisting language="html"><![CDATA[
 314 <link rel="stylesheet" type="text/css" href="/styles/site.css" />
 315 <link rel="stylesheet" type="text/css" href="/styles/user-list.css" />
 316 ]]></programlisting>
 317     </sect2>
 318
 319     <sect2 id="learning.view.placeholders.standard.head-script">
 320         <title>Aggréger des scripts avec HeadScript</title>
 321
 322         <para>
 323             Un autre moyen de ne pas surcharger la page est de ne charger le JavaScript que lorsque
 324             c'est nécessaire. Vous aurez donc besoin de scripts découpés: peut-être un pour afficher
 325             le menu du site progressivement, un autre pour traiter le contenu d'une page spécifique.
 326             Dans ces cas, l'aide <methodname>headScript()</methodname> propose une solution.
 327         </para>
 328
 329         <para>
 330             Comme l'aide <methodname>headLink()</methodname>, <methodname>headScript()</methodname>
 331             permet d'empiler en début ou fin des scripts entiers et de les afficher d'un coup. Cela
 332             est très flexible pour spécifier des fichiers de scripts entiers à charger, ou encore
 333             du code JavaScript explicite. Vous pouvez aussi capturer le JavaScript via
 334             <methodname>captureStart()</methodname>/<methodname>captureEnd()</methodname>, qui
 335             permettent d'utiliser du code JavaScript inline plutot que de demander un appel serveur
 336             pour charger un fichier.
 337         </para>
 338
 339         <para>
 340             Tout comme <methodname>headLink()</methodname>, <methodname>headScript()</methodname>
 341             propose des mééthodes "virtuelles" via surcharge pour spécifier rapidement des contenus
 342             à aggréger; les méthodes sont <methodname>prependFile()</methodname>,
 343             <methodname>appendFile()</methodname>, <methodname>prependScript()</methodname>, et
 344             <methodname>appendScript()</methodname>. Les deux premières vous permettent de préciser
 345             des fichiers référéncés dans l'attribut <varname>$src</varname> d'une balise
 346             <emphasis>&lt;script&gt;</emphasis>; les deux dernières vont prendre le contenu qu'on leur
 347             passe et le rendre comme du JavaScript dans les balises <emphasis>&lt;script&gt;</emphasis>.
 348         </para>
 349
 350         <para>
 351             Dans cet exemple, nous allons spécifier qu'un script, "<filename>/js/site.js</filename>" a
 352             besoin d'être chargé sur chaque page; nous allons donc mettre à jour notre méthode de
 353             bootstap <methodname>_initPlaceholders()</methodname> pour effectuer cela.
 354         </para>
 355
 356         <programlisting language="php"><![CDATA[
 357 class Bootstrap extends Zend_Application_Bootstrap_Bootstrap
 358 {
 359     // ...
 360
 361     protected function _initPlaceholders()
 362     {
 363         $this->bootstrap('View');
 364         $view = $this->getResource('View');
 365         $view->doctype('XHTML1_STRICT');
 366
 367         // Titre et séparateur d'origine:
 368         $view->headTitle('My Site')
 369              ->setSeparator(' :: ');
 370
 371         // Feuille de style originale:
 372         $view->headLink()->prependStylesheet('/styles/site.css');
 373
 374         // Affecte le JS initial à charger:
 375         $view->headScript()->prependFile('/js/site.js');
 376     }
 377
 378     // ...
 379 }
 380 ]]></programlisting>
 381
 382         <para>
 383             Dans un script de vue, nous voulons ajouter un script ou capturer du contenu JavaScript
 384             à inclure dans le document.
 385         </para>
 386
 387         <programlisting language="php"><![CDATA[
 388 <?php $this->headScript()->appendFile('/js/user-list.js') ?>
 389 <?php $this->headScript()->captureStart() ?>
 390 site = {
 391     baseUrl: "<?php echo $this->baseUrl() ?>"
 392 };
 393 <?php $this->headScript()->captureEnd() ?>
 394 ]]></programlisting>
 395
 396         <para>
 397             Dans notre script de layout, nous affichons simplement le placeholder, tout comme nous avions
 398             fait pour les autres précédemment:
 399         </para>
 400
 401         <programlisting language="php"><![CDATA[
 402 <?php echo $this->doctype() ?>
 403 <html>
 404     <?php echo $this->headTitle() ?>
 405     <?php echo $this->headLink() ?>
 406     <?php echo $this->headScript() ?>
 407     <!-- ... -->
 408 ]]></programlisting>
 409
 410         <para>
 411             Le contenu suivant sera généré:
 412         </para>
 413
 414         <programlisting language="html"><![CDATA[
 415 <script type="text/javascript" src="/js/site.js"></script>
 416 <script type="text/javascript" src="/js/user-list.js"></script>
 417 <script type="text/javascript">
 418 site = {
 419     baseUrl: "<?php echo $this->baseUrl() ?>"
 420 };
 421 </script>
 422 ]]></programlisting>
 423
 424         <note>
 425             <title>Variante InlineScript</title>
 426
 427             <para>
 428                 La plupart des navigateur bloquent l'affichage tant que tous les scritps et les feuilles
 429                 de style référencés dans la section <emphasis>&lt;head&gt;</emphasis> ne sont pas chargés.
 430                 Ces règles permettent un meilleur feeling au niveau du rendu de la page et permettent
 431                 à l'utilisateur de voir le contenu de la page plus tôt.
 432             </para>
 433
 434             <para>
 435                 Pour cela, vous pouvez par exemple écrire vos tags <emphasis>&lt;script&gt;</emphasis>
 436                 après avoir fermé <emphasis>&lt;body&gt;</emphasis>. (C'est une pratique recommandée
 437                 par <ulink url="http://developer.yahoo.com/yslow/">Y! Slow project</ulink>.)
 438             </para>
 439
 440             <para>
 441                 Zend Framework supporte cela de deux manières différentes:
 442             </para>
 443
 444             <itemizedlist>
 445                 <listitem>
 446                     <para>
 447                         Vous pouvez rendre <methodname>headScript()</methodname> où vous voulez dans votre
 448                         layout; ce n'est pas parce que la méthode commence par "head" que vous devez
 449                         l'appeler pour cette section du HTML.
 450                     </para>
 451                 </listitem>
 452
 453                 <listitem>
 454                     <para>
 455                         Aussi, vous pourriez utiliser l'aide de vue <methodname>inlineScript()</methodname>,
 456                         qui est simplement une variante de <methodname>headScript()</methodname> avec le même
 457                         comportement mais un registre séparé.
 458                     </para>
 459                 </listitem>
 460             </itemizedlist>
 461         </note>
 462     </sect2>
 463 </sect1>