5.7.31. Bugzilla::Extension¶
5.7.31.1. NAME¶
Bugzilla::Extension - Base class for Bugzilla Extensions.
5.7.31.2. SYNOPSIS¶
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|/Template Hooks would go into extensions/Foo/template/en/default/hook/.
5.7.31.3. DESCRIPTION¶
This is the base class for all Bugzilla extensions.
5.7.31.4. WRITING 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|https://wiki.mozilla.org/Bugzilla:Extension_Notes with additional HOWTOs, tips and tricks.
Using extensions/create.pl¶
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.
Example Extension¶
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.
Where Extension Code Goes¶
Extension code lives under the extensions/ directory in Bugzilla.
There are two ways to write extensions:
1
If your extension will have only code and no templates or other files, you can create a simple
.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.
2
If you plan for your extension to have templates and other files, you can create a whole directory for your extension, and the main extension code would go into a file called Extension.pm in that 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/Extension.pm.
The Extension NAME
.¶
The "name" of an extension shows up in several places:
1
The name of the package:
package Bugzilla::Extension::Foo;
2
In a
NAME
constant that must be defined for every extension:
use constant NAME => 'Foo';
3
At the very end of the file:
__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.
Hooks¶
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 Bugzilla/input_params.
Adding New Hooks To 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 Your Extension Requires Certain Perl Modules¶
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
Bugzilla::Install::Requirements/REQUIRED_MODULES.
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 Bugzilla::Install::Requirements/OPTIONAL_MODULES.
If Your Extension Needs Certain Modules In Order To Compile¶
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.pmcontaining 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.pmwill 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.
Libraries¶
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.
Templates¶
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
Bugzilla::Install::Util/template_include_path.
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).
Template Hooks¶
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.
Which Templates Can Be Hooked¶
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
.
Where Template Hooks Go¶
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
<templates>
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 indefault
for your extension, templates for different languages can be supplied, etc. Template extensions are searched for and run in the order described in Bugzilla::Install::Util/template_include_path.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 thedefault
directory within your Bugzilla extension, it will not override the same-named template extension in thedefault
directory of another Bugzilla extension.
<template path>
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 beglobal
.
<template name>
This is the file name of the template, before the.html.tmpl
part. So, for template/en/default/global/header.html.tmpl, this would beheader
.
<hook name>
This is the name of the hook--what you saw inHook.process
inside of the template you want to hook. In our example, this isadditional_header
.
<template type>
This is what comes after the template name but before.tmpl
in the template's path. In most cases this ishtml
, but sometimes it'snone
,txt
,js
, or various other formats, indicating what type of output the template has.
Adding New Template Hooks to Bugzilla¶
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.
Overriding Existing Templates¶
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')
.
A Warning About Extensions That You Want To Distribute¶
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.
CSS, JavaScript, and Images¶
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.
Documenting Extensions¶
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.
Disabling Your Extension¶
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.
5.7.31.5. DISTRIBUTING EXTENSIONS¶
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.
Distributing on CPAN¶
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.pmshould 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.
Templates in extensions distributed on CPAN¶
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.
Using an extension distributed on CPAN¶
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.
5.7.31.6. GETTING HELP WITH WRITING 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/.
5.7.31.7. ADDITIONAL CONSTANTS¶
In addition to NAME
, there are some other constants you might
want to define:
$VERSION
¶
This 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.
5.7.31.8. SUBCLASS METHODS¶
In addition to hooks, there are a few methods that your extension can define to modify its behavior, if you want:
Class Methods¶
These methods are called on your extension's class. (Like
Bugzilla::Extension::Foo->some_method
).
new
¶
Once 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.)
Instance Methods¶
These are called on an instantiated Extension object.
enabled
¶
This should return 1
if this extension's hook code should be run
by Bugzilla, and 0
otherwise.
package_dir
¶
This 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_dir
¶
The 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_dir
¶
The 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_dir
¶
The 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.
5.7.31.9. BUGZILLA::EXTENSION CLASS METHODS¶
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.
load
¶
Takes 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.