Bugzilla:Writing Extensions: Difference between revisions

From MozillaWiki
Jump to navigation Jump to search
(Make the note at the top bold now that 3.6 is actually released.)
(Replaced content with "See http://bugzilla.readthedocs.org/en/latest/integrating/extensions.html .")
 
Line 1: Line 1:
'''Note: These are the instructions for versions of Bugzilla before 3.6. For 3.6 and later, see the [http://www.bugzilla.org/docs/tip/en/html/api/Bugzilla/Extension.html 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.'''
See http://bugzilla.readthedocs.org/en/latest/integrating/extensions.html .
 
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 [http://www.bugzilla.org/docs/tip/en/html/api/Bugzilla/Hook.html a system of code hooks] that allow us to make code "happen" at different times on different pages in Bugzilla.
 
The [http://www.bugzilla.org/docs/tip/en/html/api/Bugzilla/Hook.html#DESCRIPTION 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 [http://mxr.mozilla.org/mozilla/source/webtools/bugzilla/extensions/example/code/ ''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 [http://template-toolkit.org/ 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 [[Bugzilla:Developers|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 [http://www.bugzilla.org/docs/tip/en/html/api/Bugzilla/Install/Util.html 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 [[Bugzilla:Communicate|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.

Latest revision as of 16:18, 16 February 2015

See http://bugzilla.readthedocs.org/en/latest/integrating/extensions.html .

Retrieved from "https://wiki.allizom.org/index.php?title=Bugzilla:Writing_Extensions&oldid=1056328"