Bug 233398: Update the customization docs to point to the Extensions system POD instead of having docs about template hooks in the Guide.

Patch by Max Kanat-Alexander <mkanat@bugzilla.org> r=LpSolit, a=LpSolit

1 files changed, 19 insertions, 237 deletions

diff --git a/docs/en/xml/customization.xml b/docs/en/xml/customization.xml
index 24b1d4403..f397cff53 100644
--- a/docs/en/xml/customization.xml
+++ b/docs/en/xml/customization.xml
@@ -2,6 +2,23 @@
 <chapter id="customization">
   <title>Customizing Bugzilla</title>
 
+  <section id="extensions">
+    <title>Bugzilla Extensions</title>
+
+    <para>
+      One of the best ways to customize Bugzilla is by writing a Bugzilla
+      Extension. Bugzilla Extensions let you modify both the code and
+      UI of Bugzilla in a way that can be distributed to other Bugzilla
+      users and ported forward to future versions of Bugzilla with minimal
+      effort.
+    </para>
+
+    <para>
+      See the <ulink url="api/Bugzilla/Extension.html">Bugzilla Extension
+      documentation</ulink> for information on how to write an Extension.
+    </para>
+  </section>
+
   <section id="cust-skins">
     <title>Custom Skins</title>
     
@@ -438,241 +455,6 @@
       
   </section>
 
-  <section id="cust-hooks">
-    <title>The Bugzilla Extension Mechanism</title>
-    
-    <warning>
-      <para>
-        Note that the below paths are inconsistent and confusing. They will
-        likely be changed in Bugzilla 4.0.
-      </para>
-    </warning>
-       
-    <para>
-      Extensions are a way for extensions to Bugzilla to insert code
-      into the standard Bugzilla templates and source files
-      without modifying these files themselves.  The extension mechanism 
-      defines a consistent API for extending the standard templates and source files 
-      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. Furthermore, they make it easy to install 
-      and remove extensions as each extension is nothing more than a 
-      simple directory structure. 
-    </para>
-    
-    <para>
-      There are two main types of hooks: code hooks and template hooks. Code 
-      hooks allow extensions to invoke code at specific points in various 
-      source files, while template hooks allow extensions to add elements to 
-      the Bugzilla user interface. 
-    </para>
-
-    <para>
-      A hook is just a named place in a standard source or template file
-      where extension source code or template files for that hook get processed. 
-      Each extension has a corresponding directory in the Bugzilla directory 
-      tree (<filename>BUGZILLA_ROOT/extensions/extension_name</filename>).  Hooking 
-      an extension source file or template to a hook is as simple as putting 
-      the extension file into extension's template or code directory. 
-      When Bugzilla processes the source file or template and reaches the hook, 
-      it will process all extension files in the hook's directory. 
-      The hooks themselves can be added into any source file or standard template 
-      upon request by extension authors.
-    </para>
-    
-    <para>
-      To use hooks to extend Bugzilla, first make sure there is
-      a hook at the appropriate place within the source file or template you 
-      want to extend. The exact appearance of a hook depends on if the hook 
-      is a code hook or a template hook. 
-    </para>
-    
-    <para>
-      Code hooks appear in Bugzilla source files as a single method call 
-      in the format <literal role="code">Bugzilla::Hook->process("<varname>name</varname>");</literal>.
-      For instance, <filename>enter_bug.cgi</filename> may invoke the hook 
-      "<varname>enter_bug-entrydefaultvars</varname>". Thus, a source file at 
-      <filename>BUGZILLA_ROOT/extensions/EXTENSION_NAME/code/enter_bug-entrydefaultvars.pl</filename>
-      will be automatically invoked when the code hook is reached. 
-    </para>
-   
-    <para>  
-      Template hooks appear in the standard Bugzilla templates as a 
-      single directive in the format
-      <literal role="code">[% Hook.process("<varname>name</varname>") %]</literal>,
-      where <varname>name</varname> is the unique name of the hook.
-    </para>
-
-    <para>
-      If you aren't sure what you want to extend or just want to browse the 
-      available hooks, either use your favorite multi-file search
-      tool (e.g. <command>grep</command>) to search the standard templates
-      for occurrences of <methodname>Hook.process</methodname> or the source 
-      files for occurrences of <methodname>Bugzilla::Hook::process</methodname>.
-    </para>
-
-    <para>
-      If there is no hook at the appropriate place within the Bugzilla 
-      source file or 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 source or template file for which you are 
-          requesting a hook;</member>
-      <member>
-        where in the file you would like the hook to be placed
-        (line number/position for latest version of the file 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 or source file, and check 
-      the new version of the template into CVS.
-    </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 to the directory within the Bugzilla
-      extensions tree corresponding to the hook. 
-    </para>
-    
-    <para>
-      That's it!  Now, when the source file or template containing the hook
-      is processed, your extension file 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_ROOT/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><![CDATA[...
-    [% ', <a href="editkeywords.cgi">keywords</a>' 
-       IF user.in_group('editkeywords') %]
-    [% Hook.process("edit") %]
-...]]></programlisting>
-
-    <para>
-      The corresponding extension file for this hook is
-      <filename>BUGZILLA_ROOT/extensions/projman/template/en/global/useful-links-edit.html.tmpl</filename>.
-      You then create that template file and add the following constant:
-    </para>
-
-    <programlisting><![CDATA[...[% ', <a href="edit-projects.cgi">projects</a>' IF user.in_group('projman_admins') %]]]></programlisting>
-
-    <para>
-      Voila!  The link now appears after the other administration links in the
-      navigation bar for users in the <literal>projman_admins</literal> group.
-    </para>
-    
-    <para>
-      Now, let us say your extension adds a custom "project_manager" field 
-      to enter_bug.cgi. You want to modify the CGI script to set the default 
-      project manager to be productname@company.com. Looking at 
-      <filename>enter_bug.cgi</filename>, you see the enter_bug-entrydefaultvars 
-      hook near the bottom of the file before the default form values are set. 
-      The corresponding extension source file for this hook is located at 
-      <filename>BUGZILLA_ROOT/extensions/projman/code/enter_bug-entrydefaultvars.pl</filename>.
-      You then create that file and add the following:
-    </para>
-    
-    <programlisting>$default{'project_manager'} = $product.'@company.com';</programlisting>
-    
-    <para>
-      This code will be invoked whenever enter_bug.cgi is executed. 
-      Assuming that the rest of the customization was completed (e.g. the 
-      custom field was added to the enter_bug template and the required hooks 
-      were used in process_bug.cgi), the new field will now have this 
-      default value. 
-    </para>
-      
-    <para>
-      Notes:
-    </para>
-
-    <itemizedlist>
-      <listitem>
-        <para>
-          If your extension includes entirely new templates in addition to
-          extensions of standard templates, it should store those new
-          templates in its
-          <filename>BUGZILLA_ROOT/extensions/template/en/</filename> 
-          directory. Extension template directories, like the 
-          <filename>default/</filename> and <filename>custom/</filename>
-          directories, are 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>extensions/</filename>
-          directory (i.e. templates added by extensions), and finally in the 
-          <filename>default/</filename> directory (i.e. the standard Bugzilla 
-          templates). Thus, installation-specific templates override both 
-          default and extension templates.
-        </para>
-      </listitem>
-
-      <listitem>
-        <para>
-          If you are looking to customize Bugzilla, you can also take advantage 
-          of template hooks. To do so, create a directory in
-          <filename>BUGZILLA_ROOT/template/en/custom/hook/</filename>
-          that corresponds to the hook you wish to use, then place your 
-          customization templates into those directories. For example, 
-          if you wanted to use the hook "end" in 
-          <filename>global/useful-links.html.tmpl</filename>, you would 
-          create the directory <filename>BUGZILLA_ROOT/template/en/custom/hook/
-          global/useful-links.html.tmpl/end/</filename> and add your customization 
-          template to this directory. 
-        </para>
-
-        <para>
-          Obviously this method of customizing Bugzilla only lets you add code
-          to the standard source files and 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.
-        </para>
-      </listitem>
-    </itemizedlist>    
-  </section>
-
   <section id="cust-change-permissions">
     <title>Customizing Who Can Change What</title>
     
@@ -795,8 +577,8 @@
 
     <para>
       Many utilities and applications can integrate with Bugzilla,
-      either on the client- or server-side. None of them is maintained
-      by the Bugzilla community, nor are they being tested during our
+      either on the client- or server-side. None of them are maintained
+      by the Bugzilla community, nor are they tested during our
       QA tests, so use them at your own risk. They are listed at
       <ulink url="https://wiki.mozilla.org/Bugzilla:Addons" />.
     </para>