diff options
Diffstat (limited to 'docs')
-rw-r--r-- | docs/xml/customization.xml | 201 |
1 files changed, 111 insertions, 90 deletions
diff --git a/docs/xml/customization.xml b/docs/xml/customization.xml index 0198670ba..ef091cb06 100644 --- a/docs/xml/customization.xml +++ b/docs/xml/customization.xml @@ -411,11 +411,11 @@ </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. @@ -423,62 +423,82 @@ </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> @@ -487,9 +507,8 @@ <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> @@ -505,13 +524,13 @@ <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> @@ -542,14 +561,9 @@ ...]]></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> @@ -558,7 +572,28 @@ 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> @@ -566,61 +601,47 @@ <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> |