La structure des répertoires des modèles démarre au répertoire racine nommé template, qui contient un répertoire pour chaque langue installée. Le niveau suivant définit la langue utilisée dans les modèles. Bugzilla est livré avec les modèles en anglais, donc le répertoire s'appelle en, et nous discuterons du répertoire template/en tout au long de la documentation. Dans le répertoire template/en se trouve le répertoire default qui contient tous les modèles standards livrés avec Bugzilla.

	Un répertoire data/templates existe aussi ; c'est l'endroit où « Template Toolkit » met les versions compilées des modèles du répertoire par défaut ou des répertoires personnalisés. Ne modifiez pas ces fichiers de ce répertoire directement, ou tous vos changements seront perdus la prochaine fois que « Template Toolkit » recompilera les modèles.

Si vous voulez modifier les modèles de Bugzilla, La première décision que vous devrez prendre est la façon dont vous voulez procéder. Il y a deux choix qui dépendent pricipalement de la portée de vos modifications et de la méthode que vous prévoyez d'utiliser pour mettre à jour Bugzilla.

La première méthode de personnalisation est de modifier directement les modèles situés dans template/en/default. Ceci est probablement la meilleure méthode si vous projetez de mettre à jour Bugzilla par Bzr, car si vous exécutez une commande bzr update, tous les changements que vous avez faits seront automatiquement fusionnés avec les versions mises à jour.

	Si vous utilisez cette méthode et que des conflits Bzr surviennent pendant la mise à jour, les modèles en conflit (et peut-être d'autres parties de votre installation) ne fonctionneront pas jusqu'à ce que les conflits soient résolus.

La seconde méthode est de copier les modèles à modifier dans structure de répertoire miroir dans template/en/custom. Les modèles dans cette structure de répertoires écrasent automatiquement ceux dont le nom et l'emplacement sont identiques dans le répertoire default.

	Le répertoire custom n'existe pas, vous devez le créer si vous voulez l'utiliser.

La deuxième méthode doit être utilisée si vous utilisez la méthode de mise à jour qui remplace les fichiers, sinon vos changements seront perdus. Cette méthode peut être meilleure si vous utilisez la mise à jour par Bzr et que vous allez faire des changements majeurs, car il est garanti que le contenu de ce répertoire ne sera pas modifié pendant une mise à jour et vous pouvez décider alors si vous continuez à utiliser vos propres modèles ou si vous faites l'effort de fussionner vos changements dans les nouvelles versions manuellement.

En utilisant cette méthode, votre installation peut ne plus fonctionner si des changements incompatibles sont faits à l'interface des modèles. De tels changements devraient être documentés dans les notes de version, pourvu que vous utilisiez une version stable de Bugzilla. Si vous utilisez une version instable, vous devrez vous débrouillez avec celle-ci vous-même, bien que, si possible, les changements seront mentionnés avant qu'ils n'arrivent dans les notes de version de la version stable précédente.

	Quelle que soit la méthode utilisée, il est recommandé d'exécuter le script ./checksetup.pl après la modification de modèles dans le répertoire template/en/default, et après avoir créé ou modifié des modèles dans le répertoire custom.

	Il est nécessaire d'exécuter ./checksetup.pl après la création d'un nouveau modèle dans le répertoire custom. Ne pas le faire produira un message d'erreur incompréhensible.

	Si vous réalisez des changements de modèle que vous comptez renvoyer pour les inclure dans le Bugzilla standard, vous devriez lire les sections appropriées dans le guide des développeurs.

La syntaxe du langage « Template Toolkit » n'est pas couverte par ce guide. Il est relativement facile de comprendre en regardant les modèles actuels ; ou vous pouvez lire le manuel, disponible sur la page d'accueil de Template Toolkit.

Une chose à laquelle vous devez prêter une attention particulière est le besoin de de filtrer correctement les données HTML qui sont passées par un modèle. Ceci signifie que si les données peuvent contenir des caractère spéciaux HTML comme « < », et que les données ne sont pas destinéees à être de l'HTML, elles doivent alors être converties sous forme d'entités, par ex. « < ». Vous utilisez le filtre « html » dans Template Toolkit pour faire cela (ou le filtre 'uri' pour encoder les caractères spéciaux dans les URLs). Si vous oubliez, vous pourriez ouvrir votre installation à des attaques de scripts de sites croisés.

Modifier les modèles est un bon moyen pour personnaliser les champs sans trop d'efforts. Par exemple, si vous n'utilisez pas le « Tableau blanc », mais que vous voulez avoir un champ de saisie de texte libre pour « Identifiant de compilation », alors vous pouvez simplement modifier les modèles pour changer les libellés du champ. Il sera toujours appelé « status_whiteboard » en interne, mais vos utilisateurs n'ont pas besoin de le savoir.

Certains scripts CGI ont la capacité d'utiliser plus d'un modèle. Par exemple, buglist.cgi peut faire des sorties sous forme RDF ou sous deux formats HTML (complexe et simple). Le mécanisme qui produit cette fonctionnalité est extensible.

Bugzilla peut gérer différents types de sortie, qui peuvent encore avoir de multiples formats. Pour demander un certain type, vous pouvez ajouter « &ctype=<contenttype> » (comme rdf ou html) à l'URL <cginame>.cgi. Si vous voulez récupérer un certain format, vous pouvez utiliser « &format=<format> » (comme simple ou complexe) dans l'URL.

Pour voir si un script CGI gère de multiples types et formats de sortie, faites un grep du fichier CGI pour rechercher « get_format ». S'il n'est pas présent, ajouter la gestion de multiples formats ou types n'est pas trop dur - regardez comment c'est mis en œuvre dans d'autres scripts CGI, comme par exemple config.cgi.

Pour faire un nouveau modèle de format pour un script CGI qui le gère, ouvrez un modèle actuellement utilisé pour ce script CGI et regardez le commentaire « INTERFACE » (s'il existe). Ce commentaire définit quelles variables sont passées dans ce modèle. S'il n'y en a pas, il vous faudra alors lire le modèle et le code pour découvrir les informations que vous obtenez.

Écrivez votre modèle avec le langage de balises ou le style de texte approprié.

Vous devez maintenant décider le type de contenu que vous voulez que votre modèle serve. Les types de contenu sont définis dans le fichier Bugzilla/Constants.pm dans la constante contenttypes. Si votre type de contenu n'y est pas, ajoutez-le. Souvenez-vous du marqueur de trois ou quatre lettres affecté à votre type de contenu. Ce marqueur fera partie du nom de fichier de votre modèle.

	Après avoir ajouter ou modifier le type de contenu, il faut modifier le fichier Bugzilla/Constants.pm afin de refléter les changements. Et aussi, le fichier doit être maintenu à jour après une mise à jour de Bugzilla si les types de contenus ont été personnalisés auparavant.

Enregistrez le modèle sous le nom <stubname>-<formatname>.<contenttypetag>.tmpl. Essayez le modèles en invoquant le script ainsi : <cginame>.cgi?format=<formatname>&ctype=<type> .

Il existe quelques modèles qui pourraient particulièrement vous intéresser pour personnaliser votre installation.

index.html.tmpl : C'est la page d'accueil de Bugzilla

global/header.html.tmpl : Ceci définit l'en-tête qui sera sur toutes les pages de Bugzilla. L'en-tête inclut la bannière, qui s'affiche pour tous les utilisateurs et que vous voudrez certainement modifier. Cependant, l'en-tête contient aussi la section « HTML HEAD », et vous pourriez par exemple y ajouter une feuille de style ou une balise « META » en modifiant l'en-tête.

global/banner.html.tmpl : Ceci contient la « bannière », la partie de l'en-tête qui apparaît en haut de toutes les pages de Bugzilla. La bannière par défaut est relativement austère et vous voudrez certainement la personnaliser pour donner à votre installation distincte. il est recommandé de conserver le numéro de version de Bugzilla que vous utilisez de sorte que les utilisateurs sachent quelle documentation consulter.

global/footer.html.tmpl : Ceci définit lepied de page de toutes les pages de Bugzilla. Modifier ceci est un autre moyen pour obtenir rapidement une apparence distincte pour votre installation de Bugzilla.

global/variables.none.tmpl : Ceci définit la liste des termes qui peuvent être modifiés afin de mettre « à vos couleurs » l'instance Bugzilla. De cette façon, des termes comme « bogues » peuvent être remplacés par « défaut » dans toute l'installation de Bugzilla. Le nom « Bugzilla » et d'autres mots peuvent être personnalisés de la même manière.

list/table.html.tmpl : Ce modèle contrôle l'apparence des listes de bogues créées par Bugzilla. Modifier ce modèle permet un contrôle par colonne de la largeur et du titre de la colonne, la longueur maximum d'affichage de chaque entrée et le comportement d'affichage des longues entrées. Pour les longues liste de bogues, Bugzilla insère une « coupure » tous les 100 bogues par défautt ; ce comportement est aussi contrôlé par ce modèle et cette valeur peut être modifiée ici.

bug/create/user-message.html.tmpl : C'est le message qui apparaît près du haut de la page de rapport de bogue. En modifiant ceci, vous pouvez dire aux utilisateurs comment rapporter les bogues.

bug/process/midair.html.tmpl : C'est la page utilisée i deux utilisateurs soumettent simultanément des changements pour le même bogue. La seconde personne à soumettre les changements obtiendra cette page pour lui indiquer les changements que la première personne a fait, et lui demander si elle souhaite écraser ces changements ou revenir sur la page du bogue. Le titre par défaut et l'en-tête de cette page indiquent « Collision détectée ! ». Si vous travaillez dans l'industrie aéronautique ou d'autres environnements ou ceci pourrait être perçu comme choquant (oui, nous avons des histoires vraies à ce sujet) vous voudrez changer ceci pour quelque chose de plus approprié pour votre environnement.

bug/create/create.html.tmpl et bug/create/comment.txt.tmpl : Vous ne souhaitez peut-être pas faire l'effort de créer des champs personnalisés dans Bugzilla, cependant, vous voulez être sûr que chaque rapport de bogue contienne un certain nombre d'éléments d'information importants pour lesquels il n'y a pas un champ spécial. Le système de saisie de bogue a été conçu de façon extensible pour vous permettre d'ajouter des widgets HTML, tels que des listes déroulantes ou des boîtes de texte, sur la page de saisie de bogue, et leurs valeurs apparaissent formatées dans le commentaire initial. Un champ caché indiquant le format peut être ajouté dans le formulaire afin de rendre le modèle fonctionnel. Sa valeur doit être le suffixe du nom de fichier du modèle. Par exemple, si le fichier s'appelle create-cust.html.tmpl, alors

<input type="hidden" name="format" value="cust">

doit être utilisé dans le formulaire.

Un exemple de ceci est le formulaire de soumission de bogue assisté. Le code pour ceci est livré dans la distribution de Bugzilla comme exemple à copier. On peut le trouver dans les fichiers create-guided.html.tmpl et comment-guided.html.tmpl.

Pour utiliser cette focntionnalité, créez un modèle personnalisé pour enter_bug.cgi. Le modèle par défaut sur lequel vous pouvez vous baser est custom/bug/create/create.html.tmpl. Nommez-le create-<formatname>.html.tmpl, et dedans, ajouter les widgets pour chaque élément d'information que vous aimeriez collecter - comme l'identifiant de compilation ou un ensemble d'étapes à reproduire.

Puis, créez un modèle comme custom/bug/create/comment.txt.tmpl, et appelez-le comment-<formatname>.txt.tmpl. Ce modèle doit référencer les champs de formulaire que vous avez créés en utilisant la syntaxe [% form.<fieldname> %]. Quand un rapport de bogue sera soumis, le commentaire initial du rapport de bogue sera formaté selon ce qui est indiqué dans ce modèle.

Par exemple, si votre modèle personnalisé « enter_bug » avait un champ

<input type="text" name="buildid" size="30">

et que votre fichier « comment.txt.tmpl » avait

BuildID : [% form.buildid %]

, alors quelque chose comme

BuildID : 20020303

devrait apparaître dans le commentaire initial.

Bugzilla respecte l'en-tête utilisateur « Accept: HTTP ». Vous pouvez installer des modèles dans d'autres langues et Bugzilla choisira la plus appropriée selon un ordre de priorité que vous avez établi. Beaucoup de modèle de langues peuvent être obtenus sur http://www.bugzilla.org/download.html#localizations. Les instructions pour soumettre de nouvelles langues sont également disponibles à cet emplacement.