| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> |
| <HTML |
| ><HEAD |
| ><TITLE |
| >Template Hooks</TITLE |
| ><META |
| NAME="GENERATOR" |
| CONTENT="Modular DocBook HTML Stylesheet Version 1.7"><LINK |
| REL="HOME" |
| TITLE="The Bugzilla Guide - 2.20.1 |
| 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.20.1 |
| 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 5. 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" |
| >5.2. Template Hooks</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 |
| > Template Hooks require Template Toolkit version 2.12 or |
| above, or the application of a patch. See <A |
| HREF="http://bugzilla.mozilla.org/show_bug.cgi?id=239112" |
| TARGET="_top" |
| >bug |
| 239112</A |
| > for details. |
| </P |
| ></TD |
| ></TR |
| ></TABLE |
| ></DIV |
| ><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 |
| <VAR |
| CLASS="literal" |
| >[% Hook.process("<VAR |
| CLASS="varname" |
| >name</VAR |
| >") %]</VAR |
| >, |
| where <VAR |
| CLASS="varname" |
| >name</VAR |
| > 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 <CODE |
| CLASS="methodname" |
| >Hook.process</CODE |
| > 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 <VAR |
| CLASS="literal" |
| >projman_admins</VAR |
| > 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 |
| > |
