La structure de répertoires des modèles est composée d'un répertoire de haut niveau nommé template, qui contient un répertoire pour chaque région installée. Le niveau suivant définit la langue utilisée dans les modèles. Bugzilla est livré avec des modèles en anglais, le nom du répertoire est donc en, et nous parlerons de template/en dans toute la documentation. En dessous de ça, template/en est un répertoire default qui contient tous les modèles standard fournis avec Bugzilla.

	Avertissement
	Un répertoire data/templates existe aussi ; c'est là où Template Toolkit met les versions compilées à partir des répertoires par défaut ou personnalisés. N'éditez pas directement les fichiers dans ce répertoire, ou alors toutes vos modifications seront perdues la prochaine fois que Template Toolkit recompilera les modèles.

Si vous voulez éditer des modèles Bugzilla, la première choix à faire est de décider comment vous allez vous y prendre. Il y a deux possibilités et celle que vous utiliserez dépend principalement de la portée de vos modifications, et de la méthode que vous prévoyez d'utiliser pour mettre à niveau Bugzilla.

La première méthode pour personnaliser les modèles consiste à éditer directement ceux qui sont dans template/en/default. C'est probablement la meilleure méthode pour de petites modifications si vous comptez utiliser la méthode de mise à niveau par CVS, parce qu'alors, si vous exécutez un cvs update, toute correction dans un modèle s'intègrera automagiquement dans les versions que vous aurez mises à jour.

	Note
	Si vous utilisez cette méthode, et si des conflits CVS surviennent pendant une mise à jour, les modèles en conflit (et éventuellement d'autres parties de votre installation) ne fonctionneront pas tant qu'ils ne seront pas résolus.

L'autre méthode consiste à copier les modèles à modifier dans une arborescence de répertoires miroir sous template/en/custom. Les modèles de cette arborescence de répertoire prennent le pas sur tous les modèles de même nom et situés au même endroit dans le répertoire default.

	Note
	Le répertoire custom n'existe pas initialement et doit être créé si vous voulez l'utiliser.

C'est la technique que vous devez utiliser si vous utilisez la méthode de mise à niveau par réécriture, parce qu'autrement vos modifications seront perdues. Cette méthode est peut-être également la meilleure si vous utilisez la méthode de mise à niveau par CVS et que vous comptez faire des modifications majeures, car il est garanti que le contenu de ce répertoire ne sera pas touché au cours d'une mise à niveau, et vous pouvez alors décider soit de continuer en utilisant votre propre modèle, soit de faire l'effort d'intégrer à la main vos modifications dans les nouvelles versions.

Avec cette méthode, votre installation peut être perdue en cas de modifications incompatibles faites à l'interface des modèles. Si de telles modifications sont faites, elles seront détaillées dans la notice de la version, à condition que vous utilisiez une version stable de Bugzilla. Si vous utilisez du code instable, vous devrez vous occuper de ça vous-même, bien que, autant que possible, les modifications seront citées, avant qu'elles ne s'appliquent, dans la partie « À éviter » de la notice de la précédente version stable.

	Note
	Quelle que soit la méthode que vous avez choisie, il est recommandé d'exécuter ./checksetup.pl après la création ou l'édition de tout modèle dans le répertoire template/en/default, et après l'édition de tout modèle dans le répertoire custom.

	Avertissement
	Il est indispensable d'exécuter ./checksetup.pl après la création d'un nouveau modèle, dans le répertoire custom. Si vous ne le faites pas, cela entraînera un message d'erreur incompréhensible.

	Note
	Si vous apportez des modifications aux modèles que vous souhaitez voir inclus dans le Bugzilla standard, il faut lire les parties correspondantes du guide des développeurs.

La syntaxe du langage de Template Toolkit dépasse le cadre de ce guide. Elle est assez facile à comprendre en regardant les modèles actuels ; vous pouvez également lire le manuel, disponible sur la page d'accueil de Template Toolkit.

Cependant, une chose à laquelle vous devriez apporter un soin particulier est la nécessité de filtrer correctement, par rapport au langage HTML, les données qui ont été transmises dans le modèle. Cela signifie que si les données sont susceptibles de contenir des caractères HTML spéciaux comme <, et que les données ne sont pas sensées être du HTML, elles doivent être converties sous la forme d'entité, c'est-à-dire &lt; on utilise le filtre « html » de Template Toolkit pour faire cela. Si vous ne le faîtes pas, vous pouvez exposer votre installation à des attaques par scripts à l'intérieur du site.

Notez également que Bugzilla inclut de lui-même quelques filtres, qui ne sont pas dans le Template Toolkit standard. En particulier, le filtre « url_quote » peut convertir les caractères qui sont illégaux ou qui ont un sens particulier dans les URL, comme &, en une forme encodée, c'est-à-dire %26. En fait, celui-ci encode la plupart des caractères (mais pas les plus fréquents comme les lettres et les nombres et cætera), y compris les caractères HTML spéciaux, de sorte que, par la suite, vous n'avez jamais besoin de filtrer par rapport au langage HTML.

Editer des modèles est une bonne façon de faire les « champs personnalisés du pauvre ». Par exemple, si vous n'utilisez pas le Tableau Blanc mais que vous souhaitez disposer d'une boîte d'entrée de texte de forme libre pour le « Identifiant de Création », vous pouvez vous contenter d'éditer les modèles pour changer le nom des champs. Ca s'appellera toujours status_whiteboard en interne, mais vos utilisateurs n'ont pas besoin de le savoir.

Certains CGI sont capables d'utiliser plus d'un modèle. Par exemple, buglist.cgi peut générer des listes de bogues en RDF ou en 2 formes différentes de HTML (complexe et simple). Le mécanisme qui fournit ce dispositif est extensible.

Bugzilla peut supporter différents types de sorties, qui peuvent eux aussi avoir des formats multiples. Pour demander un certain type, vous pouvez joindre le &ctype=<contenttype> (tel que rdf ou html) au lien <cginame>.cgi. Si vous souhaitez rechercher un certain format, vous pouvez utiliser le &format=<format> (comme simple ou complex) dans l'URL.

Pour savoir si un CGI supporte plusieurs formats de sortie et plusieurs types, effectuez un grep sur le CGI pour « GetFormat ». S'il n'y en a pas, l'ajout de support de plusieurs formats/types n'est pas trop dur ; regardez comment c'est fait dans d'autres CGI, i.e. config.cgi.

Pour faire un nouveau modèle de format pour un CGI qui supporte ça, ouvrez un modèle existant pour ce CGI et prenez note du commentaire INTERFACE (s'il est présent). Ce commentaire définit quelles variables sont passées dans ce modèle. S'il n'y en a pas, j'ai bien peur que vous deviez lire le modèle et le code pour voir ce que vous avez comme informations.

Vous pouvez écrire votre modèle dans n'importe quel style de balisage ou de texte qui convient.

Il vous faut maintenant choisir le type de contenu dans lequel vous voulez qu'il soit utilisé. Les types de contenu sont définis dans le fichier Bugzilla/Constants.pm dans la constante contenttypes. Si votre type de contenu ne s'y trouve pas, ajoutez le. Mémorisez l'étiquette de trois ou quatre lettres affectée à votre type de contenu. Cette étiquette fera partie du nom de fichier du modèle.

	Note
	Après l'ajout ou la modification d'un type de contenu, il convient d'éditer Bugzilla/Constants.pm afin de répercuter les modifications. En outre, le fichier doit être conservé à jour après une mise à jour si des types de contenu ont été personnalisés dans le passé.

Enregistrez le modèle sous <stubname>-<formatname>.<contenttypetag>.tmpl. Testez le modèle en appelant le CGI par <cginame>.cgi?format=<formatname>&ctype=<type>.

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

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

global/header.html.tmpl : définit l'en-tête qui apparaît sur toutes les pages de Bugzilla. L'en-tête inclut la bannière, qui est ce qui apparaît aux utilisateurs et qui est probablement ce que vous voulez éditer plutôt que l'en-tête. Cependant, l'en-tête inclut également la section HTML HEAD, vous pourriez donc par exemple ajouter une feuille de style ou une balise META en éditant l'en-tête.

global/banner.html.tmpl : 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 assez sommaire, vous voudrez donc probablement la personnaliser pour donner à votre installation son propre aspect et sa propre convivialité. Il est recommandé de conserver le numéro de version Bugzilla sous une forme ou une autre pour permettre de déterminer la version que vous utilisez, et que les utilisateurs sachent quelle documentation ils doivent lire.

global/footer.html.tmpl : définit le pied de page qui apparaît sur toutes les pages de Bugzilla. En l'éditant, vous avez un autre moyen de donner rapidement son propre aspect et sa propre convivialité à votre installation Bugzilla.

global/variables.none.tmpl : définit une liste de termes qui peuvent être modifiés afin « d'estampiller » l'instance Bugzilla. De cette manière, les termes tels que « bugs » peuvent être remplacés par « problèmes » dans toute l'installation Bugzilla. Le nom « Bugzilla » et d'autres mots peuvent être tout aussi bien personnalisés.

list/table.html.tmpl : ce modèle gère l'apparence des listes de bogues créées par Bugzilla. En éditant ce modèle, on peut modifier la largeur et le titre des colonnes une par une, la taille maximale de l'affichage pour chaque entrée, et le comportement de l'enveloppe des entrées longues. Pour les longues listes de bogues, Bugzilla insère un « break » tous les 100 bogues par défaut ; ce comportement est également géré par ce modèle, et c'est là que cette valeur pourra être modifié.

bug/create/user-message.html.tmpl : message qui apparaît près du haut de la page de soumission de bogues. En le modifiant, vous pouvez dire à vos utilisateurs comment soumettre des bogues.

bug/process/midair.html.tmpl : ceci est le modèle utilisé si deux personnes modifient un bug simultanément. La deuxième personne a soumettre une modification verra apparaître cette page indiquant la modification apportée par la première personne et demandant s'ils veulent écraser cette modification ou revenir sur le bogue. Le titre et l'en-tête par défaut de cette page est « Collision en plein vol détectée ! » Si vous travaillez dans l'industrie aero-nautique ou un autre milieu ou ceci peut géner quelqu'un (oui, on nous a rapporté des histoires vraies à ce sujet), vous voudrez peut-être changer cette phrase.

bug/create/create.html.tmpl et bug/create/comment.txt.tmpl : vous n'avez peut-être pas envie de vous casser la tête à créer des zones personnalisées dans Bugzilla, mais vous voulez être sûr que chaque rapport de bogue contienne un nombre d'informations importantes pour lesquelles il n'y a pas de zone spéciale. Le système d'entrée de bogues a été conçu sous une forme extensible pour vous permettre d'ajouter arbitrairement des gadgets HTML, tels que listes déroulantes et zones de texte, à la page d'entrée de bogues et de faire apparaître leurs valeurs formatées dans la description initiale. Un champ caché qui indique le format doit être ajouté à l'intérieur du formulaire afin de rendre le modèle fonctionnel. Sa valeur doit être le suffixe de nom du 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é à l'intérieur du formulaire.

Un exemple en est le formulaire de soumission de bogues de mozilla.org. Le code pour cela est livré avec la distribution Bugzilla comme exemple à copier par vous. Vous le trouverez dans les fichiers create-guided.html.tmpl et comment-guided.html.tmpl.

Donc pour utiliser ce dispositif, 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 ajoutez y des gadgets pour chaque information que vous aimeriez voir collectée : un numéro de création, l'ensemble des étapes pour le reproduire.

Puis, créez un modèle comme custom/bug/create/comment.txt.tmpl, et nommez le comment-<formatname>.txt.tmpl. Ce modèle doit renvoyer aux champs du formulaire que vous avez créé en utilisant la syntaxe [% form.<fieldname> %]. Quand un rapport de bogue est soumis, le commentaire initial joint au rapport de bogue sera formaté d'après la disposition de ce modèle.

Par exemple, si votre modèle enter_bug possédait un champ

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

et que votre comment.txt.tmpl avait

BuildID : [% form.buildid %]

alors

BuildID : 20020303

apparaîtrait dans le commentaire initial.

Bugzilla prend en compte l'en-tête HTTP Accept: de l'utilisateur. Vous pouvez installer des modèles dans d'autres langues, et Bugzilla retiendra le plus approprié d'après l'ordre de priorités que vous avez défini. Beaucoup de modèles de langue peuvent être récupérés à partir de http://www.bugzilla.org/download.html#localizations. Les instructions pour intégrer de nouvelles langues sont aussi disponibles à cet endroit.

Après avoir décompressé les localisations (ou créé les vôtres) dans le répertoire BUGZILLA_ROOT/template, vous devez mettre à jour le paramètre languages pour contenir toutes les adaptations que vous aimeriez laisser. Vous pouvez également, si vous le souhaitez, modifier le paramètre defaultlanguage en remplaçant « en » par autre chose si vous ne voulez pas l'anglais comme langue par défaut.