5.2. Template Hooks

Warning

Template Hooks require Template Toolkit version 2.12 or above, or the application of a patch. See bug 239112 for details.

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.

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.

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 [% Hook.process("name") %], where name is the unique (within that template) name of the hook.

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. grep) to search the standard templates for occurrences of Hook.process or browse the directory tree in BUGZILLA_ROOT/template/en/extension/hook/, which contains a directory for each hook in the following location:

BUGZILLA_ROOT/template/en/extension/hook/PATH_TO_STANDARD_TEMPLATE/STANDARD_TEMPLATE_NAME/HOOK_NAME/

If there is no hook at the appropriate place within the Bugzilla template you want to extend, file a bug requesting one, specifying:

the template for which you are requesting a hook;
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);
the purpose of the hook;
a link to information about your extension, if any.

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 BUGZILLA_ROOT/template/en/extension/hook/.

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.

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.

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.

For example, let's say you have an extension named Projman that adds project management capabilities to Bugzilla. Projman has an administration interface edit-projects.cgi, 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.

The navigation bar is generated by the template file useful-links.html.tmpl, which is located in the global/ subdirectory on the standard Bugzilla template path BUGZILLA_ROOT/template/en/default/. Looking in useful-links.html.tmpl, you find the following hook at the end of the list of standard Bugzilla administration links:

...
    [% ', <a href="editkeywords.cgi">keywords</a>' 
                                              IF user.groups.editkeywords %]
    [% Hook.process("edit") %]
...

The corresponding directory for this hook is BUGZILLA_ROOT/template/en/extension/hook/global/useful-links.html.tmpl/edit/.

You put a template named projman-edit-projects.html.tmpl into that directory with the following content:

...[% ', <a href="edit-projects.cgi">projects</a>' IF user.groups.projman_admins %]

Voila! The link now appears after the other administration links in the navigation bar for users in the projman_admins group.

Notes: