5.5. Extensions

La meilleure façon de personnaliser Bugzilla est d’utiliser une extension Bugzilla. Les extensions peuvent modifier le code et l’interface utilisateur de Bugzilla et être portées dans les futures versions de Bugzilla avec peu d’effort. Nous maintennons une liste des extensions disponibles écrites par d’autres développeurs sur notre wiki. Vous devrez vous assurer que l’extension en question fonctionne avec votre version de Bugzilla.

Ou vous pouvez aussi écrire votre propre extension. Consulter la documentation des extensions de Bugzilla pour l’essentiel des informations sur la façon de les faire. Il est utile aussi de lire la section sur les Templates. Il existe une extension d’exemple dans $BUGZILLA_HOME/extensions/Example/ qui montre comment utiliser tous les crochets de code.

Cette section explique comment réaliser quelques tâches courantes en utilisant les API Extension.

5.5.1. Ajouter une nouvelle page à Bugzilla

Il peut exister des situations où il est utile d’ajouter une nouvelle page à Bugzilla qui n’a que très peu ou pas de relation avec les autres pages, ou qui peut-être n’utilise que très peu de données Bugzilla. Une page d’aide ou un rapport personnalisé par exemple. Le meilleur moyen d’y parvenir est d’utiliser page.cgi et le crochet page_before_template.

5.5.2. Modifier les données sur une page existante

Le crochet template_before_process peut être utilisé pour personnaliser les données affichées sur une page particulière si vous connaissez le template utilisé. Ce crochet peu accéder à toutes les variables de template avant qu’elles soient envoyées au moteur de template.

5.5.3. Ajouter de nouveaux champs aux bogues

Pour ajouter de nouveaux champs sur des bogues, vous devrez faire ce qui suit :

Ajouter un crochet install_update_db pour ajouter les champs en appelant Bugzilla::Field->create (seulement si le champ n’existe pas déjà). Cela ressemble à ce qui suit pour un champ simple :

my $field = new Bugzilla::Field({ name => $name });
return if $field;

$field = Bugzilla::Field->create({
    name        => $name,
    description => $description,
    type        => $type,        # À partir de la liste dans Constants.pm
    enter_bug   => 0,
    buglist     => 0,
    custom      => 1,
});

Poussez le nom du champ dans le tableau approprié dans les crochets bug_columns et bug_fields.
Si vous voulez des accesseurs directs ou d’autres fonctions sur l’objet, vous aurez besoin d’ajouter un bloc BEGIN dans votre fichier Extension.pm :
```
BEGIN {
   *Bugzilla::Bug::is_foopy = \&_bug_is_foopy;
}

...

sub _bug_is_foopy {
    return $_[0]->{'is_foopy'};
}
```
Vous n’avez pas besoin de modifier Bugzilla/DB/Schema.pm.
Vous pouvez utiliser bug_end_of_create, bug_end_of_create_validators et bug_end_of_update pour créer ou mettre à jour les valeurs pour le nouveau champ.

5.5.4. Ajouter de nouveaux champs pour d’autres choses

Si vous ajoutez de nouveaux champs pour un objet autre qu’un bogue, vous devrez descendre un niveau plus bas en vous référant aux instructions ci-dessous :

Dans install_update_db, utilisez bz_add_column
Poussez les colonnes dans object_columns et object_update_columns au lieu de bug_columns.
Ajoutez les validateurs pour les valeurs dans object_validators

Le processus pour ajouter les fonctions accesseurs est le même.

Vous pouvez utiliser les crochets object_end_of_create, object_end_of_create_validators, object_end_of_set_all et object_end_of_update pour créer ou mettre à jour les valeurs des champs du nouvel objet que vous avez ajouté. Dans les cochets, vous pouvez vérifier le type de l’objet manipulé et passer outre les objets dont vous n’avez pas besoin. Par exemple, si vous ajoute un nouveau champ à la table products :

sub object_end_of_create {
    my ($self, $args) = @_;
    my $class = $args->{'class'};
    my $object = $args->{'object'};
    if ($class->isa('Bugzilla::Product') {
        [...]
    }
}

Vous devrez faire ce filtrage pour la plupart des crochets dont les noms commencent par object_.

5.5.5. Ajouter des panneaux de configuration d’administration

Si vous ajoutez de nouvelles fonctionnalités à Bugzilla, elles peuvent avoir des options ou des paramètres configurables. Vous devez alors ajouter un panneau de configuration pour permettre à un administrateur de définir ces paramètres.

En plus du crochet config_add_panels, vous aurez besoin d’un template pour définir les chaînes de l’interface utilisateur pour le panneau. Consultez les templates dans template/en/default/admin/params pour des exemples et ajoutez le vôtre dans template/en/default/admin/params dans le répertoire de votre extension.

Vous pouvez accéder aux valeurs des paramètres des templates en utilisant :

[% Param('param_name') %]

et dans votre code, en utilisant :

Bugzilla->params->{'param_name'}

5.5.6. Ajouter des préférences utilisateur

Pour ajouter une nouvelle préférence utilisateur :

Appelez add_setting('setting_name', ['some_option', 'another_option'], 'some_option') dans le crochet install_before_final_checks. (Le dernier paramètre est le nom de l’option par défaut).
Ajoutez des descriptions pour les identifiants pour vos paramètres et choix (setting_name, some_option etc.) dans le hash défini dans global/setting-descs.none.tmpl. Faites ceci dans un template de crochet : hook/global/setting-descs-settings.none.tmpl. Votre code peut voir la variable de hash ; ajoutez plus de membres dans celui-ci.
Pour changer le comportement basé sur votre paramètre, référencez-le dans des templates en utilisant [% user.settings.setting_name.value %]. Référencez-le dans votre code en utilisant $user->settings->{'setting_name'}->{'value'}. La valeur sera un des noms de l’option (par ex. : some_option).

5.5.7. Modifier qui peut changer quoi

Les sociétés ont souvent des règles sur les employés ou les catégories d’employés autorisés à modifier certaines choses dans le système de bogues. Par exemple, seul le responsable QA est autorisé à marquer le bogue comme VÉRIFIÉ. Bugzilla a été conçu pour rendre cela facile en écrivant vos propres règles personnalisées pour définir qui est autorisé à faire certains types de transitions sur les bogues.

Par défaut, les responsables, les responsables QA et les utilisateurs avec les privilèges editbugs peuvent modifier tous les champs des bogues, sauf restrictions de groupes (à moins qu’ils ne soient membres des groupes qu’ils essaient de modifier). Les rapporteurs de bogues ont aussi la possibilité de modifier certains champs, mais de manière plus restrictive. Les autres utilisateurs, sans prvilèges editbugs, ne peuvent pas modifier les bogues, sauf pour ajouter un commentaire ou s’ajouter à la liste « Copie à ».

Parce que ce type de modification est une demande récurrente, nous avons ajouté un crochet spécifique que les Extensions peuvent appeler. Ce crochet s’appelle bug_check_can_change_field et est documenté dans la documentation sur les crochets.

5.5.8. Vérifier la syntaxe

Il n’est pas évident de voir comment vérifier la syntaxe des modules Perl de votre extension, s’il elle en possède. Exécuter la commande checksetup.pl peut détecter certaines erreurs, mais les informations données ne sont pas nécessairement compréhensible.

perl -Mlib=lib -MBugzilla -e 'BEGIN { Bugzilla->extensions; } use Bugzilla::Extension::ExtensionName::Class;'

(exécuté à partir de $BUGZILLA_HOME) est ce que vous voulez pour vérifier la syntaxe.

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