summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--docs/xml/customization.xml191
1 files changed, 191 insertions, 0 deletions
diff --git a/docs/xml/customization.xml b/docs/xml/customization.xml
index 2e3306f88..a9005665e 100644
--- a/docs/xml/customization.xml
+++ b/docs/xml/customization.xml
@@ -305,6 +305,197 @@
</section>
+ <section id="cust-hooks">
+ <title>Template Hooks</title>
+
+ <para>
+ Template hooks are a way for customisers or Bugzilla extensions to insert
+ code into the standard Bugzilla templates without modifying them.
+ The hooks mechanism defines an API for extending the
+ standard templates with a clean separation of code.
+ This makes the changes less tied to specific versions of
+ Bugzilla, and reduces merge conflicts, making
+ upgrading a modified Bugzilla installation easier.
+ </para>
+
+ <para>
+ A template hook is just an named place in a standard template file.
+ When Bugzilla reaches this position, it checks whether there are any
+ extension template files for that hook. If so, it processes them. Each
+ hook has a directory of its own in the Bugzilla template directory tree.
+ Hooking a template file on to a specific hook is as
+ simple as putting the file into that hook's directory.
+ </para>
+
+ <para>
+ 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 default Bugzilla templates as a single template
+ directive in the format
+ <filename>[% Hook.process("&lt;name&gt;") %]</filename>, where
+ &lt;name&gt;
+ is the unique (within that template) name of the hook.
+ </para>
+
+ <para>
+ 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
+ <filename>$BUGZILLA_HOME/template/en/extension/hook/</filename>,
+ which contains a directory for each hook. Each hook's directory
+ is located as follows:
+ </para>
+
+ <para>
+ <filename>$BUGZILLA_HOME/template/en/extension/hook/&lt;path-to-standard-template&gt;/&lt;standard-template-name&gt;/&lt;hook-name&gt;/</filename>
+ </para>
+
+ <para>
+ If there is no hook in the appropriate place within the Bugzilla
+ template you want to extend,
+ <ulink url="http://bugzilla.mozilla.org/enter_bug.cgi?product=Bugzilla&amp;component=User%20Interface">file
+ a bug requesting one</ulink>, specifying:
+ </para>
+
+ <simplelist>
+ <member>the template for which you are requesting a hook;</member>
+
+ <member>
+ 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);
+ </member>
+ <member>the purpose of the hook;</member>
+ <member>a link to information about your extension, if any.</member>
+ </simplelist>
+
+ <para>
+ The Bugzilla reviewers will promptly review each hook request,
+ name the hook,
+ add it to the template and check the new version into CVS, and add the
+ corresponding directory to
+ <filename>$BUGZILLA_HOME/template/en/extension/hook/</filename>.
+ </para>
+
+ <para>
+ 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.
+ </para>
+
+ <para>
+ 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.
+ </para>
+
+ <para>
+ 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.
+ </para>
+
+ <para>
+ For example, let's say you have an extension named Projman that adds
+ project management capabilities to Bugzilla. Projman has an
+ administration interface <filename>edit-projects.cgi</filename>,
+ 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.
+ </para>
+
+ <para>
+ The navigation bar is generated by the template file
+ <filename>useful-links.html.tmpl</filename>, which is located in the
+ <filename>global/</filename> subdirectory on the standard Bugzilla
+ template path
+ <filename>$BUGZILLA_HOME/template/en/default/</filename>.
+ Looking in <filename>useful-links.html.tmpl</filename>, you find the
+ following
+ hook at the end of the list of standard Bugzilla administration links:
+ </para>
+
+ <programlisting>...
+ [% ', &lt;a href="editkeywords.cgi"&gt;keywords&lt;/a&gt;'
+ IF user.groups.editkeywords %]
+ [% Hook.process("edit") %]
+...</programlisting>
+
+ <para>
+ The corresponding directory for this hook is
+ <filename>$BUGZILLA_HOME/template/en/extension/hook/global/useful-links.html.tmpl/edit/</filename>.
+ </para>
+
+ <para>
+ You put a template named
+ <filename>projman-edit-projects.html.tmpl</filename>
+ into that directory with the following content:
+ </para>
+
+ <programlisting>[% ', &lt;a href="edit-projects.cgi"&gt;projects&lt;/a&gt;' IF user.groups.projman_admins %]</programlisting>
+
+ <para>
+ Voila! The link now appears after the other administration links in the
+ navigation bar for users in the <filename>projman_admins</filename> group.
+ </para>
+
+ <para>
+ Notes:
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ You may want to prefix your extension templates names with
+ the name of your extension, e.g.
+ <filename>projman-foo.html.tmpl</filename>,
+ so there is no chance of a conflict with the names of
+ templates installed by other extensions.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ 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
+ <filename>$BUGZILLA_HOME/template/en/extension/</filename>
+ directory.
+ The <filename>extension/</filename> directory, like the
+ <filename>default/</filename>
+ and <filename>custom/</filename> directories, is part of the template
+ search path, so putting templates there enables them to be found by
+ the template processor.
+ </para>
+
+ <para>
+ The template processor looks for templates first in the
+ <filename>custom/</filename> directory (i.e. templates added by the
+ specific installation), then in the <filename>extension/</filename>
+ directory (i.e. templates added by extensions), and finally in the
+ <filename>default/</filename> directory, for the standard Bugzilla
+ templates.
+ Thus extension templates can override standard templates, but
+ installation-specific templates override both.
+ </para>
+
+ <para>
+ Note that overriding standard 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.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </section>
+
<section id="cust-change-permissions">
<title>Customizing Who Can Change What</title>