<<

# Bugzilla::Extension

- NAME
- SYNOPSIS
- DESCRIPTION
- WRITING EXTENSIONS
  - Using extensions/create.pl
  - Example Extension
  - Where Extension Code Goes
  - The Extension NAME.
  - Hooks
    - Adding New Hooks To Bugzilla
  - If Your Extension Requires Certain Perl Modules
    - If Your Extension Needs Certain Modules In Order To Compile
  - Libraries
  - Templates
  - Template Hooks
    - Which Templates Can Be Hooked
    - Where Template Hooks Go
    - Adding New Template Hooks to Bugzilla
  - Overriding Existing Templates
    - A Warning About Extensions That You Want To Distribute
  - Disabling Your Extension
- DISTRIBUTING EXTENSIONS
  - Distributing on CPAN
    - Templates in extensions distributed on CPAN
    - Using an extension distributed on CPAN
- GETTING HELP WITH WRITING EXTENSIONS
- ADDITIONAL CONSTANTS
  - $VERSION
- SUBCLASS METHODS
  - Class Methods
    - new
  - Instance Methods
    - enabled
    - package_dir
    - template_dir
    - lib_dir
- BUGZILLA::EXTENSION CLASS METHODS
  - load
  - load_all

# NAME

Bugzilla::Extension - Base class for Bugzilla Extensions.

# SYNOPSIS

The following would be in extensions/Foo/Extension.pm or extensions/Foo.pm:

     package Bugzilla::Extension::Foo
     use strict;
     use base 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/.

# DESCRIPTION

This is the base class for all Bugzilla extensions.

# 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.

## 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 "input_params" in Bugzilla.

### 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 "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 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.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.

## 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 "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).

## 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 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.

<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 be `global`.

<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 be `header`.

<hook name>

  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`.

<template type>

  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 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.

## 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.

# 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.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.

### 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.

# 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/.

# 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.

# 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.

### `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.

# 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.

## `load_all`

Calls "load" for every enabled extension installed into Bugzilla, and returns an arrayref of all the package names that were loaded.

<<