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

2004-01-19 00:25:16 +00:00 · 2004-01-19 00:25:16 +00:00 · 3917285e25
--- a/webtools/bugzilla/docs/xml/customization.xml
+++ b/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>