documentation/manual/fr/tutorials/plugins-usage.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- EN-Revision: 21825 -->
   3 <!-- Reviewed: no -->
   4 <sect1 id="learning.plugins.usage">
   5     <title>Utiliser des Plugins</title>
   6
   7     <para>
   8         Les composants utilisant des plugins se servent de
   9         <classname>Zend_Loader_PluginLoader</classname> pour fonctionner. Cette classe vous
  10         propose d'enregistrer des "chemins de préfixes". Le composant va alors utiliser la méthode
  11         <methodname>load()</methodname> du PluginLoader en lui passant le nom court du plugin
  12         à charger. Le PluginLoader va ensuite tester chaque chemin de préfixe pour trouver une
  13         classe qui corresponde au nom court passé. Les chemins de préfixes sont testés en ordre
  14         LIFO (last in, first out) et il trouvera d'abord les chemins de préfixes enregistrés
  15         en dernier, ce qui permet de surcharger des plugins existants.
  16     </para>
  17
  18     <para>
  19         Voici quelques exemples pour éclaircir tout ça.
  20     </para>
  21
  22     <example id="learning.plugins.usage.basic">
  23         <title>Exemple de base: ajouter un chemin de préfixes simple</title>
  24
  25         <para>
  26             Dans cet exemple, nous supposerons que des validateurs ont été écrits et enregistrés
  27             sous <filename>foo/plugins/validators/</filename>, puis que toutes ces classes
  28             partagent le même préfixe "Foo_Validate_"; ces deux informations forment le
  29             "chemin de préfixes". Imaginons maintenant deux validateurs, un s'appelle "Even" (impaire)
  30             il validera donc un chiffre impaire, et l'autre "Dozens"(multiples) qui vérifiera
  31             un chiffre multiple de 12. L'arbre ressemble à ceci:
  32         </para>
  33
  34         <programlisting language="text"><![CDATA[
  35 foo/
  36 |-- plugins/
  37 |   |-- validators/
  38 |   |   |-- Even.php
  39 |   |   |-- Dozens.php
  40 ]]></programlisting>
  41
  42         <para>
  43             Maintenant, nous allons informer un <classname>Zend_Form_Element</classname> de ce
  44             chemin de préfixes. La méthode <methodname>addPrefixPath()</methodname> de
  45             <classname>Zend_Form_Element</classname> prend comme troisième paramètre le type de
  46             plugin pour lequel on spécifie un chemin, dans notre cas il s'agit d'un plugin de
  47             validation , "validate".
  48         </para>
  49
  50         <programlisting language="php"><![CDATA[
  51 $element->addPrefixPath('Foo_Validate', 'foo/plugins/validators/', 'validate');
  52 ]]></programlisting>
  53
  54         <para>
  55             Dès lors il devient possible de passer à l'élément le nom court du validateur. Dans l'exemple
  56             qui suit, nous mixons des validateurs standards ("NotEmpty", "Int") et personnalisés
  57             ("Even", "Dozens"):
  58         </para>
  59
  60         <programlisting language="php"><![CDATA[
  61 $element->addValidator('NotEmpty')
  62         ->addValidator('Int')
  63         ->addValidator('Even')
  64         ->addValidator('Dozens');
  65 ]]></programlisting>
  66
  67         <para>
  68             Lorsque l'élément devra utiliser la validation, il appellera le plugin via le
  69             PluginLoader. Les deux premiers validateurs vont correspondre à
  70             <classname>Zend_Validate_NotEmpty</classname> et
  71             <classname>Zend_Validate_Int</classname>, puis les deux suivants à
  72             <classname>Foo_Validate_Even</classname> et <classname>Foo_Validate_Dozens</classname>,
  73             respectivement.
  74         </para>
  75     </example>
  76
  77     <note>
  78         <title>Que se passe-t-il si un plugin n'est pas trouvé?</title>
  79
  80         <para>
  81             Que se passe-t-il si un plugin est demandé mais que le PluginLoader ne peut pas trouver
  82             de classe qui y corresponde? Dans notre exemple ci-dessus, la question devient
  83             "que se passe-t-il si j'enregistre le validateur "Bar" dans l'élément?"
  84         </para>
  85
  86         <para>
  87             Le PluginLoader va chercher dans tous les chemins de prefixes pour trouver un fichier qui
  88             corresponde au nom du plugin. Si le fichier n'est pas trouvé, il passe au prochain
  89             chemin.
  90         </para>
  91
  92         <para>
  93             Une fois que la pile de chemins est épuisée, si aucun fichier n'a été trouvé, il enverra
  94             une <exceptionname>Zend_Loader_PluginLoader_Exception</exceptionname>.
  95         </para>
  96     </note>
  97
  98     <example id="learning.plugins.usage.override">
  99         <title>Exemple intermédiaire: Surcharger un plugin existant</title>
 100
 101         <para>
 102             Une des forces du PluginLoader est qu'il utilise une pile LIFO, ceci vous permet
 103             de surcharger des plugins existants par les votres stockés dans des chemins
 104             différents en enregistrant ce chemin dans la pile.
 105         </para>
 106
 107         <para>
 108             Par exemple, considérons <classname>Zend_View_Helper_FormButton</classname> (les aides
 109             de vue sont une forme de plugin). Cette aide de vue accepte trois paramètres, un nom
 110             DOM, une valeur (utilisée comme libéllé de bouton), et un tableau optionnel d'options.
 111             L'aide génère du HTML concernant un élément de formulaire.
 112         </para>
 113
 114         <para>
 115             Imaginons que vous vouliez que cette aide génère un vrai bouton HTML
 116             <constant>button</constant>; vous ne voulez pas que cette aide génère un identifiant DOM
 117             mais plutôt une classe CSS; et que vous ne souhaitez pas utiliser d'options
 118             supplémentaires. Vous pourriez faire cela de plusieurs manières. Dans tous les cas vous
 119             allez créer votre aide de vue en y écrivant le comportement mais comment allez-vous
 120             nommer votre aide de vue et comment l'instancier?
 121         </para>
 122
 123         <para>
 124             Nous allons d'abord nommer notre classe avec un nom unique non existant,
 125             <classname>Foo_View_Helper_CssButton</classname>, ceci donne immédiatement un nom de plugin:
 126             "CssButton". Pourquoi pas, mais ceci pose quelques problèmes: si vous utilisiez déja
 127             "FormButton" dans votre code vous allez devoir changer le nom partout, et si un autre
 128             développeur rejoind vos rangs, il pourrait être troublé par "CssButton" et intuitivement
 129             penser à l'aide standard "FormButton".
 130         </para>
 131
 132         <para>
 133             Le mieux reste encore de nommer notre aide de vue "Button", en lui donnant comme nom de classe
 134             <classname>Foo_View_Helper_Button</classname>. Nous enregistrons aussi le chemin de préfixes
 135             dans la vue:
 136         </para>
 137
 138         <programlisting language="php"><![CDATA[
 139 // Zend_View::addHelperPath() utilise PluginLoader; attention par contre
 140 // sa signature inverse les arguments par rapport à PluginLoader, ceci car il
 141 // propose une valeur par défaut au préfixe : "Zend_View_Helper"
 142 //
 143 // La ligne ci-dessous suppose que la classe soit logée dans 'foo/view/helpers/'.
 144 $view->addHelperPath('foo/view/helpers', 'Foo_View_Helper');
 145 ]]></programlisting>
 146
 147         <para>
 148             A partir de ce moment, utiliser l'aide "Button" mènera vers votre propre classe
 149             <classname>Foo_View_Helper_Button</classname>!
 150         </para>
 151     </example>
 152 </sect1>