5.5. Extensions

One of the best ways to customize Bugzilla is by using a Bugzilla Extension. Extensions can modify both the code and UI of Bugzilla in a way that can be distributed to other Bugzilla users and ported forward to future versions of Bugzilla with minimal effort. We maintain a list of available extensions written by other people on our wiki. You would need to make sure that the extension in question works with your version of Bugzilla.

Or, you can write your own extension. See the Bugzilla Extension documentation for the core documentation on how to do that. It would make sense to read the section on Templates. There is also a sample extension in $BUGZILLA_HOME/extensions/Example/ which gives examples of how to use all the code hooks.

This section explains how to achieve some common tasks using the Extension APIs.

5.5.1. Adding A New Page to Bugzilla

There are occasions where it's useful to add a new page to Bugzilla which has little or no relation to other pages, and perhaps doesn't use very much Bugzilla data. A help page, or a custom report for example. The best mechanism for this is to use page.cgi and the page_before_template hook.

5.5.2. Altering Data On An Existing Page

The template_before_process hook can be used to tweak the data displayed on a particular existing page, if you know what template is used. It has access to all the template variables before they are passed to the templating engine.

5.5.3. Adding New Fields To Bugs

To add new fields to a bug, you need to do the following:

• Add an install_update_db hook to add the fields by calling Bugzilla::Field->create (only if the field doesn't already exist). Here's what it might look like for a single field:

  my $field = new Bugzilla::Field({ name => $name });
  return if $field;
  
  $field = Bugzilla::Field->create({
      name        => $name,
      description => $description,
      type        => $type,        # From list in Constants.pm
      enter_bug   => 0,
      buglist     => 0,
      custom      => 1,
  });
  

• Push the name of the field onto the relevant arrays in the bug_columns and bug_fields hooks.

• If you want direct accessors, or other functions on the object, you need to add a BEGIN block to your Extension.pm:

  BEGIN {
     *Bugzilla::Bug::is_foopy = \&_bug_is_foopy;
  }
  
  ...
  
  sub _bug_is_foopy {
      return $_[0]->{'is_foopy'};
  }
  

• You don't have to change Bugzilla/DB/Schema.pm.

• You can use bug_end_of_create, bug_end_of_create_validators, and bug_end_of_update to create or update the values for your new field.

5.5.4. Adding New Fields To Other Things

If you are adding the new fields to an object other than a bug, you need to go a bit lower-level. With reference to the instructions above:

• In install_update_db, use bz_add_column instead
• Push on the columns in object_columns and object_update_columns instead of bug_columns.
• Add validators for the values in object_validators

The process for adding accessor functions is the same.

You can use the hooks object_end_of_create, object_end_of_create_validators, object_end_of_set_all, and object_end_of_update to create or update the values for the new object fields you have added. In the hooks you can check the object type being operated on and skip any objects you don't care about. For example, if you added a new field to the products table:

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

You will need to do this filtering for most of the hooks whose names begin with object_.

5.5.5. Adding Admin Configuration Panels

If you add new functionality to Bugzilla, it may well have configurable options or parameters. The way to allow an administrator to set those is to add a new configuration panel.

As well as using the config_add_panels hook, you will need a template to define the UI strings for the panel. See the templates in template/en/default/admin/params for examples, and put your own template in template/en/default/admin/params in your extension's directory.

You can access param values from Templates using:

[% Param('param_name') %]

and from code using:

Bugzilla->params->{'param_name'}

5.5.6. Adding User Preferences

To add a new user preference:

• Call add_setting('setting_name', ['some_option', 'another_option'], 'some_option') in the install_before_final_checks hook. (The last parameter is the name of the option which should be the default.)
• Add descriptions for the identifiers for your setting and choices (setting_name, some_option etc.) to the hash defined in global/setting-descs.none.tmpl. Do this in a template hook: hook/global/setting-descs-settings.none.tmpl. Your code can see the hash variable; just set more members in it.
• To change behaviour based on the setting, reference it in templates using [% user.settings.setting_name.value %]. Reference it in code using $user->settings->{'setting_name'}->{'value'}. The value will be one of the option tag names (e.g. some_option).

5.5.7. Altering Who Can Change What

Companies often have rules about which employees, or classes of employees, are allowed to change certain things in the bug system. For example, only the bug's designated QA Contact may be allowed to VERIFY the bug. Bugzilla has been designed to make it easy for you to write your own custom rules to define who is allowed to make what sorts of value transition.

By default, assignees, QA owners and users with editbugs privileges can edit all fields of bugs, except group restrictions (unless they are members of the groups they are trying to change). Bug reporters also have the ability to edit some fields, but in a more restrictive manner. Other users, without editbugs privileges, cannot edit bugs, except to comment and add themselves to the CC list.

Because this kind of change is such a common request, we have added a specific hook for it that Extensions can call. It's called bug_check_can_change_field, and it's documented in the Hooks documentation.

5.5.8. Checking Syntax

It's not immediately obvious how to check the syntax of your extension's Perl modules, if it contains any. Running checksetup.pl might do some of it, but the errors aren't necessarily massively informative.

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

(run from $BUGZILLA_HOME) is what you need.

---

This documentation undoubtedly has bugs; if you find some, please file them here.