diff options
| -rw-r--r-- | docs/xml/customization.xml | 191 |
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("<name>") %]</filename>, where + <name> + 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/<path-to-standard-template>/<standard-template-name>/<hook-name>/</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&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>... + [% ', <a href="editkeywords.cgi">keywords</a>' + 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>[% ', <a href="edit-projects.cgi">projects</a>' 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> |