2. Crochets de modèles

[Avertissement]Avertissement

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("nom") %], où 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. S'il n'y a pas de crochets à l'endroit approprié dans le modèle Bugzilla que vous souhaitez étendre, rapportez un bug pour en demander un, en précisant :

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 :