2. Crochets de modèles

2. Crochets de modèles
Précédent	Chapitre 5. Personnalisation de Bugzilla	Suivant

	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 :

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.

Précédent	Niveau supérieur	Suivant
1. Personnalisation des modèles	Sommaire	3. Personnalisation : Qui peut faire quoi ?