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