5.2. Template Hooks

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

• You may want to prefix your extension template names with the name of your extension, e.g. projman-foo.html.tmpl, so they do not conflict with the names of templates installed by other extensions.

• 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 BUGZILLA_ROOT/template/en/extension/ directory. The extension/ directory, like the default/ and custom/ directories, is part of the template search path, so putting templates there enables them to be found by the template processor.

  The template processor looks for templates first in the custom/ directory (i.e. templates added by the specific installation), then in the extension/ directory (i.e. templates added by extensions), and finally in the default/ directory (i.e. the standard Bugzilla templates). Thus extension templates can override standard templates, but installation-specific templates override both.

  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.

• Installation customizers can also take advantage of hooks when adding code to a Bugzilla template. To do so, create directories in BUGZILLA_ROOT/template/en/custom/hook/ equivalent to the directories in BUGZILLA_ROOT/template/en/extension/hook/ for the hooks you want to use, then place your customization templates into those directories.

  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.