528 lines
13 KiB
HTML
528 lines
13 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
|
|
<HTML
|
|
><HEAD
|
|
><TITLE
|
|
>The Bugzilla Extension Mechanism</TITLE
|
|
><META
|
|
NAME="GENERATOR"
|
|
CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK
|
|
REL="HOME"
|
|
TITLE="The Bugzilla Guide - 3.4.2
|
|
Release"
|
|
HREF="index.html"><LINK
|
|
REL="UP"
|
|
TITLE="Customizing Bugzilla"
|
|
HREF="customization.html"><LINK
|
|
REL="PREVIOUS"
|
|
TITLE="Template Customization"
|
|
HREF="cust-templates.html"><LINK
|
|
REL="NEXT"
|
|
TITLE="Customizing Who Can Change What"
|
|
HREF="cust-change-permissions.html"></HEAD
|
|
><BODY
|
|
CLASS="section"
|
|
BGCOLOR="#FFFFFF"
|
|
TEXT="#000000"
|
|
LINK="#0000FF"
|
|
VLINK="#840084"
|
|
ALINK="#0000FF"
|
|
><DIV
|
|
CLASS="NAVHEADER"
|
|
><TABLE
|
|
SUMMARY="Header navigation table"
|
|
WIDTH="100%"
|
|
BORDER="0"
|
|
CELLPADDING="0"
|
|
CELLSPACING="0"
|
|
><TR
|
|
><TH
|
|
COLSPAN="3"
|
|
ALIGN="center"
|
|
>The Bugzilla Guide - 3.4.2
|
|
Release</TH
|
|
></TR
|
|
><TR
|
|
><TD
|
|
WIDTH="10%"
|
|
ALIGN="left"
|
|
VALIGN="bottom"
|
|
><A
|
|
HREF="cust-templates.html"
|
|
ACCESSKEY="P"
|
|
>Prev</A
|
|
></TD
|
|
><TD
|
|
WIDTH="80%"
|
|
ALIGN="center"
|
|
VALIGN="bottom"
|
|
>Chapter 6. Customizing Bugzilla</TD
|
|
><TD
|
|
WIDTH="10%"
|
|
ALIGN="right"
|
|
VALIGN="bottom"
|
|
><A
|
|
HREF="cust-change-permissions.html"
|
|
ACCESSKEY="N"
|
|
>Next</A
|
|
></TD
|
|
></TR
|
|
></TABLE
|
|
><HR
|
|
ALIGN="LEFT"
|
|
WIDTH="100%"></DIV
|
|
><DIV
|
|
CLASS="section"
|
|
><H1
|
|
CLASS="section"
|
|
><A
|
|
NAME="cust-hooks"
|
|
>6.3. The Bugzilla Extension Mechanism</A
|
|
></H1
|
|
><DIV
|
|
CLASS="warning"
|
|
><P
|
|
></P
|
|
><TABLE
|
|
CLASS="warning"
|
|
WIDTH="100%"
|
|
BORDER="0"
|
|
><TR
|
|
><TD
|
|
WIDTH="25"
|
|
ALIGN="CENTER"
|
|
VALIGN="TOP"
|
|
><IMG
|
|
SRC="../images/warning.gif"
|
|
HSPACE="5"
|
|
ALT="Warning"></TD
|
|
><TD
|
|
ALIGN="LEFT"
|
|
VALIGN="TOP"
|
|
><P
|
|
> Note that the below paths are inconsistent and confusing. They will
|
|
likely be changed in Bugzilla 4.0.
|
|
</P
|
|
></TD
|
|
></TR
|
|
></TABLE
|
|
></DIV
|
|
><P
|
|
> Extensions are a way for extensions to Bugzilla to insert code
|
|
into the standard Bugzilla templates and source files
|
|
without modifying these files themselves. The extension mechanism
|
|
defines a consistent API for extending the standard templates and source files
|
|
in a way that cleanly separates standard code from extension code.
|
|
Hooks reduce merge conflicts and make it easier to write extensions that work
|
|
across multiple versions of Bugzilla, making upgrading a Bugzilla installation
|
|
with installed extensions easier. Furthermore, they make it easy to install
|
|
and remove extensions as each extension is nothing more than a
|
|
simple directory structure.
|
|
</P
|
|
><P
|
|
> There are two main types of hooks: code hooks and template hooks. Code
|
|
hooks allow extensions to invoke code at specific points in various
|
|
source files, while template hooks allow extensions to add elements to
|
|
the Bugzilla user interface.
|
|
</P
|
|
><P
|
|
> A hook is just a named place in a standard source or template file
|
|
where extension source code or template files for that hook get processed.
|
|
Each extension has a corresponding directory in the Bugzilla directory
|
|
tree (<TT
|
|
CLASS="filename"
|
|
>BUGZILLA_ROOT/extensions/extension_name</TT
|
|
>). Hooking
|
|
an extension source file or template to a hook is as simple as putting
|
|
the extension file into extension's template or code directory.
|
|
When Bugzilla processes the source file or template and reaches the hook,
|
|
it will process all extension files in the hook's directory.
|
|
The hooks themselves can be added into any source file or standard template
|
|
upon request by extension authors.
|
|
</P
|
|
><P
|
|
> To use hooks to extend Bugzilla, first make sure there is
|
|
a hook at the appropriate place within the source file or template you
|
|
want to extend. The exact appearance of a hook depends on if the hook
|
|
is a code hook or a template hook.
|
|
</P
|
|
><P
|
|
> Code hooks appear in Bugzilla source files as a single method call
|
|
in the format <TT
|
|
CLASS="literal"
|
|
>Bugzilla::Hook->process("<CODE
|
|
CLASS="varname"
|
|
>name</CODE
|
|
>");</TT
|
|
>.
|
|
For instance, <TT
|
|
CLASS="filename"
|
|
>enter_bug.cgi</TT
|
|
> may invoke the hook
|
|
"<CODE
|
|
CLASS="varname"
|
|
>enter_bug-entrydefaultvars</CODE
|
|
>". Thus, a source file at
|
|
<TT
|
|
CLASS="filename"
|
|
>BUGZILLA_ROOT/extensions/EXTENSION_NAME/code/enter_bug-entrydefaultvars.pl</TT
|
|
>
|
|
will be automatically invoked when the code hook is reached.
|
|
</P
|
|
><P
|
|
>
|
|
Template hooks appear in the standard Bugzilla templates as a
|
|
single directive in the format
|
|
<TT
|
|
CLASS="literal"
|
|
>[% Hook.process("<CODE
|
|
CLASS="varname"
|
|
>name</CODE
|
|
>") %]</TT
|
|
>,
|
|
where <CODE
|
|
CLASS="varname"
|
|
>name</CODE
|
|
> is the unique name of the hook.
|
|
</P
|
|
><P
|
|
> If you aren't sure what you want to extend or just want to browse the
|
|
available hooks, either use your favorite multi-file search
|
|
tool (e.g. <B
|
|
CLASS="command"
|
|
>grep</B
|
|
>) to search the standard templates
|
|
for occurrences of <CODE
|
|
CLASS="methodname"
|
|
>Hook.process</CODE
|
|
> or the source
|
|
files for occurrences of <CODE
|
|
CLASS="methodname"
|
|
>Bugzilla::Hook::process</CODE
|
|
>.
|
|
</P
|
|
><P
|
|
> If there is no hook at the appropriate place within the Bugzilla
|
|
source file or template you want to extend,
|
|
<A
|
|
HREF="http://bugzilla.mozilla.org/enter_bug.cgi?product=Bugzilla&component=User%20Interface"
|
|
TARGET="_top"
|
|
>file
|
|
a bug requesting one</A
|
|
>, specifying:
|
|
</P
|
|
><P
|
|
></P
|
|
><TABLE
|
|
BORDER="0"
|
|
><TBODY
|
|
><TR
|
|
><TD
|
|
>the source or template file for which you are
|
|
requesting a hook;</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
> where in the file you would like the hook to be placed
|
|
(line number/position for latest version of the file in CVS
|
|
or description of location);
|
|
</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
>the purpose of the hook;</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
>a link to information about your extension, if any.</TD
|
|
></TR
|
|
></TBODY
|
|
></TABLE
|
|
><P
|
|
></P
|
|
><P
|
|
> The Bugzilla reviewers will promptly review each hook request,
|
|
name the hook, add it to the template or source file, and check
|
|
the new version of the template into CVS.
|
|
</P
|
|
><P
|
|
> You may optionally attach a patch to the bug which implements the hook
|
|
and check it in yourself after receiving approval from a Bugzilla
|
|
reviewer. The developers may suggest changes to the location of the
|
|
hook based on their analysis of your needs or so the hook can satisfy
|
|
the needs of multiple extensions, but the process of getting hooks
|
|
approved and checked in is not as stringent as the process for general
|
|
changes to Bugzilla, and any extension, whether released or still in
|
|
development, can have hooks added to meet their needs.
|
|
</P
|
|
><P
|
|
> After making sure the hook you need exists (or getting it added if not),
|
|
add your extension to the directory within the Bugzilla
|
|
extensions tree corresponding to the hook.
|
|
</P
|
|
><P
|
|
> That's it! Now, when the source file or template containing the hook
|
|
is processed, your extension file will be processed at the point
|
|
where the hook appears.
|
|
</P
|
|
><P
|
|
> For example, let's say you have an extension named Projman that adds
|
|
project management capabilities to Bugzilla. Projman has an
|
|
administration interface <TT
|
|
CLASS="filename"
|
|
>edit-projects.cgi</TT
|
|
>,
|
|
and you want to add a link to it into the navigation bar at the bottom
|
|
of every Bugzilla page for those users who are authorized
|
|
to administer projects.
|
|
</P
|
|
><P
|
|
> The navigation bar is generated by the template file
|
|
<TT
|
|
CLASS="filename"
|
|
>useful-links.html.tmpl</TT
|
|
>, which is located in
|
|
the <TT
|
|
CLASS="filename"
|
|
>global/</TT
|
|
> subdirectory on the standard Bugzilla
|
|
template path
|
|
<TT
|
|
CLASS="filename"
|
|
>BUGZILLA_ROOT/template/en/default/</TT
|
|
>.
|
|
Looking in <TT
|
|
CLASS="filename"
|
|
>useful-links.html.tmpl</TT
|
|
>, you find
|
|
the following hook at the end of the list of standard Bugzilla
|
|
administration links:
|
|
</P
|
|
><TABLE
|
|
BORDER="0"
|
|
BGCOLOR="#E0E0E0"
|
|
WIDTH="100%"
|
|
><TR
|
|
><TD
|
|
><FONT
|
|
COLOR="#000000"
|
|
><PRE
|
|
CLASS="programlisting"
|
|
>...
|
|
[% ', <a href="editkeywords.cgi">keywords</a>'
|
|
IF user.in_group('editkeywords') %]
|
|
[% Hook.process("edit") %]
|
|
...</PRE
|
|
></FONT
|
|
></TD
|
|
></TR
|
|
></TABLE
|
|
><P
|
|
> The corresponding extension file for this hook is
|
|
<TT
|
|
CLASS="filename"
|
|
>BUGZILLA_ROOT/extensions/projman/template/en/global/useful-links-edit.html.tmpl</TT
|
|
>.
|
|
You then create that template file and add the following constant:
|
|
</P
|
|
><TABLE
|
|
BORDER="0"
|
|
BGCOLOR="#E0E0E0"
|
|
WIDTH="100%"
|
|
><TR
|
|
><TD
|
|
><FONT
|
|
COLOR="#000000"
|
|
><PRE
|
|
CLASS="programlisting"
|
|
>...[% ', <a href="edit-projects.cgi">projects</a>' IF user.in_group('projman_admins') %]</PRE
|
|
></FONT
|
|
></TD
|
|
></TR
|
|
></TABLE
|
|
><P
|
|
> Voila! The link now appears after the other administration links in the
|
|
navigation bar for users in the <TT
|
|
CLASS="literal"
|
|
>projman_admins</TT
|
|
> group.
|
|
</P
|
|
><P
|
|
> Now, let us say your extension adds a custom "project_manager" field
|
|
to enter_bug.cgi. You want to modify the CGI script to set the default
|
|
project manager to be productname@company.com. Looking at
|
|
<TT
|
|
CLASS="filename"
|
|
>enter_bug.cgi</TT
|
|
>, you see the enter_bug-entrydefaultvars
|
|
hook near the bottom of the file before the default form values are set.
|
|
The corresponding extension source file for this hook is located at
|
|
<TT
|
|
CLASS="filename"
|
|
>BUGZILLA_ROOT/extensions/projman/code/enter_bug-entrydefaultvars.pl</TT
|
|
>.
|
|
You then create that file and add the following:
|
|
</P
|
|
><TABLE
|
|
BORDER="0"
|
|
BGCOLOR="#E0E0E0"
|
|
WIDTH="100%"
|
|
><TR
|
|
><TD
|
|
><FONT
|
|
COLOR="#000000"
|
|
><PRE
|
|
CLASS="programlisting"
|
|
>$default{'project_manager'} = $product.'@company.com';</PRE
|
|
></FONT
|
|
></TD
|
|
></TR
|
|
></TABLE
|
|
><P
|
|
> This code will be invoked whenever enter_bug.cgi is executed.
|
|
Assuming that the rest of the customization was completed (e.g. the
|
|
custom field was added to the enter_bug template and the required hooks
|
|
were used in process_bug.cgi), the new field will now have this
|
|
default value.
|
|
</P
|
|
><P
|
|
> Notes:
|
|
</P
|
|
><P
|
|
></P
|
|
><UL
|
|
><LI
|
|
><P
|
|
> If your extension includes entirely new templates in addition to
|
|
extensions of standard templates, it should store those new
|
|
templates in its
|
|
<TT
|
|
CLASS="filename"
|
|
>BUGZILLA_ROOT/extensions/template/en/</TT
|
|
>
|
|
directory. Extension template directories, like the
|
|
<TT
|
|
CLASS="filename"
|
|
>default/</TT
|
|
> and <TT
|
|
CLASS="filename"
|
|
>custom/</TT
|
|
>
|
|
directories, are part of the template search path, so putting templates
|
|
there enables them to be found by the template processor.
|
|
</P
|
|
><P
|
|
> The template processor looks for templates first in the
|
|
<TT
|
|
CLASS="filename"
|
|
>custom/</TT
|
|
> directory (i.e. templates added by the
|
|
specific installation), then in the <TT
|
|
CLASS="filename"
|
|
>extensions/</TT
|
|
>
|
|
directory (i.e. templates added by extensions), and finally in the
|
|
<TT
|
|
CLASS="filename"
|
|
>default/</TT
|
|
> directory (i.e. the standard Bugzilla
|
|
templates). Thus, installation-specific templates override both
|
|
default and extension templates.
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> If you are looking to customize Bugzilla, you can also take advantage
|
|
of template hooks. To do so, create a directory in
|
|
<TT
|
|
CLASS="filename"
|
|
>BUGZILLA_ROOT/template/en/custom/hook/</TT
|
|
>
|
|
that corresponds to the hook you wish to use, then place your
|
|
customization templates into those directories. For example,
|
|
if you wanted to use the hook "end" in
|
|
<TT
|
|
CLASS="filename"
|
|
>global/useful-links.html.tmpl</TT
|
|
>, you would
|
|
create the directory <TT
|
|
CLASS="filename"
|
|
>BUGZILLA_ROOT/template/en/custom/hook/
|
|
global/useful-links.html.tmpl/end/</TT
|
|
> and add your customization
|
|
template to this directory.
|
|
</P
|
|
><P
|
|
> Obviously this method of customizing Bugzilla only lets you add code
|
|
to the standard source files and templates; you cannot change the
|
|
existing code. Nevertheless, for those customizations that only add
|
|
code, this method can reduce conflicts when merging changes,
|
|
making upgrading your customized Bugzilla installation easier.
|
|
</P
|
|
></LI
|
|
></UL
|
|
></DIV
|
|
><DIV
|
|
CLASS="NAVFOOTER"
|
|
><HR
|
|
ALIGN="LEFT"
|
|
WIDTH="100%"><TABLE
|
|
SUMMARY="Footer navigation table"
|
|
WIDTH="100%"
|
|
BORDER="0"
|
|
CELLPADDING="0"
|
|
CELLSPACING="0"
|
|
><TR
|
|
><TD
|
|
WIDTH="33%"
|
|
ALIGN="left"
|
|
VALIGN="top"
|
|
><A
|
|
HREF="cust-templates.html"
|
|
ACCESSKEY="P"
|
|
>Prev</A
|
|
></TD
|
|
><TD
|
|
WIDTH="34%"
|
|
ALIGN="center"
|
|
VALIGN="top"
|
|
><A
|
|
HREF="index.html"
|
|
ACCESSKEY="H"
|
|
>Home</A
|
|
></TD
|
|
><TD
|
|
WIDTH="33%"
|
|
ALIGN="right"
|
|
VALIGN="top"
|
|
><A
|
|
HREF="cust-change-permissions.html"
|
|
ACCESSKEY="N"
|
|
>Next</A
|
|
></TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
WIDTH="33%"
|
|
ALIGN="left"
|
|
VALIGN="top"
|
|
>Template Customization</TD
|
|
><TD
|
|
WIDTH="34%"
|
|
ALIGN="center"
|
|
VALIGN="top"
|
|
><A
|
|
HREF="customization.html"
|
|
ACCESSKEY="U"
|
|
>Up</A
|
|
></TD
|
|
><TD
|
|
WIDTH="33%"
|
|
ALIGN="right"
|
|
VALIGN="top"
|
|
>Customizing Who Can Change What</TD
|
|
></TR
|
|
></TABLE
|
|
></DIV
|
|
></BODY
|
|
></HTML
|
|
> |