Sophie: bugzilla-3.4.2-1mdv2010.0 noarch

bugzilla-3.4.2-1mdv2010.0.noarch.rpm

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<HTML
><HEAD
><TITLE
>The Bugzilla Extension Mechanism</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK
REL="HOME"
TITLE="The Bugzilla Guide - 3.4.2 
    Release"
HREF="index.html"><LINK
REL="UP"
TITLE="Customizing 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 - 3.4.2 
    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 6. Customizing 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"
>6.3. The Bugzilla Extension Mechanism</A
></H1
><DIV
CLASS="warning"
><P
></P
><TABLE
CLASS="warning"
WIDTH="100%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
><IMG
SRC="../images/warning.gif"
HSPACE="5"
ALT="Warning"></TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
>&#13;        Note that the below paths are inconsistent and confusing. They will
        likely be changed in Bugzilla 4.0.
      </P
></TD
></TR
></TABLE
></DIV
><P
>&#13;      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. 
    </P
><P
>&#13;      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. 
    </P
><P
>&#13;      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 (<TT
CLASS="filename"
>BUGZILLA_ROOT/extensions/extension_name</TT
>).  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.
    </P
><P
>&#13;      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 appearance of a hook depends on if the hook 
      is a code hook or a template hook. 
    </P
><P
>&#13;      Code hooks appear in Bugzilla source files as a single method call 
      in the format <TT
CLASS="literal"
>Bugzilla::Hook-&#62;process("<CODE
CLASS="varname"
>name</CODE
>");</TT
>.
      For instance, <TT
CLASS="filename"
>enter_bug.cgi</TT
> may invoke the hook 
      "<CODE
CLASS="varname"
>enter_bug-entrydefaultvars</CODE
>". Thus, a source file at 
      <TT
CLASS="filename"
>BUGZILLA_ROOT/extensions/EXTENSION_NAME/code/enter_bug-entrydefaultvars.pl</TT
>
      will be automatically invoked when the code hook is reached. 
    </P
><P
>  
      Template hooks appear in the standard Bugzilla templates as a 
      single directive in the format
      <TT
CLASS="literal"
>[% Hook.process("<CODE
CLASS="varname"
>name</CODE
>") %]</TT
>,
      where <CODE
CLASS="varname"
>name</CODE
> is the unique name of the hook.
    </P
><P
>&#13;      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. <B
CLASS="command"
>grep</B
>) to search the standard templates
      for occurrences of <CODE
CLASS="methodname"
>Hook.process</CODE
> or the source 
      files for occurrences of <CODE
CLASS="methodname"
>Bugzilla::Hook::process</CODE
>.
    </P
><P
>&#13;      If there is no hook at the appropriate place within the Bugzilla 
      source file or template you want to extend,
      <A
HREF="http://bugzilla.mozilla.org/enter_bug.cgi?product=Bugzilla&#38;component=User%20Interface"
TARGET="_top"
>file
      a bug requesting one</A
>, specifying:
    </P
><P
></P
><TABLE
BORDER="0"
><TBODY
><TR
><TD
>the source or template file for which you are 
          requesting a hook;</TD
></TR
><TR
><TD
>&#13;        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);
      </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 or source file, and check 
      the new version of the template into CVS.
    </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 to the directory within the Bugzilla
      extensions tree corresponding to the hook. 
    </P
><P
>&#13;      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.
    </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.in_group('editkeywords') %]
    [% Hook.process("edit") %]
...</PRE
></FONT
></TD
></TR
></TABLE
><P
>&#13;      The corresponding extension file for this hook is
      <TT
CLASS="filename"
>BUGZILLA_ROOT/extensions/projman/template/en/global/useful-links-edit.html.tmpl</TT
>.
      You then create that template file and add the following constant:
    </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.in_group('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;      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 
      <TT
CLASS="filename"
>enter_bug.cgi</TT
>, 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 
      <TT
CLASS="filename"
>BUGZILLA_ROOT/extensions/projman/code/enter_bug-entrydefaultvars.pl</TT
>.
      You then create that file and add the following:
    </P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><FONT
COLOR="#000000"
><PRE
CLASS="programlisting"
>$default{'project_manager'} = $product.'@company.com';</PRE
></FONT
></TD
></TR
></TABLE
><P
>&#13;      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. 
    </P
><P
>&#13;      Notes:
    </P
><P
></P
><UL
><LI
><P
>&#13;          If your extension includes entirely new templates in addition to
          extensions of standard templates, it should store those new
          templates in its
          <TT
CLASS="filename"
>BUGZILLA_ROOT/extensions/template/en/</TT
> 
          directory. Extension template directories, like the 
          <TT
CLASS="filename"
>default/</TT
> and <TT
CLASS="filename"
>custom/</TT
>
          directories, are 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"
>extensions/</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, installation-specific templates override both 
          default and extension templates.
        </P
></LI
><LI
><P
>&#13;          If you are looking to customize Bugzilla, you can also take advantage 
          of template hooks. To do so, create a directory in
          <TT
CLASS="filename"
>BUGZILLA_ROOT/template/en/custom/hook/</TT
>
          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 
          <TT
CLASS="filename"
>global/useful-links.html.tmpl</TT
>, you would 
          create the directory <TT
CLASS="filename"
>BUGZILLA_ROOT/template/en/custom/hook/
          global/useful-links.html.tmpl/end/</TT
> and add your customization 
          template to this directory. 
        </P
><P
>&#13;          Obviously this method of customizing Bugzilla only lets you add code
          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.
        </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
>