Bugzilla:Writing Extensions

Note: These are the instructions for versions of Bugzilla before 3.6. For 3.6 and later, see the Bugzilla::Extension documentation. There is a script included in 3.6 and later that will convert extensions from the format described below to the 3.6 format.

You can write "extensions" for Bugzilla, which change Bugzilla's functionality without modifying any of the core code.

Extensions can modify two areas: the code of Bugzilla, and the templates (user interface) of Bugzilla.

Extensions go into their own directory underneath the extensions/ directory of Bugzilla. So if you had an extension named "foo", all its files would go into a directory called extensions/foo/.

Code Hooks

Bugzilla supports a system of code hooks that allow us to make code "happen" at different times on different pages in Bugzilla.

The Hooks Documentation describes pretty well how the hooks work, and what every single hook is.

If you need a clearer example of how the code hooks work, there is example code for almost every code hook in the extensions/example/code/ directory.

Bugzilla will call each extension's hook code in a random sequence whenever it processes a hook, so try to make sure that your hooks don't do anything that might interfere with the working of some other extension.

Newer versions of Bugzilla have more hooks than older versions of Bugzilla, so make sure that your extension will be compatible with your version of Bugzilla.

Libraries For Your Hooks

If your code has some libraries that it uses, you can put them in the lib/ directory of your extension. This directory is added to Perl's "include path" right before a code hook is processed.

So, if you had an extension called "foo", you could create a file called extensions/foo/lib/Bar/Baz.pm. Then you could use that from your code hooks by saying "use Bar::Baz;" in your code.

Adding New Code Hooks

If you need a new hook for your extension, please just file a bug requesting it, and possibly also include a patch that adds the hook. Simple hooks can often make it even on to stable branches of Bugzilla, so your hook could be in the next point release of our stable branch.

In order for a hook to be accepted into Bugzilla, it has to work, it must have documentation, and it must have example code in extensions/example/code/.

Template Hooks

Templates can also be extended, using a system of "hooks" that add new UI elements to a particular area of Bugzilla without modifying the code of the existing templates. This is a good way for your extension to modify the user interface of Bugzilla.

You can see what places in the user interface can be hooked by searching for the string "Hook.process" in Bugzilla's templates (in the template/en/default/ directory). That will also give you the name of the hooks--the first argument to "Hook.process" is the name of the hook, which I will show you how to use further down in this section. For example, if you see Hook.process("additional_header"), that means the name of the hook is "additional_header" (without the quotes).

Template extensions go into the template/en/ directory of your extension. So, if you had an extension called "foo", your template extensions would go into extensions/foo/template/en/.

The file names and directories that your templates go into follow a specific pattern. If you're extending the template/en/default/global/header.html.tmpl file, using the additional_header hook, and your extension was called "foo", then your hook code would go into a file named extensions/foo/template/en/global/header-additional_header.html.tmpl.

Note that the path is similar to the original file's path, but it lacks "default", and that the name of the hook becomes part of the name of the template extension, appended to the actual template's name with a hyphen.

Any code you put into that file will happen at the point that "Hook.process" is called in the template you are extending.

Templates are written in the Template Toolkit language.

There are a few examples of template hooks in the extensions/example/template directory.

Adding New Template Hooks

It's even easier to add template hooks to Bugzilla than it is to add code hooks. Usually you just have to submit a patch to us that adds the hook to the template, and go through our normal development process. If you want to include some example code, that would be great, but you don't have to. New template hooks will usually be approved even for stable branches.

Overriding Existing Templates

Sometimes you don't want to extend a template, you just want to replace it entirely with your extension's template.

To replace the template/en/default/global/banner.html.tmpl in an extension named "foo", create a file called extensions/foo/template/en/default/global/banner.html.tmpl. Note that this is very similar to the path for a template hook, except that it includes "default/" whereas the template hook didn't.

Be warned, though, if multiple extensions override a template, it's a toss-up as to which one's will actually be rendered. So if you want to be sure your extension won't conflict with another extension, just use template hooks instead of overriding existing templates.

Bugzilla actually has lots of ways of overriding templates (mostly for historical reasons, but there are a few practical reasons as well). If you're curious about which methods "win" over each other, there is some documentation on that--directories higher on the list override directories lower on the list.

New Templates

You can also use the above method to create entirely new templates for your extension. If you have an extension called "foo", and you add a file named extensions/foo/template/en/default/bar/baz.html.tmpl, you can refer to that file as "bar/baz.html.tmpl" in all your code and templates.

Disabling Extensions

Extensions can be "disabled" by putting a file named "disabled" into the extension's directory.

So for example, to disable the "foo" extension, I would create a file named extensions/foo/disabled.

When an extension is disabled, none of its template hooks or code hooks will be called by Bugzilla.

Need Help with Writing Extensions?

The Bugzilla developers would be happy to help you with any questions you might have about writing extensions. Probably the best way to ask us questions is to get in touch with us on IRC.

"Publishing" Your Extension

If you want to "publish" your extension so that other Bugzilla users can use it, the best thing to do is to package it up somewhere and then link to it from the appropriate section of Bugzilla:Addons. That is currently the central location where we track everything that extends or interacts with Bugzilla.