</section>
<section id="cust-hooks">
- <title>Template Hooks</title>
+ <title>The Bugzilla Extension Mechanism</title>
<warning>
<para>
- Template Hooks require Template Toolkit version 2.12 or
+ Custom extensions require Template Toolkit version 2.12 or
above, or the application of a patch. See <ulink
url="http://bugzilla.mozilla.org/show_bug.cgi?id=239112">bug
239112</ulink> for details.
</warning>
<para>
- Template hooks are a way for extensions to Bugzilla to insert code
- into the standard Bugzilla templates without modifying the template files
- themselves. The hooks mechanism defines a consistent API for extending
- the standard templates 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.
+ 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 template hook is just a named place in a standard template file
- where extension template files for that hook get processed. Each hook
- has a corresponding directory in the Bugzilla directory tree. Hooking an
- extension template to a hook is as simple as putting the extension file
- into the hook's directory. When Bugzilla processes the standard template
- and reaches the hook, it will process all extension templates in the
- hook's directory. The hooks themselves can be added into any standard
- template upon request by extension authors.
+ 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 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 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 (within that template)
- name of the hook.
+ 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 appearence of a hook depends on if the hook
+ is a code hook or a template 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. <command>grep</command>) to search the standard templates
- for occurrences of <methodname>Hook.process</methodname> or browse
- the directory tree in
- <filename>BUGZILLA_ROOT/template/en/extension/hook/</filename>,
- which contains a directory for each hook in the following location:
+ 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-defaultvars</varname>". Thus, a source file at
+ <filename>BUGZILLA_ROOT/extensions/EXTENSION_NAME/code/enter_bug-entrydefaultvars.pl</filename>
+ will be automatically invoked when 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>
- <filename>BUGZILLA_ROOT/template/en/extension/hook/PATH_TO_STANDARD_TEMPLATE/STANDARD_TEMPLATE_NAME/HOOK_NAME/</filename>
+ 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 occurences of <methodname>Bugzilla::Hook::process</methodname>.
</para>
<para>
- If there is no hook at the appropriate place within the Bugzilla template
- you want to extend,
+ 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&component=User%20Interface">file
a bug requesting one</ulink>, specifying:
</para>
<simplelist>
- <member>the template for which you are requesting a hook;</member>
+ <member>the source or template file 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
+ 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>
<para>
The Bugzilla reviewers will promptly review each hook request,
- name the hook, add it to the template, check the new version
- of the template into CVS, and create the corresponding directory in
- <filename>BUGZILLA_ROOT/template/en/extension/hook/</filename>.
+ name the hook, add it to the template or source file, and check
+ the new version of the template into CVS.
</para>
<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.
+ add your extension to the directory within the Bugzilla
+ extensions 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
+ 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>
...]]></programlisting>
<para>
- The corresponding directory for this hook is
- <filename>BUGZILLA_ROOT/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:
+ The corresponding extension file for this hook is
+ <filename>BUGZILLA_ROOT/extensions/projman/template/en/hook/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.groups.projman_admins %]]]></programlisting>
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>
- You may want to prefix your extension template names
- with the name of your extension, e.g.
- <filename>projman-foo.html.tmpl</filename>,
- so they do not 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_ROOT/template/en/extension/</filename>
- directory. The <filename>extension/</filename> directory, like the
+ 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, is part of the template search path, so putting templates
+ 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>extension/</filename>
- directory (i.e. templates added by extensions), and finally in 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 extension templates can override standard templates,
- but installation-specific templates override both.
- </para>
-
- <para>
- Note that overriding standard templates with extension 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.
+ templates). Thus, installation-specific templates override both
+ default and extension templates.
</para>
</listitem>
<listitem>
<para>
- Installation customizers can also take advantage of hooks when adding
- code to a Bugzilla template. To do so, create directories in
+ 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>
- equivalent to the directories in
- <filename>BUGZILLA_ROOT/template/en/extension/hook/</filename>
- for the hooks you want to use, then place your customization templates
- into those directories.
+ 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 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.
+ 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>
projects / thirdparty / bugzilla.git / commitdiff
