5.4. Templates

Bugzilla utilise un système de templates pour définir son interface utilisateur. Les templates standards peuvent être modifiés, remplacés ou écrasés. Vous pouvez aussi utiliser des crochets de template dans une extension pour ajouter ou modifier le comportement des templates en utilisant une interface stable.

5.4.1. Structure du répertoire Template

La structure du répertoire de templates débute par le répertoire template, qui contient un répertoire pour chaque localisation (langue) installée. Bugzilla fournit par défaut les templates en anglais, le répertoire s'appelle donc en et nous parlerons donc du répertoire template/en tout au long de cette documentation. Sous le répertoire template/en se trouve le répertoire default qui contient tous les templates standards fournis par Bugzilla.

Avertissement

Il existe aussi un répertoire data/template. C'est ici que Template Toolkit place les versions compilées (c'est-à-dire le code Perl) des templates. Ne modifiez pas les fichiers dans ce répertoire ou tous vos changements seront perdus lors de la prochaine compilation des templates par Template Toolkit.

5.4.2. Choisir une méthode de personnalisation

Si vous voulez modifier les templates de Bugzilla, la première décision à prendre est la méthode pour le faire. Il y a trois possibilités, dépendant principalement de la portée de vos modifications et de la méthode que vous utilisez pour mettre à jour Bugzilla.

1. Vous pouvez éditer directement les templates dans template/en/default.
2. Vous pouvez copier les templates à modifier dans un répertoire miroir ayant la même arborescence dans template/en/custom. Les templates dans ce répertoire écraseront automatiquement tout template de même nom et situé au même endroit de l'arborescence du répertoire template/en/default. (Le répertoire custom n'existe pas par défaut et doit être créé si vous voulez l'utiliser).
3. Vous pouvez utiliser les crochets présents dans de nombreux templates pour ajouter des éléments ou modifier l'interface utilisateur à l'aide d'une extension. Les crochets ne sont généralement pas supprimés d'une version à l'autre et bénéficient d'une interface stable.

La troisième méthode est la meilleure s'il existe des crochets dans les endroits appropriés and the change you want to do is possible using hooks. It's not very easy et que le changement que vous voulez faire est possible avec les crochets. C'est ce qui est le plus souvent utilisé pour faire des ajouts. Vous pouvez faire des modifications si vous ajoutez du code JS qui fera les modifications lors du chargement de la page. Vous pouvez retirer des éléments de l'interface utilisateur en ajouter du code CSS pour les masquer.

Contrairement aux crochets de code, il n'est pas nécessaire de documenter les crochets de templates, il suffit d'ouvrir le template et de rechercher Hook.process.

S'il n'y a pas de crochet disponible, alors la deuxième méthode de personnalisation doit être utilisée si vous voulez faire des changements majeurs, car il est garanti que le contenu du répertoire custom ne sera pas touché pendant une mise à jour, et vous pouvez décider de revenir aux templates standards ou continuer à utiliser les vôtres, ou faire les modifications nécessaires pour être compatible avec la nouvelle version. C'est aussi une bonne méthode pour des fichiers totalement nouveaux ou pour quelques fichiers comme bug/create/user-message.html.tmpl qui sont conçus pour être entièrement remplacés.

En utilsiant la deuxième méthode, votre interface utilisateur peut être corrompue si des changements incompatibles sont faits dans l'interface des templates. Les templates changent régulièrement et par conséquent, ils ne sont pas tous individuellement documentés. Vous devrez alors trouver ce qui a changé et adapter vos templates en conséquence.

Pour des changements mineurs, la commodité de la première méthode est difficile à battre. Lors de la mise à jour, git fusionnera vos modifications dans la nouvelle version pour vous. Le revers de la médaille, si la fusion échoue, c'est que Bugzilla ne fonctionnera pas correctement jusqu'à ce que vous ayez corrigé le problème et réintégré votre code.

Vous pouvez aussi voir ce que vous avez changé en utilisant git diff, ce qui n'est pas possible si vous avez placé le fichier dans le répertoire custom.

5.4.3. Comment modifier les templates

Note

Si vous faites des modifications de template que vous souhaitez soumettre pour être inclus dans les standard de Bugzilla, veuillez lire les sections appropriées du Guide des développeurs.

Bugzilla utilise un système de template appelé Template Toolkit. La syntaxe de ce langage dépasse le cadre de ce guide. Il est assez facile à appréhender en consultant les templares de Bugzilla. Vous pouvez aussi consulter le manuel, disponible sur le site Web de Template Toolkit.

Vous devez porter une attention particulière sur la nécessité de flitrer correctement les données HTML passées dans le template. Cela signifie que si des données peuvent contenir un caractère spécial HTML tel que < et que les données ne sont pas destinées à être du HTML, elles doivent être converties en entités, par ex. : <. Il faut utiliser le filtre html de Template Toolkit pour cela (ou le filtre uri pour encoder les caractères spéciaux dans les URL). Si vous oubliez de le faire, vous pourriez ouvrir votre installation aux attaques par « cross-site scripting ».

Vous devez exécuter la commande ./checksetup.pl après avoir modifié des templates. Ne pas le faire peut conduire à ce que vos changements ne soient pas pris en compte ou que les permissions sur les fichiers modifiés ne soient pas correctes et que le serveur Web ne soient pas en mesure de les lire.

5.4.4. Format et type de template

Certains CGI sont capables d'utiliser plus d'un template. Par exemple, buglist.cgi peut renvoyer deux formats de HTML (complexe et simple). Chacun d'eux dans un template séparé. Le mécanisme qui fournit cette fonctionnalité est extensible : vous pouvez ajouter de nouveaux templates pour ajouter de nouveaux formats.

Vous pourriez utiliser cette fonctionnalité pour par exemple ajouter un formulaire de saisie de bogue personnalisé pour un sous-ensemble particulier d'utilisateurs ou un type de bogue particulier.

Bugzilla peut aussi gérer deux types de sorties. Par exemple, les bogues sont disponibles aux formats HTML et XML, et ce mécanisme est aussi extensible pour ajouter de nouveaux types de contenu. Cependant, au lieu d'utiliser de telles interfaces ou d'étendre Bugzilla pour en ajouter d'autres, il est préférable d'utiliser les Référence API des WebServices pour s'intégrer avec Bugzilla.

Pour voir si un CGI gère plusieurs formats et types de sortie, recherchez dans le fichier CGI get_format. Si ce n'est pas présent, ajouter la gestion de plusieurs formats ou types n'est pas très compliqué : regardez dans d'autres fichiers CGI comment c'est mis en œuvre, par exemple : config.cgi.

Pour faire un nouveau format de template qui soit géré par un fichier CGI, ouvrez le template pour ce fichier CGI et regardez le commentaire « INTERFACE » (s'il existe). Ce commentaire indique les variables qui sont passées à ce template. S'il n'existe pas, il faudra lire le template et le code pour trouver cette information.

Écrivez votre template avec le langage à balises ou le style de texte approprié.

Vous devez décider du type de contenu que votre template va servir. Les types de contenu sont définis dans le fichier Bugzilla/Constants.pm dans la constante contenttypes. Si votre type de contenu n'est pas présent, ajoutez-le. Rappelez-vous du marqueur à trois ou quatre lettre affecté à votre type de contenu. Ce marqueur fera partie du nom du filename.

Enregistrez votre nouveau template sous la forme <stubname>-<formatname>.<contenttypetag>.tmpl. Essayez votre template en l'appelant avec le fichier CGI : <cginame>.cgi?format=<formatname>. Ajoutez &ctype=<type> si le type n'est pas HTML.

5.4.5. Templates particuliers

Il existe quelques templates qui pourraient vous intéresser pour personnaliser votre installation.

index.html.tmpl :

Ceci est la page d'accueil de Bugzilla.

global/header.html.tmpl :

Ceci définit l'en-tête utilisé dans toutes les pages de Bugzilla. L'en-tête comprend la bannière, qui est ce qui est présenté aux utilisateurs et vous vous voudrez certainement modifier. Cependant, l'en-tête comprend aussi la section « HTML HEAD », et vous pourriez par exemple vouloir y ajouter une feuile 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 chaque page de Bugzilla. La bannière par défaut est sobre et vous voudrez peut-être la personnaliser pour donner à votre installation une apparence distinctive. Il est recommandé de conserver le numéro de version de Bugzilla sous une forme ou une autre afin de déterminer la version de Bugzilla exécutée et que les utilisateurs sachent quelle documentation lire.

global/footer.html.tmpl :

Ceci définit le pied de page de toutes les pages de Bugzilla. Vous pouvez modifier ce fichier pour personnaliser votre installation et lui donner une apparence distinctive.

global/variables.none.tmpl :

Ceci permet de changer le terme « bogue » pour un autre (par ex. : « ticket ») dans toute l'interface. Il permet aussi de remplacer le nom Bugzilla par un autre (par ex. : « Support utilisateur de Toto Corp. »).

list/table.html.tmpl :

Ce template contrôle l'apparence des listes de bogues créées par Bugzilla. En modifiant ce template, vous pouvez contrôler pour chaque colonne sa largeur et son titre, la longueur maximale de chaque entrée et le comportement à adopter pour les entrées très longues. Pour les longues listes de bogues, Bugzilla insère un séparateur tous les cent bogues par défaut. Ce comportement est également contrôlé par ce template et la 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 saisie d'un bogue. En le modifiant, vous pouvez indiquer à vos utilisateurs comment il doivent rapporter un bogue.

bug/process/midair.html.tmpl :

C'est la page utilisée si deux personnes soumettent en même temps une modification sur le même bogue. La deuxième personne soumettant les changements verra cette page lui indiquant ce que la première personne a modifié et demandera si elle souhaite écraser ces changements ou annuler et revenir sur le bogue. Le titre par défaut et l'en-tête de ce page est : « Collision détectée ! ». Si vous travaillez dans l'industrie aéronautique ou un autre environnement où ce message pourrait paraître inapproprié (oui, on nous a rapporté des histoires vraies à ce sujet) vous voudrez peut-être changer ce message par un autre plus adapté à votre environnement.

bug/create/create.html.tmpl et bug/create/comment.txt.tmpl :

Vous ne voulez peut-être pas faire l'effort de créer des champs personnalisés dans Bugzilla, mais vous voulez vous assurer que chaque rapport de bogue contienne un certain nombre d'informations importantes pour lesquelles il n'y a pas de champ spécifique. Le système de saisie de bogue a été conçu de manière extensible pour vous permettre d'ajouter à votre discrétion des widgets HTML, tels que des boîtes de texte ou des listes déroulantes dans la page de saisie de bogues, et avoir leurs valeurs affichées dans le commentaire initial.

Un exemple de ceci est dans le formulaire de saisie assistée. Ce code est fourni dans Bugzilla comme exemple que vous pouvez copier. Il se trouve dans les fichiers create-guided.html.tmpl et comment-guided.html.tmpl.

Un champ masqué indiquant le format doit être ajouté dans le formulaire afin de rendre le template fonctionnel. Sa valeur doit être le suffixe du nom du template. Par exemple, si le fichier s'appelle create-guided.html.tmpl, alors

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

est utilisé à l'intérieur du formulaire.

Pour utiliser cette fonctionnalité, créez un template personnalisé pour le fichier enter_bug.cgi. Le template par défaut sur lequel vous pourriez vous baser est default/bug/create/create.html.tmpl. Nommez-le custom/bug/create/create-<formatname>.html.tmpl, et à l'intérieur ajoutez les champs de saisie du formulaire pour chaque information désirée, comme par exemple, le numéro de version ou les étapes à reproduire.

Ensuite, créez un template basé sur default/bug/create/comment.txt.tmpl et nommez-le custom/bug/create/comment-<formatname>.txt.tmpl. Il nécessite deux lignes à placer au début du fichier comme suit :

[% USE Bugzilla %]
[% cgi = Bugzilla.cgi %]

Ensuite, ce template peut référencer les champs de formulaire que vous avez créés en utilisant la syntaxe [% cgi.param("field_name") %]. Quand un rapport de bohue est soumis, le commentaire initial attaché au rapport de bogue sera formaté selon la disposition de ce template.

Par exemple, si votre template personnalisé enter_bug a un champ

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

et que votre fichier comment.txt.tmpl a

[% USE Bugzilla %]
[% cgi = Bugzilla.cgi %]
Build Identifier: [%+ cgi.param("buildid") %]

alors quelque chose comme ceci

Build Identifier: 20140303

apparaîtra dans le commentaire initial.

Le système permet de collecter des données structurées dans les rapports de bogue sans la complexité d'une interface utilisateur contenant un grand nombre de champs personnalisés.

---

Cette documentation contient très probablement des bogues ; si vous en découvrez, veuillez les signaler ici.