diff options
Diffstat (limited to 'docs/html/cust-hooks.html')
| -rw-r--r-- | docs/html/cust-hooks.html | 454 |
1 files changed, 0 insertions, 454 deletions
diff --git a/docs/html/cust-hooks.html b/docs/html/cust-hooks.html deleted file mode 100644 index fe0ff99f2..000000000 --- a/docs/html/cust-hooks.html +++ /dev/null @@ -1,454 +0,0 @@ -<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 -> 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 -> 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 -> 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 -> 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 -> <TT -CLASS="filename" ->BUGZILLA_ROOT/template/en/extension/hook/PATH_TO_STANDARD_TEMPLATE/STANDARD_TEMPLATE_NAME/HOOK_NAME/</TT -> - </P -><P -> 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 -> 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 -> 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 -> 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 -> 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 -> 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 -> 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 -> 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" ->... - [% ', <a href="editkeywords.cgi">keywords</a>' - IF user.groups.editkeywords %] - [% Hook.process("edit") %] -...</PRE -></FONT -></TD -></TR -></TABLE -><P -> 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 -> 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" ->...[% ', <a href="edit-projects.cgi">projects</a>' IF user.groups.projman_admins %]</PRE -></FONT -></TD -></TR -></TABLE -><P -> 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 -> Notes: - </P -><P -></P -><UL -><LI -><P -> 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 -> 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 -> 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 -> 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 -> 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 -> 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 |