documentation/manual/fr/tutorials/form-decorators-individual.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- EN-Revision: 21997 -->
   3 <!-- Reviewed: no -->
   4 <sect1 id="learning.form.decorators.individual">
   5     <title>Rendu individuel des décorateurs</title>
   6
   7     <para>
   8         Dans la <link linkend="learning.form.decorators.layering">section précédente</link>, nous
   9         avons vu comment combiner les décorateurs afin de créer un rendu complexe. Ceci est très fléxible
  10         mais rajoute tout de même un part de compléxité à l'ensemble. Dans ce chapitre, nous allons
  11         inspecter le rendu individuel des décorateurs afin de créer du contenu visuel pour des
  12         formulaires ou des éléments.
  13     </para>
  14
  15     <para>
  16         Une fois des décorateurs enregistrés, vous pouvez les récupérer via leur nom depuis l'élément.
  17         Revoyons l'exemple précédent:
  18     </para>
  19
  20     <programlisting language="php"><![CDATA[
  21 $element = new Zend_Form_Element('foo', array(
  22     'label'      => 'Foo',
  23     'belongsTo'  => 'bar',
  24     'value'      => 'test',
  25     'prefixPath' => array('decorator' => array(
  26         'My_Decorator' => 'path/to/decorators/',
  27     )),
  28     'decorators' => array(
  29         'SimpleInput'
  30         array('SimpleLabel', array('placement' => 'append')),
  31     ),
  32 ));
  33 ]]></programlisting>
  34
  35     <para>
  36         Si nous voulons récupérer le décorateur <classname>SimpleInput</classname>, nous passons
  37         par la méthode <methodname>getDecorator()</methodname>:
  38     </para>
  39
  40     <programlisting language="php"><![CDATA[
  41 $decorator = $element->getDecorator('SimpleInput');
  42 echo $decorator->render('');
  43 ]]></programlisting>
  44
  45     <para>
  46         C'est simple et ça peut l'être encore plus; ré-écrivons le tout sur une seule ligne:
  47     </para>
  48
  49     <programlisting language="php"><![CDATA[
  50 echo $element->getDecorator('SimpleInput')->render('');
  51 ]]></programlisting>
  52
  53     <para>
  54         Pas mauvais, mais toujours un peu compliqué. Pour simplifier, une notation raccourcie a été
  55         introduite dans <classname>Zend_Form</classname> en 1.7: vous pouvez rendre n'importe quel
  56         décorateur enregistré en appelant une méthode de la forme
  57         <methodname>renderDecoratorName()</methodname>.
  58         Ceci effectue le rendu et fait en sorte que <varname>$content</varname> soit optionnel ce qui
  59         simplifie l'utilisation:
  60     </para>
  61
  62     <programlisting language="php"><![CDATA[
  63 echo $element->renderSimpleInput();
  64 ]]></programlisting>
  65
  66     <para>
  67         C'est une simplification astucieuse, mais comment et pourquoi l'utiliser?
  68     </para>
  69
  70     <para>
  71         Beaucoup de développeurs ont des besoins très précis en affichage des formulaires. Ils préfèrent
  72         avoir un contrôle complet sur tout l'affichage plutôt que d'utiliser une solution automatisée
  73         qui peut s'écarter de leur but initial. Dans d'autres cas, les formulaires peuvent demander
  74         un affichage extrêmement spécifique, en groupant des éléments alors que d'autres doivent
  75         pouvoir être invisibles avant que l'on n'effectue telle action sur la page, etc.
  76     </para>
  77
  78     <para>
  79         Utilisons la possibilité de rendre un seul décorateur pour créer un affichage précis.
  80     </para>
  81
  82     <para>
  83         D'abord, définissons un formulaire. Celui-ci récupèrera des détails démographiques sur l'utilisateur.
  84         Le rendu sera hautement personnalisé et dans certains cas il utilisera les aides de vue directement
  85         plutôt que les éléments. Voici une définition simple du formulaire:
  86     </para>
  87
  88     <programlisting language="php"><![CDATA[
  89 class My_Form_UserDemographics extends Zend_Form
  90 {
  91     public function init()
  92     {
  93         // Ajoute un chemin pour les décorateurs personnalisés
  94         $this->addElementPrefixPaths(array(
  95             'decorator' => array('My_Decorator' => 'My/Decorator'),
  96         ));
  97
  98         $this->addElement('text', 'firstName', array(
  99             'label' => 'First name: ',
 100         ));
 101         $this->addElement('text', 'lastName', array(
 102             'label' => 'Last name: ',
 103         ));
 104         $this->addElement('text', 'title', array(
 105             'label' => 'Title: ',
 106         ));
 107         $this->addElement('text', 'dateOfBirth', array(
 108             'label' => 'Date of Birth (DD/MM/YYYY): ',
 109         ));
 110         $this->addElement('text', 'email', array(
 111             'label' => 'Your email address: ',
 112         ));
 113         $this->addElement('password', 'password', array(
 114             'label' => 'Password: ',
 115         ));
 116         $this->addElement('password', 'passwordConfirmation', array(
 117             'label' => 'Confirm Password: ',
 118         ));
 119     }
 120 }
 121 ]]></programlisting>
 122
 123     <note>
 124         <para>
 125             Nous n'utilisons pas de validateurs ou de filtres ici, car ils n'ont rien à voir avec le
 126             rendu visuel qui nous interesse. En réalité, il y en aurait.
 127         </para>
 128     </note>
 129
 130     <para>
 131         Maintenant réfléchissons au rendu visuel du formulaire. Une communalité concernant les nom
 132         et prénom est qu'on les affiche l'un à coté de l'autre, à coté de leur titre, si présent.
 133         Les dates, si elles n'utilisent pas Javascript, affichent souvent des champs séparés pour
 134         chaque segment de la date.
 135     </para>
 136
 137     <para>
 138         Utilisons la possibilité de rendre des décorateurs un par un pour accomplir notre tâche.
 139         D'abord, notez qu'aucun décorateur spécifique n'a été renseigné dans les éléments.
 140         Rappelons donc les décorateurs par défaut de la plupart des éléments:
 141     </para>
 142
 143     <itemizedlist>
 144         <listitem>
 145             <para>
 146                 <classname>ViewHelper</classname>: utilise une aide de vue pour rendre l'élément
 147                 balise de formulaire à proprement parlé.
 148             </para>
 149         </listitem>
 150
 151         <listitem>
 152             <para>
 153                 <classname>Errors</classname>: utilise l'aide de vue <classname>FormErrors</classname>
 154                 pour afficher les erreurs de validation éventuelles.
 155             </para>
 156         </listitem>
 157
 158         <listitem>
 159             <para>
 160                 <classname>Description</classname>: utilise l'aide de vue <classname>FormNote</classname>
 161                 afin de rendre la description éventuelle de l'élément.
 162             </para>
 163         </listitem>
 164
 165         <listitem>
 166             <para>
 167                 <classname>HtmlTag</classname>: encapsule les trois objets ci-dessus dans un tag
 168                 <emphasis>&lt;dd&gt;</emphasis>.
 169             </para>
 170         </listitem>
 171
 172         <listitem>
 173             <para>
 174                 <classname>Label</classname>: rend l'intitulé de l'élément en utilisant l'aide de vue
 175                 <classname>FormLabel</classname> (et en encapsulant le tout dans un tag
 176                 <emphasis>&lt;dt&gt;</emphasis>).
 177             </para>
 178         </listitem>
 179     </itemizedlist>
 180
 181     <para>
 182         Nous vous rappelons aussi que vous pouvez accéder à tout élément individuellement en tant
 183         qu'attribut du formulaire représentant son nom.
 184     </para>
 185
 186     <para>
 187         Notre script de vue ressemblerait à cela:
 188     </para>
 189
 190     <programlisting language="php"><![CDATA[
 191 <?php
 192 $form = $this->form;
 193 // Enlève le <dt> depuis l'intitulé
 194 foreach ($form->getElements() as $element) {
 195     $element->getDecorator('label')->setOption('tag', null);
 196 }
 197 ?>
 198 <form method="<?php echo $form->getMethod() ?>" action="<?php echo
 199     $form->getAction()?>">
 200     <div class="element">
 201         <?php echo $form->title->renderLabel()
 202               . $form->title->renderViewHelper() ?>
 203         <?php echo $form->firstName->renderLabel()
 204               . $form->firstName->renderViewHelper() ?>
 205         <?php echo $form->lastName->renderLabel()
 206               . $form->lastName->renderViewHelper() ?>
 207     </div>
 208     <div class="element">
 209         <?php echo $form->dateOfBirth->renderLabel() ?>
 210         <?php echo $this->formText('dateOfBirth[day]', '', array(
 211             'size' => 2, 'maxlength' => 2)) ?>
 212         /
 213         <?php echo $this->formText('dateOfBirth[month]', '', array(
 214             'size' => 2, 'maxlength' => 2)) ?>
 215         /
 216         <?php echo $this->formText('dateOfBirth[year]', '', array(
 217             'size' => 4, 'maxlength' => 4)) ?>
 218     </div>
 219     <div class="element">
 220         <?php echo $form->password->renderLabel()
 221               . $form->password->renderViewHelper() ?>
 222     </div>
 223     <div class="element">
 224         <?php echo $form->passwordConfirmation->renderLabel()
 225               . $form->passwordConfirmation->renderViewHelper() ?>
 226     </div>
 227     <?php echo $this->formSubmit('submit', 'Save') ?>
 228 </form>
 229 ]]></programlisting>
 230
 231     <para>
 232         Si vous utilisez le script ci-dessus, vous verrez un code HTML ressemblant à ceci:
 233     </para>
 234
 235     <programlisting language="html"><![CDATA[
 236 <form method="post" action="">
 237     <div class="element">
 238         <label for="title" tag="" class="optional">Title:</label>
 239         <input type="text" name="title" id="title" value=""/>
 240
 241         <label for="firstName" tag="" class="optional">First name:</label>
 242         <input type="text" name="firstName" id="firstName" value=""/>
 243
 244         <label for="lastName" tag="" class="optional">Last name:</label>
 245         <input type="text" name="lastName" id="lastName" value=""/>
 246     </div>
 247
 248     <div class="element">
 249         <label for="dateOfBirth" tag="" class="optional">Date of Birth
 250             (DD/MM/YYYY):</label>
 251         <input type="text" name="dateOfBirth[day]" id="dateOfBirth-day"
 252             value="" size="2" maxlength="2"/>
 253         /
 254         <input type="text" name="dateOfBirth[month]" id="dateOfBirth-month"
 255             value="" size="2" maxlength="2"/>
 256         /
 257         <input type="text" name="dateOfBirth[year]" id="dateOfBirth-year"
 258             value="" size="4" maxlength="4"/>
 259     </div>
 260
 261     <div class="element">
 262         <label for="password" tag="" class="optional">Password:</label>
 263         <input type="password" name="password" id="password" value=""/>
 264     </div>
 265
 266     <div class="element">
 267         <label for="passwordConfirmation" tag="" class="" id="submit"
 268             value="Save"/>
 269 </form>
 270 ]]></programlisting>
 271
 272     <para>
 273         Ca peut ne pas ressembler à quelque chose de terminé, mais avec un peu de CSS, cela peut
 274         ressembler exactement à ce que vous cherchez. Le point important ici, c'est que le formulaire
 275         a été généré en utilisant de la décoration manuelle personnalisée (ainsi que l'utilisation
 276         d'échappement avec htmlentities).
 277     </para>
 278
 279     <para>
 280         Grâce à cette partie du tutoriel, vous devriez être à l'aise avec les possibilité de rendu de
 281         <classname>Zend_Form</classname>. Dans la section suivante, nous verrons comment monter un
 282         élément de date grâce à des éléments et des décorateur uniques assemblés main.
 283     </para>
 284 </sect1>