Dans vos scripts de vue, il est souvent nécessaire d'effectuer certaines actions complexe encore et encore : par exemple, formatter une date, générer des éléments de formulaire, afficher des liens d'action. Vous pouvez utiliser des classes d'aide pour effectuer ce genre de tâches.
Une aide est simplement une classe. Par exemple, nous voulons une aide nommée "foobar". Par défaut, la classe est préfixée avec 'Zend_View_Helper_'
(vous pouvez spécifier un préfixe personnalisé en paramètrant votre chemin d'aide), et le dernier segment du nom de classe est le nom de l'aide ; ce segment peut être avec des CaractereMajuscule ; le nom complet de la classe est alors : Zend_View_Helper_FooBar
. Cette classe doit contenir au moins une méthode, nommée comme l'aide avec la notationCamel : fooBar()
.
Note | |
---|---|
Les noms des aides sont toujours en notationCamel, c'est-à-dire qu'ils ne commencent pas avec une caractère majuscules. |
Pour utiliser une aide dans votre script de vue, appelez la en utilisant $this->helperName()
. Dans les coulisses, Zend_View
va charger la classe Zend_View_Helper_HelperName
, créer une instance de cet objet, et appeler sa méthode helperName()
. L'instance de l'objet est persistante dans l'instance de Zend_View
, et est réutilisée pour tous les appels futurs à $this->helperName()
.
Zend_View
fournit avec un jeu initial de classes d'aides, la plupart sont liées à la génération d'éléments de formulaire. Chacune affiche et échappe l'élement automatiquement. De plus, il existe des aides pour créer des URLS sur la base de routes et des listes HTML, de la même manière que l'on déclarerait des variables. Les aides actuellement inclus sont :
declareVars()
: initialement préu pour être utilisé avec strictVars()
, cette aide peut être utilisée pour déclarer les variables de modèle ("template") qui sont (ou pas) déjà déclarées dans l'objet de vue, ou pour gérer des valeurs par défaut. Les tableaux passés comme arguments à la méthode seront utilisés pour paramètrer des valeurs par défaut ; sinon, si la variable n'existe pas, on lui affecte une chaîne vide.
formButton($name, $value, $attribs)
: crée un élément <input type="button" />.
formCheckbox($name, $value, $attribs, $options)
: crée un élément <input type="checkbox" />. Le paramètre $options est un tableau dans lequel la première valeur est la valeur "checked", et la seconde "unchecked" (les défauts sont '1' et '0'). Si $value correspond à la valeur "checked", la boite sera cochée.
formFile($name, $value, $attribs)
: crée un élément <input type="file" />.
formHidden($name, $value, $attribs)
: crée un élément <input type="hidden" />.
formLabel($name, $value, $attribs)
: crée un élément <label>, en réglant l'attribut for
avec $name
, et le texte du label avec $value
. Si disable
est fourni via attribs
, rien n'est retourné.
formPassword($name, $value, $attribs)
: crée un élément <input type="password" />.
formRadio($name, $value, $attribs, $options)
: crée une série d'éléments <input type="button" />, une pour chaque élément $options. Dans le tableau $options, la clé de l'élément est la valeur du radio, et la valeur de l'élément est l'étiquette du radio. La radio $value sera précoché pour vous.
formReset($name, $value, $attribs)
: crée un élément <input type="reset" />.
formSelect($name, $value, $attribs, $options)
: crée un bloc <select>...</select>, avec une <option> pour chaque élément $options. Dans le tableau $options, la clé de l'élément est la valeur de l'option, et la valeur de l'élément est son étiquette optionnelle. L'option (ou les options) $value sera (ou seront) présélectionnées pour vous.
formSubmit($name, $value, $attribs)
: crée un élément <input type="submit" />.
formText($name, $value, $attribs)
: crée un élément <input type="text" />.
formTextarea($name, $value, $attribs)
: crée un bloc <textarea>...</textarea>.
url($urlOptions, $name, $reset)
: crée un URL basé sur une route nommée. $urlOptions
doit être un tableau associatif avec des paires de clés/valeurs utilisées par une route particulière.
htmlList($items, $ordered, $attribs)
: génère des listes ordonnées ou non basées sur les $items
qui lui sont fournis. Si $items
est un tableau multidimensionnel, une liste imbriquée sera construite.
Les utiliser dans vos script de vue est très simple, voici un exemple. Notez que tout ce dont vous avez besoin, c'est de les appeler; elles vont se charger et s'instantier elle-même si besoin est.
<?php // dans votre script de vue, $this se réfère à l'instance de Zend_View. // // Partons du principe que vous avez déjà assigné une série d'options de sélection dans un // tableau $countries = array('us' => 'United States', 'il' => 'Israel', 'de' => 'Germany'). ?> <form action="action.php" method="post"> <p><label>Votre email : <?php echo $this->formText('email', 'you@example.com', array('size' => 32)) ?> </label></p> <p><label>Votre pays : <?php echo $this->formSelect('country', 'us', null, $this->countries) ?> </label></p> <p><label>??? Would you like to opt in ??? <?php echo $this->formCheckbox('opt_in', 'yes', null, array('yes', 'no')) ?> </label></p> </form>
La sortie résultante du script de vue ressemblera à ceci:
<form action="action.php" method="post"> <p><label>Votre email : <input type="text" name="email" value="you@example.com" size="32" /> </label></p> <p><label>Votre pays : <select name="country"> <option value="us" selected="selected">United States</option> <option value="il">Israel</option> <option value="de">Germany</option> </select> </label></p> <p><label>??? Would you like to opt in ??? <input type="hidden" name="opt_in" value="no" /> <input type="checkbox" name="opt_in" value="yes" checked="checked" /> </label></p> </form>
Comme pour les scripts de vue, votre contrôleur peut spécifier une pile de chemins dans lesquels Zend_View
cherchera les classes d'aides. Par défaut, Zend_View
cherche dans "Zend/View/Helper/*". Vous pouvez dire à Zend_View
de regarder dans d'autres chemins en utilisant les méthodes setHelperPath()
et addHelperPath()
. De plus, vous pouvez indiquer un préfixe de classe pour utiliser les aides dans le répertoire fourni, et permettre de donner des espaces de nommage à vos classes d'aide. Par défaut, si aucun préfixe n'est fourni, 'Zend_View_Helper_' est utilisé.
<?php $view = new Zend_View(); $view->setHelperPath('/chemin/vers/plus/de/classes/d-aides', 'Ma_View_Helper'); ?>
En fait, vous pouvez "empiler" les chemins en utilisant la méthode addHelperPath()
Comme vous ajouter des chemins dans la pile, Zend_View
va regarder dans le chemin le plus
récemment ajouté, pour inclure la classe d'aide. Cela vous permet d'ajouter (ou bien de re-définir) la
distribution initiale des aides, avec vos propes aides personnalisées.
<?php $view = new Zend_View(); // Ajoute /chemin/vers/des/aides avec le préfixe de classe 'Ma_View_Helper' $view->addHelperPath('/chemin/vers/des/aides', 'Ma_View_Helper'); // Ajoute /autre/chemin/vers/des/aides avec le préfixe de classe 'Votre_View_Helper' $view->addHelperPath('/autre/chemin/vers/des/aides', 'Votre_View_Helper'); // maintenant, lorsque vous appelerez $this->helperName(), Zend_View // va rechercher en premier /chemin/vers/des/aides/HelperName.php en utilisant la classe "Ma_View_Helper_HelperName", // et ensuite dans /autre/chemin/vers/des/aides/HelperName.php en utilisant la classe "Votre_View_Helper_HelperName", // et finalement dans Zend/View/Helpers/HelperName.php en utilisant la classe "Zend_View_Helper_HelperName" ?>
Ecrire des aides personnalisées est facile, vous devez juste suivre ces règle :
Le nom de la classe doit, au minimum, se terminer avec le nom de l'aide en utilisant la notation Camel. Par exemple, si vous écrivez une aide appelée "actionSpeciale", le nom de la classe doit être au minimum "ActionSpeciale". Vous devriez donner au nom de la classe un préfixe, et il est recommandé d'utiliser "View_Helper" comme partie de ce préfixe : "Ma_View_Helper_ActionSpeciale". (Vous devez alors fournir le préfixe, avec ou sans l'underscore, à addHelperPath()
ou à setHelperPath()
).
La classe doit avoir une méthode publique dont le nom correspond au nom de l'aide ; c'est la méthode qui sera appelé quand votre template appelera "$this->actionSpeciale()". Dans notre exemple "$this->actionSpeciale()", la déclaration de méthode requise serait "public function actionSpeciale()".
En général, la classe ne devrait pas afficher directement les données (via echo ou print). Elle devrait retourner les valeurs pour être ensuite affichées. Les valeurs retournées devrait être échappées de façon appropriées.
La classe doit être dans un fichier ayant le même nom que la méthode d'aide. Si on utilise la méthode "actionSpeciale()", le fichier devra être nommé "ActionSpeciale.php"
Placez les fichier de classe d'aide quelque part dans la pile des chemins d'aide, et Zend_View
le chargera, l'instantiera, le rendra persistant, et l'exécutera automatiquement pour vous.
Voici un exemple du fichier "ActionSpeciale.php" :
<?php class Ma_View_Helper_ActionSpeciale { protected $_count = 0; public function actionSpeciale() { $this->_count++; $output = "J'ai vu 'The Big Lebowsky' {$this->_count} fois."; return htmlspecialchars($output); } } ?>
Ensuite, dans un script de vue, vous pouvez appeler l'aide ActionSpeciale
autant de fois que vous le souhaitez ; elle sera instantiée une fois, et rendue persistante pendant toute la vie de l'instance de Zend_View
.
<?php // rappelez vous, $this se réfère à l'instance de Zend_View echo $this->actionSpeciale(); echo $this->actionSpeciale(); echo $this->actionSpeciale(); ?>
La sortie pourrait alors ressembler à ceci :
J'ai vu 'The Big Lebowsky' 1 fois. J'ai vu 'The Big Lebowsky' 2 fois. J'ai vu 'The Big Lebowsky' 3 fois.
Quelquefois vous devez accéder à l'objet Zend_View
appelant - par exemple, si vous devez utiliser l'encodage enregistré ou voulez rendre l'affichage d'un autre script de vue comme une sous partie de votre aide. Pour avoir accès à votre objet de vue, votre classe d'aide doit avoir une méthode setView($view)
, comme ceci :
<?php class My_View_Helper_ScriptPath { public $view; public function setView(Zend_View_Interface $view) { $this->view = $view; } public function scriptPath($script) { return $this->view->getScriptPath($script); } } ?>
Si votre classe d'aide a une méthode setView()
, elle sera appelée quand votre classe sera instanciée la première fois et fournira l'objet de la vue courante. Il est de votre responsabilité de maintenir la persistance de l'objet dans votre classe, de même que de déterminer la fçon dont il peut être accéder.