Bug 230742 - document new 'hooks' mechanism. This is my take on Myk's text - probably still needs further polish.

webtools/bugzilla/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>