summaryrefslogtreecommitdiffstats
path: root/docs/html/cust-hooks.html
diff options
context:
space:
mode:
authorgerv%gerv.net <>2004-01-25 03:30:57 +0100
committergerv%gerv.net <>2004-01-25 03:30:57 +0100
commit6c709dd097e65025038a0dc9c17fad6a88e99b6b (patch)
treec0c33411898e67410829ea142458440fe912b388 /docs/html/cust-hooks.html
parentc7f3e4a3a055bbbec29a8731f388f9fa4648c768 (diff)
downloadbugzilla-6c709dd097e65025038a0dc9c17fad6a88e99b6b.tar.gz
bugzilla-6c709dd097e65025038a0dc9c17fad6a88e99b6b.tar.xz
Massive rearrangement of the installation section. Hopefully it makes sense now.
Diffstat (limited to 'docs/html/cust-hooks.html')
-rw-r--r--docs/html/cust-hooks.html454
1 files changed, 454 insertions, 0 deletions
diff --git a/docs/html/cust-hooks.html b/docs/html/cust-hooks.html
new file mode 100644
index 000000000..fe0ff99f2
--- /dev/null
+++ b/docs/html/cust-hooks.html
@@ -0,0 +1,454 @@
+<HTML
+><HEAD
+><TITLE
+>Template Hooks</TITLE
+><META
+NAME="GENERATOR"
+CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
+"><LINK
+REL="HOME"
+TITLE="The Bugzilla Guide - 2.17.7
+ Development Release"
+HREF="index.html"><LINK
+REL="UP"
+TITLE="Customising Bugzilla"
+HREF="customization.html"><LINK
+REL="PREVIOUS"
+TITLE="Template Customization"
+HREF="cust-templates.html"><LINK
+REL="NEXT"
+TITLE="Customizing Who Can Change What"
+HREF="cust-change-permissions.html"></HEAD
+><BODY
+CLASS="section"
+BGCOLOR="#FFFFFF"
+TEXT="#000000"
+LINK="#0000FF"
+VLINK="#840084"
+ALINK="#0000FF"
+><DIV
+CLASS="NAVHEADER"
+><TABLE
+SUMMARY="Header navigation table"
+WIDTH="100%"
+BORDER="0"
+CELLPADDING="0"
+CELLSPACING="0"
+><TR
+><TH
+COLSPAN="3"
+ALIGN="center"
+>The Bugzilla Guide - 2.17.7
+ Development Release</TH
+></TR
+><TR
+><TD
+WIDTH="10%"
+ALIGN="left"
+VALIGN="bottom"
+><A
+HREF="cust-templates.html"
+ACCESSKEY="P"
+>Prev</A
+></TD
+><TD
+WIDTH="80%"
+ALIGN="center"
+VALIGN="bottom"
+>Chapter 4. Customising Bugzilla</TD
+><TD
+WIDTH="10%"
+ALIGN="right"
+VALIGN="bottom"
+><A
+HREF="cust-change-permissions.html"
+ACCESSKEY="N"
+>Next</A
+></TD
+></TR
+></TABLE
+><HR
+ALIGN="LEFT"
+WIDTH="100%"></DIV
+><DIV
+CLASS="section"
+><H1
+CLASS="section"
+><A
+NAME="cust-hooks"
+></A
+>4.2. Template Hooks</H1
+><P
+>&#13; 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.
+ </P
+><P
+>&#13; 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.
+ </P
+><P
+>&#13; 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
+ <TT
+CLASS="literal"
+>[% Hook.process("<TT
+CLASS="varname"
+>name</TT
+>") %]</TT
+>,
+ where <TT
+CLASS="varname"
+>name</TT
+> is the unique (within that template)
+ name of the hook.
+ </P
+><P
+>&#13; 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. <B
+CLASS="command"
+>grep</B
+>) to search the standard templates
+ for occurrences of <TT
+CLASS="methodname"
+>Hook.process</TT
+> or browse
+ the directory tree in
+ <TT
+CLASS="filename"
+>BUGZILLA_ROOT/template/en/extension/hook/</TT
+>,
+ which contains a directory for each hook in the following location:
+ </P
+><P
+>&#13; <TT
+CLASS="filename"
+>BUGZILLA_ROOT/template/en/extension/hook/PATH_TO_STANDARD_TEMPLATE/STANDARD_TEMPLATE_NAME/HOOK_NAME/</TT
+>
+ </P
+><P
+>&#13; If there is no hook at the appropriate place within the Bugzilla template
+ you want to extend,
+ <A
+HREF="http://bugzilla.mozilla.org/enter_bug.cgi?product=Bugzilla&component=User%20Interface"
+TARGET="_top"
+>file
+ a bug requesting one</A
+>, specifying:
+ </P
+><P
+></P
+><TABLE
+BORDER="0"
+><TBODY
+><TR
+><TD
+>the template for which you are requesting a hook;</TD
+></TR
+><TR
+><TD
+>&#13; 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);
+ </TD
+></TR
+><TR
+><TD
+>the purpose of the hook;</TD
+></TR
+><TR
+><TD
+>a link to information about your extension, if any.</TD
+></TR
+></TBODY
+></TABLE
+><P
+></P
+><P
+>&#13; 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
+ <TT
+CLASS="filename"
+>BUGZILLA_ROOT/template/en/extension/hook/</TT
+>.
+ </P
+><P
+>&#13; 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.
+ </P
+><P
+>&#13; 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.
+ </P
+><P
+>&#13; 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.
+ </P
+><P
+>&#13; For example, let's say you have an extension named Projman that adds
+ project management capabilities to Bugzilla. Projman has an
+ administration interface <TT
+CLASS="filename"
+>edit-projects.cgi</TT
+>,
+ 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.
+ </P
+><P
+>&#13; The navigation bar is generated by the template file
+ <TT
+CLASS="filename"
+>useful-links.html.tmpl</TT
+>, which is located in
+ the <TT
+CLASS="filename"
+>global/</TT
+> subdirectory on the standard Bugzilla
+ template path
+ <TT
+CLASS="filename"
+>BUGZILLA_ROOT/template/en/default/</TT
+>.
+ Looking in <TT
+CLASS="filename"
+>useful-links.html.tmpl</TT
+>, you find
+ the following hook at the end of the list of standard Bugzilla
+ administration links:
+ </P
+><TABLE
+BORDER="0"
+BGCOLOR="#E0E0E0"
+WIDTH="100%"
+><TR
+><TD
+><FONT
+COLOR="#000000"
+><PRE
+CLASS="programlisting"
+>...
+ [% ', &#60;a href="editkeywords.cgi"&#62;keywords&#60;/a&#62;'
+ IF user.groups.editkeywords %]
+ [% Hook.process("edit") %]
+...</PRE
+></FONT
+></TD
+></TR
+></TABLE
+><P
+>&#13; The corresponding directory for this hook is
+ <TT
+CLASS="filename"
+>BUGZILLA_ROOT/template/en/extension/hook/global/useful-links.html.tmpl/edit/</TT
+>.
+ </P
+><P
+>&#13; You put a template named
+ <TT
+CLASS="filename"
+>projman-edit-projects.html.tmpl</TT
+>
+ into that directory with the following content:
+ </P
+><TABLE
+BORDER="0"
+BGCOLOR="#E0E0E0"
+WIDTH="100%"
+><TR
+><TD
+><FONT
+COLOR="#000000"
+><PRE
+CLASS="programlisting"
+>...[% ', &#60;a href="edit-projects.cgi"&#62;projects&#60;/a&#62;' IF user.groups.projman_admins %]</PRE
+></FONT
+></TD
+></TR
+></TABLE
+><P
+>&#13; Voila! The link now appears after the other administration links in the
+ navigation bar for users in the <TT
+CLASS="literal"
+>projman_admins</TT
+> group.
+ </P
+><P
+>&#13; Notes:
+ </P
+><P
+></P
+><UL
+><LI
+><P
+>&#13; You may want to prefix your extension template names
+ with the name of your extension, e.g.
+ <TT
+CLASS="filename"
+>projman-foo.html.tmpl</TT
+>,
+ so they do not conflict with the names of templates installed by
+ other extensions.
+ </P
+></LI
+><LI
+><P
+>&#13; 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
+ <TT
+CLASS="filename"
+>BUGZILLA_ROOT/template/en/extension/</TT
+>
+ directory. The <TT
+CLASS="filename"
+>extension/</TT
+> directory, like the
+ <TT
+CLASS="filename"
+>default/</TT
+> and <TT
+CLASS="filename"
+>custom/</TT
+>
+ directories, is part of the template search path, so putting templates
+ there enables them to be found by the template processor.
+ </P
+><P
+>&#13; The template processor looks for templates first in the
+ <TT
+CLASS="filename"
+>custom/</TT
+> directory (i.e. templates added by the
+ specific installation), then in the <TT
+CLASS="filename"
+>extension/</TT
+>
+ directory (i.e. templates added by extensions), and finally in the
+ <TT
+CLASS="filename"
+>default/</TT
+> directory (i.e. the standard Bugzilla
+ templates). Thus extension templates can override standard templates,
+ but installation-specific templates override both.
+ </P
+><P
+>&#13; 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.
+ </P
+></LI
+><LI
+><P
+>&#13; Installation customizers can also take advantage of hooks when adding
+ code to a Bugzilla template. To do so, create directories in
+ <TT
+CLASS="filename"
+>BUGZILLA_ROOT/template/en/custom/hook/</TT
+>
+ equivalent to the directories in
+ <TT
+CLASS="filename"
+>BUGZILLA_ROOT/template/en/extension/hook/</TT
+>
+ for the hooks you want to use, then place your customization templates
+ into those directories.
+ </P
+><P
+>&#13; 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.
+ </P
+></LI
+></UL
+></DIV
+><DIV
+CLASS="NAVFOOTER"
+><HR
+ALIGN="LEFT"
+WIDTH="100%"><TABLE
+SUMMARY="Footer navigation table"
+WIDTH="100%"
+BORDER="0"
+CELLPADDING="0"
+CELLSPACING="0"
+><TR
+><TD
+WIDTH="33%"
+ALIGN="left"
+VALIGN="top"
+><A
+HREF="cust-templates.html"
+ACCESSKEY="P"
+>Prev</A
+></TD
+><TD
+WIDTH="34%"
+ALIGN="center"
+VALIGN="top"
+><A
+HREF="index.html"
+ACCESSKEY="H"
+>Home</A
+></TD
+><TD
+WIDTH="33%"
+ALIGN="right"
+VALIGN="top"
+><A
+HREF="cust-change-permissions.html"
+ACCESSKEY="N"
+>Next</A
+></TD
+></TR
+><TR
+><TD
+WIDTH="33%"
+ALIGN="left"
+VALIGN="top"
+>Template Customization</TD
+><TD
+WIDTH="34%"
+ALIGN="center"
+VALIGN="top"
+><A
+HREF="customization.html"
+ACCESSKEY="U"
+>Up</A
+></TD
+><TD
+WIDTH="33%"
+ALIGN="right"
+VALIGN="top"
+>Customizing Who Can Change What</TD
+></TR
+></TABLE
+></DIV
+></BODY
+></HTML
+> \ No newline at end of file