454 lines
11 KiB
HTML
454 lines
11 KiB
HTML
<HTML
|
|
><HEAD
|
|
><TITLE
|
|
>Template Hooks</TITLE
|
|
><META
|
|
NAME="GENERATOR"
|
|
CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
|
|
"><LINK
|
|
REL="HOME"
|
|
TITLE="The Bugzilla Guide - 2.17.7
|
|
Development Release"
|
|
HREF="index.html"><LINK
|
|
REL="UP"
|
|
TITLE="Customising 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 - 2.17.7
|
|
Development 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 4. Customising 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"
|
|
></A
|
|
>4.2. Template Hooks</H1
|
|
><P
|
|
> Template hooks are a way for extensions to Bugzilla to insert code
|
|
into the standard Bugzilla templates without modifying the template files
|
|
themselves. The hooks mechanism defines a consistent API for extending
|
|
the standard templates 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.
|
|
</P
|
|
><P
|
|
> A template hook is just a named place in a standard template file
|
|
where extension template files for that hook get processed. Each hook
|
|
has a corresponding directory in the Bugzilla directory tree. Hooking an
|
|
extension template to a hook is as simple as putting the extension file
|
|
into the hook's directory. When Bugzilla processes the standard template
|
|
and reaches the hook, it will process all extension templates in the
|
|
hook's directory. The hooks themselves can be added into any standard
|
|
template upon request by extension authors.
|
|
</P
|
|
><P
|
|
> To use hooks to extend a Bugzilla template, first make sure there is
|
|
a hook at the appropriate place within the template you want to extend.
|
|
Hooks appear in the standard Bugzilla templates as a single directive
|
|
in the format
|
|
<TT
|
|
CLASS="literal"
|
|
>[% Hook.process("<TT
|
|
CLASS="varname"
|
|
>name</TT
|
|
>") %]</TT
|
|
>,
|
|
where <TT
|
|
CLASS="varname"
|
|
>name</TT
|
|
> is the unique (within that template)
|
|
name of the hook.
|
|
</P
|
|
><P
|
|
> If you aren't sure which template 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 <TT
|
|
CLASS="methodname"
|
|
>Hook.process</TT
|
|
> or browse
|
|
the directory tree in
|
|
<TT
|
|
CLASS="filename"
|
|
>BUGZILLA_ROOT/template/en/extension/hook/</TT
|
|
>,
|
|
which contains a directory for each hook in the following location:
|
|
</P
|
|
><P
|
|
> <TT
|
|
CLASS="filename"
|
|
>BUGZILLA_ROOT/template/en/extension/hook/PATH_TO_STANDARD_TEMPLATE/STANDARD_TEMPLATE_NAME/HOOK_NAME/</TT
|
|
>
|
|
</P
|
|
><P
|
|
> If there is no hook at the appropriate place within the Bugzilla 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 template for which you are requesting a hook;</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
> where in the template you would like the hook to be placed
|
|
(line number/position for latest version of template 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, check the new version
|
|
of the template into CVS, and create the corresponding directory in
|
|
<TT
|
|
CLASS="filename"
|
|
>BUGZILLA_ROOT/template/en/extension/hook/</TT
|
|
>.
|
|
</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 template to the directory within the Bugzilla
|
|
directory tree corresponding to the hook.
|
|
</P
|
|
><P
|
|
> That's it! Now, when the standard template containing the hook
|
|
is processed, your extension template 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.groups.editkeywords %]
|
|
[% Hook.process("edit") %]
|
|
...</PRE
|
|
></FONT
|
|
></TD
|
|
></TR
|
|
></TABLE
|
|
><P
|
|
> The corresponding directory for this hook is
|
|
<TT
|
|
CLASS="filename"
|
|
>BUGZILLA_ROOT/template/en/extension/hook/global/useful-links.html.tmpl/edit/</TT
|
|
>.
|
|
</P
|
|
><P
|
|
> You put a template named
|
|
<TT
|
|
CLASS="filename"
|
|
>projman-edit-projects.html.tmpl</TT
|
|
>
|
|
into that directory with the following content:
|
|
</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.groups.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
|
|
> Notes:
|
|
</P
|
|
><P
|
|
></P
|
|
><UL
|
|
><LI
|
|
><P
|
|
> You may want to prefix your extension template names
|
|
with the name of your extension, e.g.
|
|
<TT
|
|
CLASS="filename"
|
|
>projman-foo.html.tmpl</TT
|
|
>,
|
|
so they do not conflict with the names of templates installed by
|
|
other extensions.
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> If your extension includes entirely new templates in addition to
|
|
extensions of standard templates, it should install those new
|
|
templates into an extension-specific subdirectory of the
|
|
<TT
|
|
CLASS="filename"
|
|
>BUGZILLA_ROOT/template/en/extension/</TT
|
|
>
|
|
directory. The <TT
|
|
CLASS="filename"
|
|
>extension/</TT
|
|
> directory, like the
|
|
<TT
|
|
CLASS="filename"
|
|
>default/</TT
|
|
> and <TT
|
|
CLASS="filename"
|
|
>custom/</TT
|
|
>
|
|
directories, is 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"
|
|
>extension/</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 extension templates can override standard templates,
|
|
but installation-specific templates override both.
|
|
</P
|
|
><P
|
|
> Note that overriding standard templates with extension templates
|
|
gives you great power but also makes upgrading an installation harder.
|
|
As with custom templates, we recommend using this functionality
|
|
sparingly and only when absolutely necessary.
|
|
</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
> Installation customizers can also take advantage of hooks when adding
|
|
code to a Bugzilla template. To do so, create directories in
|
|
<TT
|
|
CLASS="filename"
|
|
>BUGZILLA_ROOT/template/en/custom/hook/</TT
|
|
>
|
|
equivalent to the directories in
|
|
<TT
|
|
CLASS="filename"
|
|
>BUGZILLA_ROOT/template/en/extension/hook/</TT
|
|
>
|
|
for the hooks you want to use, then place your customization templates
|
|
into those directories.
|
|
</P
|
|
><P
|
|
> Obviously this method of customizing Bugzilla only lets you add code
|
|
to the standard 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
|
|
> |