diff options
Diffstat (limited to 'docs/html/cust-hooks.html')
| -rw-r--r-- | docs/html/cust-hooks.html | 454 |
1 files changed, 454 insertions, 0 deletions
diff --git a/docs/html/cust-hooks.html b/docs/html/cust-hooks.html new file mode 100644 index 000000000..fe0ff99f2 --- /dev/null +++ b/docs/html/cust-hooks.html @@ -0,0 +1,454 @@ +<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 +>
\ No newline at end of file |