Bugzilla::Extension - Base class for Bugzilla Extensions.
The following would be in extensions/Foo/Extension.pm or extensions/Foo.pm:
package Bugzilla::Extension::Foo
use strict;
use parent qw(Bugzilla::Extension);
our $VERSION = '0.02';
use constant NAME => 'Foo';
sub some_hook_name { ... }
__PACKAGE__->NAME;
Custom templates would go into extensions/Foo/template/en/default/. Template hooks would go into extensions/Foo/template/en/default/hook/.
This is the base class for all Bugzilla extensions.
The "SYNOPSIS" above gives a pretty good overview of what's basically required to write an extension. This section gives more information on exactly how extensions work and how you write them. There is also a wiki page with additional HOWTOs, tips and tricks.
There is a script, extensions::create, that will set up the framework of a new extension for you. To use it, pick a name for your extension and, in the base bugzilla directory, do:
extensions/create.pl NAME
But replace NAME with the name you picked for your extension. That will create a new directory in the extensions/ directory with the name of your extension. The directory will contain a full framework for a new extension, with helpful comments in each file describing things about them.
There is a sample extension in extensions/Example/ that demonstrates most of the things described in this document, so if you find the documentation confusing, try just reading the code instead.
Extension code lives under the extensions/ directory in Bugzilla.
There are two ways to write extensions:
.pm file in the extensions/ directory.
For example, if you wanted to create an extension called "Foo" using this method, you would put your code into a file called extensions/Foo.pm.
For example, if you wanted to create an extension called "Foo" using this method, you would put your code into a file called extensions/Foo/Extension.pm.
NAME.The "name" of an extension shows up in several places:
package Bugzilla::Extension::Foo;
NAME constant that must be defined for every extension:
use constant NAME => 'Foo';
__PACKAGE__->NAME;
You'll notice that though most Perl packages end with 1;, Bugzilla Extensions must always end with __PACKAGE__->NAME;.
The name must be identical in all of those locations.
In Bugzilla::Hook, there is a list of hooks. These are the various areas of Bugzilla that an extension can "hook" into, which allow your extension to perform code during that point in Bugzilla's execution.
If your extension wants to implement a hook, all you have to do is write a subroutine in your hook package that has the same name as the hook. The subroutine will be called as a method on your extension, and it will get the arguments specified in the hook's documentation as named parameters in a hashref.
For example, here's an implementation of a hook named foo_start that gets an argument named bar:
sub foo_start {
my ($self, $args) = @_;
my $bar = $args->{bar};
print "I got $bar!\n";
}
And that would go into your extension's code file--the file that was described in the "Where Extension Code Goes" section above.
During your subroutine, you may want to know what values were passed as CGI arguments to the current script, or what arguments were passed to the current WebService method. You can get that data via "input_params" in Bugzilla.
If you need a new hook for your extension and you want that hook to be added to Bugzilla itself, see our development process at http://wiki.mozilla.org/Bugzilla:Developers.
In order for a new hook to be accepted into Bugzilla, it has to work, it must have documentation in Bugzilla::Hook, and it must have example code in extensions/Example/Extension.pm.
One question that is often asked about new hooks is, "Is this the most flexible way to implement this hook?" That is, the more power extension authors get from a hook, the more likely it is to be accepted into Bugzilla. Hooks that only hook a very specific part of Bugzilla will not be accepted if their functionality can be accomplished equally well with a more generic hook.
If there are certain Perl modules that your extension requires in order to run, there is a way you can tell Bugzilla this, and then checksetup will make sure that those modules are installed, when you run checksetup.
To do this, you need to specify a constant called REQUIRED_MODULES in your extension. This constant has the same format as "REQUIRED_MODULES" in Bugzilla::Install::Requirements.
If there are optional modules that add additional functionality to your application, you can specify them in a constant called OPTIONAL_MODULES, which has the same format as "OPTIONAL_MODULES" in Bugzilla::Install::Requirements.
If your extension needs a particular Perl module in order to compile, then you have a "chicken and egg" problem--in order to read REQUIRED_MODULES, we have to compile your extension. In order to compile your extension, we need to already have the modules in REQUIRED_MODULES!
To get around this problem, Bugzilla allows you to have an additional file, besides Extension.pm, called Config.pm, that contains just REQUIRED_MODULES. If you have a Config.pm, it must also contain the NAME constant, instead of your main Extension.pm containing the NAME constant.
The contents of the file would look something like this for an extension named Foo:
package Bugzilla::Extension::Foo;
use strict;
use constant NAME => 'Foo';
use constant REQUIRED_MODULES => [
{
package => 'Some-Package',
module => 'Some::Module',
version => 0,
}
];
__PACKAGE__->NAME;
Note that it is not a subclass of Bugzilla::Extension, because at the time that module requirements are being checked in checksetup, Bugzilla::Extension cannot be loaded. Also, just like Extension.pm, it ends with __PACKAGE__->NAME;. Note also that it has the exact same package name as Extension.pm.
This file may not use any Perl modules other than Bugzilla::Constants, Bugzilla::Install::Util, Bugzilla::Install::Requirements, and modules that ship with Perl itself.
If you want to define both REQUIRED_MODULES and OPTIONAL_MODULES, they must both be in Config.pm or both in Extension.pm.
Every time your extension is loaded by Bugzilla, Config.pm will be read and then Extension.pm will be read, so your methods in Extension.pm will have access to everything in Config.pm. Don't define anything with an identical name in both files, or Perl may throw a warning that you are redefining things.
This method of setting REQUIRED_MODULES is of course not available if your extension is a single file named Foo.pm.
If any of this is confusing, just look at the code of the Example extension. It uses this method to specify requirements.
Extensions often want to have their own Perl modules. Your extension can load any Perl module in its lib/ directory. (So, if your extension is extensions/Foo/, then your Perl modules go into extensions/Foo/lib/.)
However, the package name of your libraries will not work quite like normal Perl modules do. extensions/Foo/lib/Bar.pm is loaded as Bugzilla::Extension::Foo::Bar. Or, to say it another way, use Bugzilla::Extension::Foo::Bar; loads extensions/Foo/lib/Bar.pm, which should have package Bugzilla::Extension::Foo::Bar; as its package name.
This allows any place in Bugzilla to load your modules, which is important for some hooks. It even allows other extensions to load your modules, and allows you to install your modules into the global Perl install as Bugzilla/Extension/Foo/Bar.pm, if you'd like, which helps allow CPAN distribution of Bugzilla extensions.
Note: If you want to use or require a module that's in extensions/Foo/lib/ at the top level of your Extension.pm, you must have a Config.pm (see above) with at least the NAME constant defined in it.
Extensions store templates in a template subdirectory of the extension. (Obviously, this isn't available for extensions that aren't a directory.)
The format of this directory is exactly like the normal layout of Bugzilla's template directory--in fact, your extension's template directory becomes part of Bugzilla's template "search path" as described in "template_include_path" in Bugzilla::Install::Util.
You can actually include templates in your extension without having any .pm files in your extension at all, if you want. (That is, it's entirely valid to have an extension that's just template files and no code files.)
Bugzilla's templates are written in a language called Template Toolkit. You can find out more about Template Toolkit at http://template-toolkit.org.
There are two ways to extend or modify Bugzilla's templates: you can use template hooks (described below) or you can override existing templates entirely (described further down).
Templates can 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 the recommended way for extensions to modify the user interface of Bugzilla.
There is no list of template hooks like there is for standard code hooks. To find what places in the user interface can be hooked, search 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. (A later section in this document explains how to use that name).
For example, if you see Hook.process("additional_header"), that means the name of the hook is additional_header.
To extend templates in your extension using template hooks, you put files into the template/en/default/hook directory of your extension. So, if you had an extension called "Foo", your template extensions would go into extensions/Foo/template/en/default/hook/.
(Note that the base template/en/default/hook directory in Bugzilla itself also works, although you would never use that for an extension that you intended to distribute.)
The files that go into this directory have a certain name, based on the name of the template that is being hooked, and the name of the hook. For example, let's imagine that you have an extension named "Foo", and you want to use the additional_header hook in template/en/default/global/header.html.tmpl. Your code would go into extensions/Foo/template/en/default/hook/global/header-additional_header.html.tmpl. Any code you put into that file will happen at the point that Hook.process("additional_header") is called in template/en/default/global/header.html.tmpl.
As you can see, template extension file names follow a pattern. The pattern looks like:
<templates>/hook/<template path>/<template name>-<hook name>.<template type>.tmpl
This is the full path to the template directory, like extensions/Foo/template/en/default. This works much like normal templates do, in the sense that template extensions in custom override template extensions in default for your extension, templates for different languages can be supplied, etc. Template extensions are searched for and run in the order described in "template_include_path" in Bugzilla::Install::Util.
The difference between normal templates and template hooks is that hooks will be run for every extension, whereas for normal templates, Bugzilla just takes the first one it finds and stops searching. So while a template extension in the custom directory may override the same-named template extension in the default directory within your Bugzilla extension, it will not override the same-named template extension in the default directory of another Bugzilla extension.
This is the part of the path (excluding the filename) that comes after template/en/default/ in a template's path. So, for template/en/default/global/header.html.tmpl, this would simply be global.
This is the file name of the template, before the .html.tmpl part. So, for template/en/default/global/header.html.tmpl, this would be header.
This is the name of the hook--what you saw in Hook.process inside of the template you want to hook. In our example, this is additional_header.
This is what comes after the template name but before .tmpl in the template's path. In most cases this is html, but sometimes it's none, txt, js, or various other formats, indicating what type of output the template has.
Adding new template hooks is just like adding code hooks (see "Adding New Hooks To Bugzilla") except that you don't have to document them, and including example code is optional.
Sometimes you don't want to extend a template, you just want to replace it entirely with your extension's template, or you want to add an entirely new template to Bugzilla for your extension to use.
To replace the template/en/default/global/banner.html.tmpl template 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 excludes hook/, and the template is named exactly like the standard Bugzilla template.
You can also use this method to add entirely new templates. If you have an extension named "Foo", and you add a file named extensions/Foo/template/en/default/foo/bar.html.tmpl, you can load that in your code using $template->process('foo/bar.html.tmpl').
You should never override an existing Bugzilla template in an extension that you plan to distribute to others, because only one extension can override any given template, and which extension will "win" that war if there are multiple extensions installed is totally undefined.
However, adding new templates in an extension that you want to distribute is fine, though you have to be careful about how you name them, because any templates with an identical path and name (say, both called global/stuff.html.tmpl) will conflict. The usual way to work around this is to put all your custom templates into a template path that's named after your extension (since the name of your extension has to be unique anyway). So if your extension was named Foo, your custom templates would go into extensions/Foo/template/en/default/foo/. The only time that doesn't work is with the page_before_template extension, in which case your templates should probably be in a directory like extensions/Foo/template/en/default/page/foo/ so as not to conflict with other pages that other extensions might add.
If you include CSS, JavaScript, and images in your extension that are served directly to the user (that is, they're not read by a script and then printed--they're just linked directly in your HTML), they should go into the web/ subdirectory of your extension.
So, for example, if you had a CSS file called style.css and your extension was called Foo, your file would go into extensions/Foo/web/style.css.
Documentation goes in extensions/Foo/docs/en/rst/, if it's in English, or change "en" to something else if it's not. The user documentation index file must be called index-user.rst; the admin documentation must be called index-admin.rst. These will end up in the User Guide and the Administration Guide respectively. Both documentation types are optional. You can use various Sphinx constructs such as :toctree: or :include: to include further reST files if you need more than one page of docs.
When documenting extensions to the Bugzilla API, if your extension provides them, the index file would be extensions/Foo/docs/en/rst/api/v1/index.rst. When and if your API has more than one version, increment the version number. These docs will get included in the WebService API Reference.
If you want your extension to be totally ignored by Bugzilla (it will not be compiled or seen to exist at all), then create a file called disabled in your extension's directory. (If your extension is just a file, like extensions/Foo.pm, you cannot use this method to disable your extension, and will just have to remove it from the directory if you want to totally disable it.) Note that if you are running under mod_perl, you may have to restart your web server for this to take effect.
If you want your extension to be compiled and have checksetup check for its module pre-requisites, but you don't want the module to be used by Bugzilla, then you should make your extension's "enabled" method return 0 or some false value.
If you've made an extension and you want to publish it, the first thing you'll want to do is package up your extension's code and then put a link to it in the appropriate section of http://wiki.mozilla.org/Bugzilla:Addons.
If you want a centralized distribution point that makes it easy for Bugzilla users to install your extension, it is possible to distribute your Bugzilla Extension through CPAN.
The details of making a standard CPAN module are too much to go into here, but a lot of it is covered in perlmodlib and on http://www.cpan.org/ among other places.
When you distribute your extension via CPAN, your Extension.pm should simply install itself as Bugzilla/Extension/Foo.pm, where Foo is the name of your module. You do not need a separate Config.pm file, because CPAN itself will handle installing the prerequisites of your module, so Bugzilla doesn't have to worry about it.
If your extension is /usr/lib/perl5/Bugzilla/Extension/Foo.pm, then Bugzilla will look for templates in the directory /usr/lib/perl5/Bugzilla/Extension/Foo/template/.
You can change this behavior by overriding the "template_dir" or "package_dir" methods described lower down in this document.
There is a file named data/extensions/additional in Bugzilla. This is a plain-text file. Each line is the name of a module, like Bugzilla::Extension::Foo. In addition to the extensions in the extensions/ directory, each module listed in this file will be loaded as a Bugzilla Extension whenever Bugzilla loads or uses extensions.
If you are an extension author and you'd like some assistance from other extension authors or the Bugzilla development team, you can use the normal support channels described at http://www.bugzilla.org/support/.
In addition to NAME, there are some other constants you might want to define:
$VERSIONThis should be a string that describes what version of your extension this is. Something like 1.0, 1.3.4 or a similar string.
There are no particular restrictions on the format of version numbers, but you should probably keep them to just numbers and periods, in the interest of other software that parses version numbers.
By default, this will be undef if you don't define it.
In addition to hooks, there are a few methods that your extension can define to modify its behavior, if you want:
These methods are called on your extension's class. (Like Bugzilla::Extension::Foo->some_method).
newOnce every request, this method is called on your extension in order to create an "instance" of it. (Extensions are treated like objects--they are instantiated once per request in Bugzilla, and then methods are called on the object.)
These are called on an instantiated Extension object.
enabledThis should return 1 if this extension's hook code should be run by Bugzilla, and 0 otherwise.
package_dirThis returns the directory that your extension is located in.
If this is an extension that was installed via CPAN, the directory will be the path to Bugzilla/Extension/Foo/, if Foo.pm is the name of your extension.
If you want to override this method, and you have a Config.pm, you must override this method in Config.pm.
template_dirThe directory that your package's templates are in.
This defaults to the template subdirectory of the "package_dir".
If you want to override this method, and you have a Config.pm, you must override this method in Config.pm.
web_dirThe directory that your package's web related files are in, such as css and javascript.
This defaults to the web subdirectory of the "package_dir".
If you want to override this method, and you have a Config.pm, you must override this method in Config.pm.
lib_dirThe directory where your extension's libraries are.
This defaults to the lib subdirectory of the "package_dir".
If you want to override this method, and you have a Config.pm, you must override this method in Config.pm.
These are used internally by Bugzilla to load and set up extensions. If you are an extension author, you don't need to care about these.
loadTakes two arguments, the path to Extension.pm and the path to Config.pm, for an extension. Loads the extension's code packages into memory using require, does some sanity-checking on the extension, and returns the package name of the loaded extension.
load_allCalls "load" for every enabled extension installed into Bugzilla, and returns an arrayref of all the package names that were loaded.