Les crochets Template ont besoin du Template Toolkit version 2.12 ou plus, ou l'application d'un correctif. Voir le bogue 239112 pour plus d'informations.
Les crochets Template permettent aux extensions de Bugzilla d'insérer du code dans les modèles Bugzilla standard sans modifier les fichiers du modèle eux-mêmes. Le mécanisme de crochets définit une API cohérente pour étendre les modèles standards de manière à séparer proprement le code standard du code d'extension. Les crochets réduisent les conflits de fusion et facilitent l'écriture d'extensions qui fonctionnent pour de multiples versions de Bugzilla, ce qui facilite la mise à jour d'une installation Bugzilla avec des extensions installées.
Un crochet de modèle est juste un emplacement nommé dans un fichier de modèle standard où les fichiers du modèle d'extension pour ce crochet sont traités. Chaque crochet a un répertoire correspondant dans l'arborescence de Bugzilla. Accrocher un modèle d'extension à un crochet est aussi simple que de mettre le fichier d'extension dans le répertoire du crochet. Les crochets eux-mêmes peuvent être ajoutés dans un modèle standard sur demande des auteurs de l'extension.
Pour utiliser des crochets afin d'étendre un modèle Bugzilla, assurez vous d'abord qu'il y a
un crochet à l'emplacement approprié dans le modèle que vous voulez étendre.
Les crochets apparaissent dans les modèles standard Bugzilla en tant que simple directive
dans le format
[% Hook.process(",
où nom") %]nom est (dans ce modèle) l'unique
nom du crochet.
Si vous n'êtes pas sûr quel modèle vous voulez étendre ou que vous voulez juste
passer en revue les crochets disponibles, vous pouvez soit utiliser votre outil de recherche multi-fichiers
préféré (i.é. grep) pour chercher parmi les modèles standards
les occurrences de Hook.process, soit passer en revue
l'arborescence Bugzilla dans
BUGZILLA_ROOT/template/en/extension/hook/,
qui contient un répertoire pour chaque crochets à l'emplacement suivant :
BUGZILLA_ROOT/template/en/extension/hook/CHEMIN_VERS_MODÈLE_STANDARD/NOM_MODÈLE_STANDARD/NOM_CROCHET/
S'il n y a pas de crochets à l'emplacement approprié dans le modèle Bugzilla que vous voulez étendre, faites un rapport de bogue pour en demander un, en spécifiant : un lien vers les informations à propos de votre extension, s'il y en a. If there is no hook at the appropriate place within the Bugzilla template you want to extend, file a bug requesting one, specifying:
| le modèle pour lequel vous demandez un crochet |
| où vous aimeriez que le crochet soit placé dans le modèle (numéro de ligne/position pour la dernière version de modèle dans le CVS ou description du but du crochet) ; |
| le but de ce crochet ; |
| un lien vers les informations à propos de votre extension, s'il y en a. |
Les responsables de l'examen des bogues de Bugzilla examineront sans délai chaque demande de crochet,
nommeront le crochet et l'ajouteront au modèle, vérifieront les nouvelles versions
du modèle dans le CVS, et créeront le répertoire correspondant dans
BUGZILLA_ROOT/template/en/extension/hook/.
Vous pouvez en option joindre un correctif au bogue qui implémente le crochet et l'enregistrer vous-même après avoir reçu l'accord d'un vérificateur Bugzilla. Les développeurs peuvent suggérer des modifications de l'emplacement d'un crochet en se basant sur l'analyse de vos besoins ou pour que le crochet puisse satisfaire les besoins d'extensions multiples mais la procédure permettant d'approuver et d'enregistrer les crochets n'est pas aussi rigoureuse que la procédure pour les modifications générales de Bugzilla, et toute extension, qu'elle soit sortie ou toujours en développement, peut avoir des crochets ajoutés pour répondre à leurs besoins.
Après vous être assuré que le crochet dont vous avez besoin existe (ou après l'avoir récupéré si ce n'est pas le cas), ajoutez votre modèle d'extension au répertoire de l'arborescence correspondant au crochet.
Oui, c'est tout ! Maintenant, quand le modèle standard contenant le crochet sera traité, votre modèle d'extension sera traité à l'endroit où le crochet apparaît.
Par exemple, disons que vous avez une extension nommée Projman qui ajoute
les possibilités de gestion de projet à Bugzilla. Projman a une
interface d'administration edit-projects.cgi
et vous voulez ajouter un lien vers elle dans la barre de navigation en bas
de toutes les pages Bugzilla pour ceux parmi les utilisateurs qui sont autorisés
à administrer les projets.
La barre de navigation est générée par le fichier
useful-links.html.tmpl du modèle, qui est placé dans
le sous-répertoire global/ sur le chemin
BUGZILLA_ROOT/template/en/default/ d'un
modèle Bugzilla standard.
Si vous regardez dans useful-links.html.tmpl, vous trouverez
le crochet suivant à la fin de la liste des liens d'administration
Bugzilla standard :
...
[% ', <a href="editkeywords.cgi">keywords</a>'
IF user.groups.editkeywords %]
[% Hook.process("edit") %]
...
Le répertoire correspondant pour ce crochet est
BUGZILLA_ROOT/template/en/extension/hook/global/useful-links.html.tmpl/edit/.
Vous mettez un modèle nommé
projman-edit-projects.html.tmpl
dans ce répertoire avec le contenu suivant :
...[% ', <a href="edit-projects.cgi">projects</a>' IF user.groups.projman_admins %]
Voilà ! Le lien apparaît maintenant après les autres liens d'administration dans la
barre de navigation pour les utilisateurs du groupe projman_admins.
Astuces :
Vous aurez peut être envie de préfixer vos noms de modèle d'extension
avec le nom de votre extension, par exemple
projman-foo.html.tmpl
pour qu'ils n'entrent pas en conflit avec les noms des modèles installés par
d'autres extensions.
Si votre extension englobent complètement de nouveaux modèles en plus des
extensions des modèles standards, il faut qu'elle installe ces nouveaux
modèles dans un sous-répertoire du répertoire
BUGZILLA_ROOT/template/en/extension/
spécifique aux extensions. Le répertoire extension/, tout comme les
répertoires default/ and custom/,
fait partie du chemin de recherche de modèle, et donc en mettant des modèles
à cet endroit là, le processeur de modèles pourra les trouver.
Le processeur de modèles cherche les modèles d'abord dans le
répertoire custom/ (modèles ajoutés par une
installation spécifique), puis dans le répertoire extension/
(modèles ajoutés par des extensions), et finalement dans le
répertoire default/ (les modèles Bugzilla
standard). Donc les modèles d'extension peuvent prendre le pas sur des modèles standard
mais les modèles à installation particulière prennent le pas sur tous les deux.
Notez que l'annulation de modèles standard vous donne un grand pouvoir mais rend également la mise à jour d'une installation plus difficile. Comme avec un modèle personnalisé, nous vous recommandons d'utiliser cette fonctionnalité avec parcimonie et seulement quand c’est absolument nécessaire.
Les personnalisateurs d'installation peuvent aussi profiter des crochets quand ils ajoutent
du code à un modèle Bugzilla. Pour ce faire, créez des répertoires dans
BUGZILLA_ROOT/template/en/custom/hook/
équivalents aux répertoires dans
BUGZILLA_ROOT/template/en/extension/hook/
pour les crochets que vous voulez utiliser puis placez vos modèles de personnalisation
dans ces répertoires.
Evidemment cette méthode de personnalisation de Bugzilla vous laisse seulement ajouter du code à vos modèles standard ; vous ne pouvez pas modifier le code existant. Cependant, pour ces personnalisations qui ne font qu'ajouter du code, cette méthode peut réduire les conflits quand la fusion est modifiée, rendant la mise à jour de votre installation Bugzilla personnalisée plus facile.