Sophie

Sophie

distrib > Mageia > 7 > i586 > by-pkgid > 4e237fd705495e1e21ef20696443e053 > files > 1041

bugzilla-5.0.4-3.mga7.noarch.rpm

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
  <head>
    <title>
Bugzilla::Extension</title>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
  <link rel="stylesheet" title="style" type="text/css" href=".././../../../../style.css" media="all" >

</head>
  <body id="pod">
<p class="backlinktop"><b><a name="___top" href="../index.html" accesskey="1" title="All Documents">&lt;&lt;</a></b></p>
<h1>Bugzilla::Extension</h1>
<div class='indexgroup'>
<ul   class='indexList indexList1'>
  <li class='indexItem indexItem1'><a href='#NAME'>NAME</a>
  <li class='indexItem indexItem1'><a href='#SYNOPSIS'>SYNOPSIS</a>
  <li class='indexItem indexItem1'><a href='#DESCRIPTION'>DESCRIPTION</a>
  <li class='indexItem indexItem1'><a href='#WRITING_EXTENSIONS'>WRITING EXTENSIONS</a>
  <ul   class='indexList indexList2'>
    <li class='indexItem indexItem2'><a href='#Using_extensions%2Fcreate.pl'>Using extensions/create.pl</a>
    <li class='indexItem indexItem2'><a href='#Example_Extension'>Example Extension</a>
    <li class='indexItem indexItem2'><a href='#Where_Extension_Code_Goes'>Where Extension Code Goes</a>
    <li class='indexItem indexItem2'><a href='#The_Extension_NAME.'>The Extension NAME.</a>
    <li class='indexItem indexItem2'><a href='#Hooks'>Hooks</a>
    <ul   class='indexList indexList3'>
      <li class='indexItem indexItem3'><a href='#Adding_New_Hooks_To_Bugzilla'>Adding New Hooks To Bugzilla</a>
    </ul>
    <li class='indexItem indexItem2'><a href='#If_Your_Extension_Requires_Certain_Perl_Modules'>If Your Extension Requires Certain Perl Modules</a>
    <ul   class='indexList indexList3'>
      <li class='indexItem indexItem3'><a href='#If_Your_Extension_Needs_Certain_Modules_In_Order_To_Compile'>If Your Extension Needs Certain Modules In Order To Compile</a>
    </ul>
    <li class='indexItem indexItem2'><a href='#Libraries'>Libraries</a>
    <li class='indexItem indexItem2'><a href='#Templates'>Templates</a>
    <li class='indexItem indexItem2'><a href='#Template_Hooks'>Template Hooks</a>
    <ul   class='indexList indexList3'>
      <li class='indexItem indexItem3'><a href='#Which_Templates_Can_Be_Hooked'>Which Templates Can Be Hooked</a>
      <li class='indexItem indexItem3'><a href='#Where_Template_Hooks_Go'>Where Template Hooks Go</a>
      <li class='indexItem indexItem3'><a href='#Adding_New_Template_Hooks_to_Bugzilla'>Adding New Template Hooks to Bugzilla</a>
    </ul>
    <li class='indexItem indexItem2'><a href='#Overriding_Existing_Templates'>Overriding Existing Templates</a>
    <ul   class='indexList indexList3'>
      <li class='indexItem indexItem3'><a href='#A_Warning_About_Extensions_That_You_Want_To_Distribute'>A Warning About Extensions That You Want To Distribute</a>
    </ul>
    <li class='indexItem indexItem2'><a href='#CSS%2C_JavaScript%2C_and_Images'>CSS, JavaScript, and Images</a>
    <li class='indexItem indexItem2'><a href='#Documenting_Extensions'>Documenting Extensions</a>
    <li class='indexItem indexItem2'><a href='#Disabling_Your_Extension'>Disabling Your Extension</a>
  </ul>
  <li class='indexItem indexItem1'><a href='#DISTRIBUTING_EXTENSIONS'>DISTRIBUTING EXTENSIONS</a>
  <ul   class='indexList indexList2'>
    <li class='indexItem indexItem2'><a href='#Distributing_on_CPAN'>Distributing on CPAN</a>
    <ul   class='indexList indexList3'>
      <li class='indexItem indexItem3'><a href='#Templates_in_extensions_distributed_on_CPAN'>Templates in extensions distributed on CPAN</a>
      <li class='indexItem indexItem3'><a href='#Using_an_extension_distributed_on_CPAN'>Using an extension distributed on CPAN</a>
    </ul>
  </ul>
  <li class='indexItem indexItem1'><a href='#GETTING_HELP_WITH_WRITING_EXTENSIONS'>GETTING HELP WITH WRITING EXTENSIONS</a>
  <li class='indexItem indexItem1'><a href='#ADDITIONAL_CONSTANTS'>ADDITIONAL CONSTANTS</a>
  <ul   class='indexList indexList2'>
    <li class='indexItem indexItem2'><a href='#%24VERSION'>$VERSION</a>
  </ul>
  <li class='indexItem indexItem1'><a href='#SUBCLASS_METHODS'>SUBCLASS METHODS</a>
  <ul   class='indexList indexList2'>
    <li class='indexItem indexItem2'><a href='#Class_Methods'>Class Methods</a>
    <ul   class='indexList indexList3'>
      <li class='indexItem indexItem3'><a href='#new'>new</a>
    </ul>
    <li class='indexItem indexItem2'><a href='#Instance_Methods'>Instance Methods</a>
    <ul   class='indexList indexList3'>
      <li class='indexItem indexItem3'><a href='#enabled'>enabled</a>
      <li class='indexItem indexItem3'><a href='#package_dir'>package_dir</a>
      <li class='indexItem indexItem3'><a href='#template_dir'>template_dir</a>
      <li class='indexItem indexItem3'><a href='#web_dir'>web_dir</a>
      <li class='indexItem indexItem3'><a href='#lib_dir'>lib_dir</a>
    </ul>
  </ul>
  <li class='indexItem indexItem1'><a href='#BUGZILLA%3A%3AEXTENSION_CLASS_METHODS'>BUGZILLA::EXTENSION CLASS METHODS</a>
  <ul   class='indexList indexList2'>
    <li class='indexItem indexItem2'><a href='#load'>load</a>
    <li class='indexItem indexItem2'><a href='#load_all'>load_all</a>
  </ul>
  <li class='indexItem indexItem1'><a href='#Methods_in_need_of_POD'>Methods in need of POD</a>
</ul>
</div>

<h1><a class='u' href='#___top' title='click to go to top of document'
name="NAME"
>NAME</a></h1>

<p>Bugzilla::Extension - Base class for Bugzilla Extensions.</p>

<h1><a class='u' href='#___top' title='click to go to top of document'
name="SYNOPSIS"
>SYNOPSIS</a></h1>

<p>The following would be in <em  class="code">extensions/Foo/Extension.pm</em> or <em  class="code">extensions/Foo.pm</em>:</p>

<pre  class="code"> package Bugzilla::Extension::Foo
 use strict;
 use parent qw(Bugzilla::Extension);

 our $VERSION = &#39;0.02&#39;;
 use constant NAME =&#62; &#39;Foo&#39;;

 sub some_hook_name { ... }

 __PACKAGE__-&#62;NAME;</pre>

<p>Custom templates would go into <em  class="code">extensions/Foo/template/en/default/</em>. <a href="#Template_Hooks" class="podlinkpod"
>Template hooks</a> would go into <em  class="code">extensions/Foo/template/en/default/hook/</em>.</p>

<h1><a class='u' href='#___top' title='click to go to top of document'
name="DESCRIPTION"
>DESCRIPTION</a></h1>

<p>This is the base class for all Bugzilla extensions.</p>

<h1><a class='u' href='#___top' title='click to go to top of document'
name="WRITING_EXTENSIONS"
>WRITING EXTENSIONS</a></h1>

<p>The <a href="#SYNOPSIS" class="podlinkpod"
>&#34;SYNOPSIS&#34;</a> above gives a pretty good overview of what&#39;s basically required to write an extension. This section gives more information on exactly how extensions work and how you write them. There is also a <a href="https://wiki.mozilla.org/Bugzilla:Extension_Notes" class="podlinkurl"
>wiki page</a> with additional HOWTOs, tips and tricks.</p>

<h2><a class='u' href='#___top' title='click to go to top of document'
name="Using_extensions/create.pl"
>Using <em  class="code">extensions/create.pl</em></a></h2>

<p>There is a script, <a href="../extensions/create.html" class="podlinkpod"
>extensions::create</a>, that will set up the framework of a new extension for you. To use it, pick a name for your extension and, in the base bugzilla directory, do:</p>

<p><code  class="code">extensions/create.pl NAME</code></p>

<p>But replace <code  class="code">NAME</code> with the name you picked for your extension. That will create a new directory in the <em  class="code">extensions/</em> directory with the name of your extension. The directory will contain a full framework for a new extension, with helpful comments in each file describing things about them.</p>

<h2><a class='u' href='#___top' title='click to go to top of document'
name="Example_Extension"
>Example Extension</a></h2>

<p>There is a sample extension in <em  class="code">extensions/Example/</em> that demonstrates most of the things described in this document, so if you find the documentation confusing, try just reading the code instead.</p>

<h2><a class='u' href='#___top' title='click to go to top of document'
name="Where_Extension_Code_Goes"
>Where Extension Code Goes</a></h2>

<p>Extension code lives under the <em  class="code">extensions/</em> directory in Bugzilla.</p>

<p>There are two ways to write extensions:</p>

<ol>
<li>If your extension will have only code and no templates or other files, you can create a simple <code  class="code">.pm</code> file in the <em  class="code">extensions/</em> directory.
<p>For example, if you wanted to create an extension called &#34;Foo&#34; using this method, you would put your code into a file called <em  class="code">extensions/Foo.pm</em>.</p>
</li>

<li>If you plan for your extension to have templates and other files, you can create a whole directory for your extension, and the main extension code would go into a file called <em  class="code">Extension.pm</em> in that directory.
<p>For example, if you wanted to create an extension called &#34;Foo&#34; using this method, you would put your code into a file called <em  class="code">extensions/Foo/Extension.pm</em>.</p>
</li>
</ol>

<h2><a class='u' href='#___top' title='click to go to top of document'
name="The_Extension_NAME."
>The Extension <code  class="code">NAME</code>.</a></h2>

<p>The &#34;name&#34; of an extension shows up in several places:</p>

<ol>
<li>The name of the package:
<p><code  class="code">package Bugzilla::Extension::Foo;</code></p>
</li>

<li>In a <code  class="code">NAME</code> constant that <b>must</b> be defined for every extension:
<p><code  class="code">use constant NAME =&#62; &#39;Foo&#39;;</code></p>
</li>

<li>At the very end of the file:
<p><code  class="code">__PACKAGE__-&#62;NAME;</code></p>

<p>You&#39;ll notice that though most Perl packages end with <code  class="code">1;</code>, Bugzilla Extensions must <b>always</b> end with <code  class="code">__PACKAGE__-&#62;NAME;</code>.</p>
</li>
</ol>

<p>The name must be identical in all of those locations.</p>

<h2><a class='u' href='#___top' title='click to go to top of document'
name="Hooks"
>Hooks</a></h2>

<p>In <a href="../Bugzilla/Hook.html" class="podlinkpod"
>Bugzilla::Hook</a>, there is a <a href="../Bugzilla/Hook.html#HOOKS" class="podlinkpod"
>list of hooks</a>. These are the various areas of Bugzilla that an extension can &#34;hook&#34; into, which allow your extension to perform code during that point in Bugzilla&#39;s execution.</p>

<p>If your extension wants to implement a hook, all you have to do is write a subroutine in your hook package that has the same name as the hook. The subroutine will be called as a method on your extension, and it will get the arguments specified in the hook&#39;s documentation as named parameters in a hashref.</p>

<p>For example, here&#39;s an implementation of a hook named <code  class="code">foo_start</code> that gets an argument named <code  class="code">bar</code>:</p>

<pre  class="code"> sub foo_start {
     my ($self, $args) = @_;
     my $bar = $args-&#62;{bar};
     print &#34;I got $bar!\n&#34;;
 }</pre>

<p>And that would go into your extension&#39;s code file--the file that was described in the <a href="#Where_Extension_Code_Goes" class="podlinkpod"
>&#34;Where Extension Code Goes&#34;</a> section above.</p>

<p>During your subroutine, you may want to know what values were passed as CGI arguments to the current script, or what arguments were passed to the current WebService method. You can get that data via <a href="../Bugzilla.html#input_params" class="podlinkpod"
>&#34;input_params&#34; in Bugzilla</a>.</p>

<h3><a class='u' href='#___top' title='click to go to top of document'
name="Adding_New_Hooks_To_Bugzilla"
>Adding New Hooks To Bugzilla</a></h3>

<p>If you need a new hook for your extension and you want that hook to be added to Bugzilla itself, see our development process at <a href="http://wiki.mozilla.org/Bugzilla:Developers" class="podlinkurl"
>http://wiki.mozilla.org/Bugzilla:Developers</a>.</p>

<p>In order for a new hook to be accepted into Bugzilla, it has to work, it must have documentation in <a href="../Bugzilla/Hook.html" class="podlinkpod"
>Bugzilla::Hook</a>, and it must have example code in <em  class="code">extensions/Example/Extension.pm</em>.</p>

<p>One question that is often asked about new hooks is, &#34;Is this the most flexible way to implement this hook?&#34; That is, the more power extension authors get from a hook, the more likely it is to be accepted into Bugzilla. Hooks that only hook a very specific part of Bugzilla will not be accepted if their functionality can be accomplished equally well with a more generic hook.</p>

<h2><a class='u' href='#___top' title='click to go to top of document'
name="If_Your_Extension_Requires_Certain_Perl_Modules"
>If Your Extension Requires Certain Perl Modules</a></h2>

<p>If there are certain Perl modules that your extension requires in order to run, there is a way you can tell Bugzilla this, and then <a href="../checksetup.html" class="podlinkpod"
>checksetup</a> will make sure that those modules are installed, when you run <a href="../checksetup.html" class="podlinkpod"
>checksetup</a>.</p>

<p>To do this, you need to specify a constant called <code  class="code">REQUIRED_MODULES</code> in your extension. This constant has the same format as <a href="../Bugzilla/Install/Requirements.html#REQUIRED_MODULES" class="podlinkpod"
>&#34;REQUIRED_MODULES&#34; in Bugzilla::Install::Requirements</a>.</p>

<p>If there are optional modules that add additional functionality to your application, you can specify them in a constant called OPTIONAL_MODULES, which has the same format as <a href="../Bugzilla/Install/Requirements.html#OPTIONAL_MODULES" class="podlinkpod"
>&#34;OPTIONAL_MODULES&#34; in Bugzilla::Install::Requirements</a>.</p>

<h3><a class='u' href='#___top' title='click to go to top of document'
name="If_Your_Extension_Needs_Certain_Modules_In_Order_To_Compile"
>If Your Extension Needs Certain Modules In Order To Compile</a></h3>

<p>If your extension needs a particular Perl module in order to <i>compile</i>, then you have a &#34;chicken and egg&#34; problem--in order to read <code  class="code">REQUIRED_MODULES</code>, we have to compile your extension. In order to compile your extension, we need to already have the modules in <code  class="code">REQUIRED_MODULES</code>!</p>

<p>To get around this problem, Bugzilla allows you to have an additional file, besides <em  class="code">Extension.pm</em>, called <em  class="code">Config.pm</em>, that contains just <code  class="code">REQUIRED_MODULES</code>. If you have a <em  class="code">Config.pm</em>, it must also contain the <code  class="code">NAME</code> constant, instead of your main <em  class="code">Extension.pm</em> containing the <code  class="code">NAME</code> constant.</p>

<p>The contents of the file would look something like this for an extension named <code  class="code">Foo</code>:</p>

<pre  class="code">  package Bugzilla::Extension::Foo;
  use strict;
  use constant NAME =&#62; &#39;Foo&#39;;
  use constant REQUIRED_MODULES =&#62; [
    {
      package =&#62; &#39;Some-Package&#39;,
      module  =&#62; &#39;Some::Module&#39;,
      version =&#62; 0,
    }
  ];
  __PACKAGE__-&#62;NAME;</pre>

<p>Note that it is <i>not</i> a subclass of <code  class="code">Bugzilla::Extension</code>, because at the time that module requirements are being checked in <a href="../checksetup.html" class="podlinkpod"
>checksetup</a>, <code  class="code">Bugzilla::Extension</code> cannot be loaded. Also, just like <em  class="code">Extension.pm</em>, it ends with <code  class="code">__PACKAGE__-&#62;NAME;</code>. Note also that it has the <b>exact same</b> <code  class="code">package</code> name as <em  class="code">Extension.pm</em>.</p>

<p>This file may not use any Perl modules other than <a href="../Bugzilla/Constants.html" class="podlinkpod"
>Bugzilla::Constants</a>, <a href="../Bugzilla/Install/Util.html" class="podlinkpod"
>Bugzilla::Install::Util</a>, <a href="../Bugzilla/Install/Requirements.html" class="podlinkpod"
>Bugzilla::Install::Requirements</a>, and modules that ship with Perl itself.</p>

<p>If you want to define both <code  class="code">REQUIRED_MODULES</code> and <code  class="code">OPTIONAL_MODULES</code>, they must both be in <em  class="code">Config.pm</em> or both in <em  class="code">Extension.pm</em>.</p>

<p>Every time your extension is loaded by Bugzilla, <em  class="code">Config.pm</em> will be read and then <em  class="code">Extension.pm</em> will be read, so your methods in <em  class="code">Extension.pm</em> will have access to everything in <em  class="code">Config.pm</em>. Don&#39;t define anything with an identical name in both files, or Perl may throw a warning that you are redefining things.</p>

<p>This method of setting <code  class="code">REQUIRED_MODULES</code> is of course not available if your extension is a single file named <code  class="code">Foo.pm</code>.</p>

<p>If any of this is confusing, just look at the code of the Example extension. It uses this method to specify requirements.</p>

<h2><a class='u' href='#___top' title='click to go to top of document'
name="Libraries"
>Libraries</a></h2>

<p>Extensions often want to have their own Perl modules. Your extension can load any Perl module in its <em  class="code">lib/</em> directory. (So, if your extension is <em  class="code">extensions/Foo/</em>, then your Perl modules go into <em  class="code">extensions/Foo/lib/</em>.)</p>

<p>However, the <code  class="code">package</code> name of your libraries will not work quite like normal Perl modules do. <em  class="code">extensions/Foo/lib/Bar.pm</em> is loaded as <code  class="code">Bugzilla::Extension::Foo::Bar</code>. Or, to say it another way, <code  class="code">use Bugzilla::Extension::Foo::Bar;</code> loads <em  class="code">extensions/Foo/lib/Bar.pm</em>, which should have <code  class="code">package Bugzilla::Extension::Foo::Bar;</code> as its package name.</p>

<p>This allows any place in Bugzilla to load your modules, which is important for some hooks. It even allows other extensions to load your modules, and allows you to install your modules into the global Perl install as <em  class="code">Bugzilla/Extension/Foo/Bar.pm</em>, if you&#39;d like, which helps allow CPAN distribution of Bugzilla extensions.</p>

<p><b>Note:</b> If you want to <code  class="code">use</code> or <code  class="code">require</code> a module that&#39;s in <em  class="code">extensions/Foo/lib/</em> at the top level of your <em  class="code">Extension.pm</em>, you must have a <em  class="code">Config.pm</em> (see above) with at least the <code  class="code">NAME</code> constant defined in it.</p>

<h2><a class='u' href='#___top' title='click to go to top of document'
name="Templates"
>Templates</a></h2>

<p>Extensions store templates in a <code  class="code">template</code> subdirectory of the extension. (Obviously, this isn&#39;t available for extensions that aren&#39;t a directory.)</p>

<p>The format of this directory is exactly like the normal layout of Bugzilla&#39;s <code  class="code">template</code> directory--in fact, your extension&#39;s <code  class="code">template</code> directory becomes part of Bugzilla&#39;s template &#34;search path&#34; as described in <a href="../Bugzilla/Install/Util.html#template_include_path" class="podlinkpod"
>&#34;template_include_path&#34; in Bugzilla::Install::Util</a>.</p>

<p>You can actually include templates in your extension without having any <code  class="code">.pm</code> files in your extension at all, if you want. (That is, it&#39;s entirely valid to have an extension that&#39;s just template files and no code files.)</p>

<p>Bugzilla&#39;s templates are written in a language called Template Toolkit. You can find out more about Template Toolkit at <a href="http://template-toolkit.org" class="podlinkurl"
>http://template-toolkit.org</a>.</p>

<p>There are two ways to extend or modify Bugzilla&#39;s templates: you can use template hooks (described below) or you can override existing templates entirely (described further down).</p>

<h2><a class='u' href='#___top' title='click to go to top of document'
name="Template_Hooks"
>Template Hooks</a></h2>

<p>Templates can be extended using a system of &#34;hooks&#34; that add new UI elements to a particular area of Bugzilla without modifying the code of the existing templates. This is the recommended way for extensions to modify the user interface of Bugzilla.</p>

<h3><a class='u' href='#___top' title='click to go to top of document'
name="Which_Templates_Can_Be_Hooked"
>Which Templates Can Be Hooked</a></h3>

<p>There is no list of template hooks like there is for standard code hooks. To find what places in the user interface can be hooked, search for the string <code  class="code">Hook.process</code> in Bugzilla&#39;s templates (in the <em  class="code">template/en/default/</em> directory). That will also give you the name of the hooks--the first argument to <code  class="code">Hook.process</code> is the name of the hook. (A later section in this document explains how to use that name).</p>

<p>For example, if you see <code  class="code">Hook.process(&#34;additional_header&#34;)</code>, that means the name of the hook is <code  class="code">additional_header</code>.</p>

<h3><a class='u' href='#___top' title='click to go to top of document'
name="Where_Template_Hooks_Go"
>Where Template Hooks Go</a></h3>

<p>To extend templates in your extension using template hooks, you put files into the <em  class="code">template/en/default/hook</em> directory of your extension. So, if you had an extension called &#34;Foo&#34;, your template extensions would go into <em  class="code">extensions/Foo/template/en/default/hook/</em>.</p>

<p>(Note that the base <em  class="code">template/en/default/hook</em> directory in Bugzilla itself also works, although you would never use that for an extension that you intended to distribute.)</p>

<p>The files that go into this directory have a certain name, based on the name of the template that is being hooked, and the name of the hook. For example, let&#39;s imagine that you have an extension named &#34;Foo&#34;, and you want to use the <code  class="code">additional_header</code> hook in <em  class="code">template/en/default/global/header.html.tmpl</em>. Your code would go into <em  class="code">extensions/Foo/template/en/default/hook/global/header-additional_header.html.tmpl</em>. Any code you put into that file will happen at the point that <code  class="code">Hook.process(&#34;additional_header&#34;)</code> is called in <em  class="code">template/en/default/global/header.html.tmpl</em>.</p>

<p>As you can see, template extension file names follow a pattern. The pattern looks like:</p>

<pre  class="code"> &#60;templates&#62;/hook/&#60;template path&#62;/&#60;template name&#62;-&#60;hook name&#62;.&#60;template type&#62;.tmpl</pre>

<dl>
<dt><a name="&#60;templates&#62;"
>&#60;templates&#62;</a></dt>

<dd>
<p>This is the full path to the template directory, like <em  class="code">extensions/Foo/template/en/default</em>. This works much like normal templates do, in the sense that template extensions in <code  class="code">custom</code> override template extensions in <code  class="code">default</code> for your extension, templates for different languages can be supplied, etc. Template extensions are searched for and run in the order described in <a href="../Bugzilla/Install/Util.html#template_include_path" class="podlinkpod"
>&#34;template_include_path&#34; in Bugzilla::Install::Util</a>.</p>

<p>The difference between normal templates and template hooks is that hooks will be run for <i>every</i> extension, whereas for normal templates, Bugzilla just takes the first one it finds and stops searching. So while a template extension in the <code  class="code">custom</code> directory may override the same-named template extension in the <code  class="code">default</code> directory <i>within your Bugzilla extension</i>, it will not override the same-named template extension in the <code  class="code">default</code> directory of another Bugzilla extension.</p>

<dt><a name="&#60;template_path&#62;"
>&#60;template path&#62;</a></dt>

<dd>
<p>This is the part of the path (excluding the filename) that comes after <em  class="code">template/en/default/</em> in a template&#39;s path. So, for <em  class="code">template/en/default/global/header.html.tmpl</em>, this would simply be <code  class="code">global</code>.</p>

<dt><a name="&#60;template_name&#62;"
>&#60;template name&#62;</a></dt>

<dd>
<p>This is the file name of the template, before the <code  class="code">.html.tmpl</code> part. So, for <em  class="code">template/en/default/global/header.html.tmpl</em>, this would be <code  class="code">header</code>.</p>

<dt><a name="&#60;hook_name&#62;"
>&#60;hook name&#62;</a></dt>

<dd>
<p>This is the name of the hook--what you saw in <code  class="code">Hook.process</code> inside of the template you want to hook. In our example, this is <code  class="code">additional_header</code>.</p>

<dt><a name="&#60;template_type&#62;"
>&#60;template type&#62;</a></dt>

<dd>
<p>This is what comes after the template name but before <code  class="code">.tmpl</code> in the template&#39;s path. In most cases this is <code  class="code">html</code>, but sometimes it&#39;s <code  class="code">none</code>, <code  class="code">txt</code>, <code  class="code">js</code>, or various other formats, indicating what type of output the template has.</p>
</dd>
</dl>

<h3><a class='u' href='#___top' title='click to go to top of document'
name="Adding_New_Template_Hooks_to_Bugzilla"
>Adding New Template Hooks to Bugzilla</a></h3>

<p>Adding new template hooks is just like adding code hooks (see <a href="#Adding_New_Hooks_To_Bugzilla" class="podlinkpod"
>&#34;Adding New Hooks To Bugzilla&#34;</a>) except that you don&#39;t have to document them, and including example code is optional.</p>

<h2><a class='u' href='#___top' title='click to go to top of document'
name="Overriding_Existing_Templates"
>Overriding Existing Templates</a></h2>

<p>Sometimes you don&#39;t want to extend a template, you just want to replace it entirely with your extension&#39;s template, or you want to add an entirely new template to Bugzilla for your extension to use.</p>

<p>To replace the <em  class="code">template/en/default/global/banner.html.tmpl</em> template in an extension named &#34;Foo&#34;, create a file called <em  class="code">extensions/Foo/template/en/default/global/banner.html.tmpl</em>. Note that this is very similar to the path for a template hook, except that it excludes <em  class="code">hook/</em>, and the template is named <i>exactly</i> like the standard Bugzilla template.</p>

<p>You can also use this method to add entirely new templates. If you have an extension named &#34;Foo&#34;, and you add a file named <em  class="code">extensions/Foo/template/en/default/foo/bar.html.tmpl</em>, you can load that in your code using <code  class="code">$template-&#62;process(&#39;foo/bar.html.tmpl&#39;)</code>.</p>

<h3><a class='u' href='#___top' title='click to go to top of document'
name="A_Warning_About_Extensions_That_You_Want_To_Distribute"
>A Warning About Extensions That You Want To Distribute</a></h3>

<p>You should never override an existing Bugzilla template in an extension that you plan to distribute to others, because only one extension can override any given template, and which extension will &#34;win&#34; that war if there are multiple extensions installed is totally undefined.</p>

<p>However, adding new templates in an extension that you want to distribute is fine, though you have to be careful about how you name them, because any templates with an identical path and name (say, both called <em  class="code">global/stuff.html.tmpl</em>) will conflict. The usual way to work around this is to put all your custom templates into a template path that&#39;s named after your extension (since the name of your extension has to be unique anyway). So if your extension was named Foo, your custom templates would go into <em  class="code">extensions/Foo/template/en/default/foo/</em>. The only time that doesn&#39;t work is with the <code  class="code">page_before_template</code> extension, in which case your templates should probably be in a directory like <em  class="code">extensions/Foo/template/en/default/page/foo/</em> so as not to conflict with other pages that other extensions might add.</p>

<h2><a class='u' href='#___top' title='click to go to top of document'
name="CSS,_JavaScript,_and_Images"
>CSS, JavaScript, and Images</a></h2>

<p>If you include CSS, JavaScript, and images in your extension that are served directly to the user (that is, they&#39;re not read by a script and then printed--they&#39;re just linked directly in your HTML), they should go into the <em  class="code">web/</em> subdirectory of your extension.</p>

<p>So, for example, if you had a CSS file called <em  class="code">style.css</em> and your extension was called <em  class="code">Foo</em>, your file would go into <em  class="code">extensions/Foo/web/style.css</em>.</p>

<h2><a class='u' href='#___top' title='click to go to top of document'
name="Documenting_Extensions"
>Documenting Extensions</a></h2>

<p>Documentation goes in <em  class="code">extensions/Foo/docs/en/rst/</em>, if it&#39;s in English, or change &#34;en&#34; to something else if it&#39;s not. The user documentation index file must be called index-user.rst; the admin documentation must be called index-admin.rst. These will end up in the User Guide and the Administration Guide respectively. Both documentation types are optional. You can use various Sphinx constructs such as :toctree: or :include: to include further reST files if you need more than one page of docs.</p>

<p>When documenting extensions to the Bugzilla API, if your extension provides them, the index file would be <em  class="code">extensions/Foo/docs/en/rst/api/v1/index.rst</em>. When and if your API has more than one version, increment the version number. These docs will get included in the WebService API Reference.</p>

<h2><a class='u' href='#___top' title='click to go to top of document'
name="Disabling_Your_Extension"
>Disabling Your Extension</a></h2>

<p>If you want your extension to be totally ignored by Bugzilla (it will not be compiled or seen to exist at all), then create a file called <code  class="code">disabled</code> in your extension&#39;s directory. (If your extension is just a file, like <em  class="code">extensions/Foo.pm</em>, you cannot use this method to disable your extension, and will just have to remove it from the directory if you want to totally disable it.) Note that if you are running under mod_perl, you may have to restart your web server for this to take effect.</p>

<p>If you want your extension to be compiled and have <a href="../checksetup.html" class="podlinkpod"
>checksetup</a> check for its module pre-requisites, but you don&#39;t want the module to be used by Bugzilla, then you should make your extension&#39;s <a href="#enabled" class="podlinkpod"
>&#34;enabled&#34;</a> method return <code  class="code">0</code> or some false value.</p>

<h1><a class='u' href='#___top' title='click to go to top of document'
name="DISTRIBUTING_EXTENSIONS"
>DISTRIBUTING EXTENSIONS</a></h1>

<p>If you&#39;ve made an extension and you want to publish it, the first thing you&#39;ll want to do is package up your extension&#39;s code and then put a link to it in the appropriate section of <a href="http://wiki.mozilla.org/Bugzilla:Addons" class="podlinkurl"
>http://wiki.mozilla.org/Bugzilla:Addons</a>.</p>

<h2><a class='u' href='#___top' title='click to go to top of document'
name="Distributing_on_CPAN"
>Distributing on CPAN</a></h2>

<p>If you want a centralized distribution point that makes it easy for Bugzilla users to install your extension, it is possible to distribute your Bugzilla Extension through CPAN.</p>

<p>The details of making a standard CPAN module are too much to go into here, but a lot of it is covered in <a href="../perlmodlib.html" class="podlinkpod"
>perlmodlib</a> and on <a href="http://www.cpan.org/" class="podlinkurl"
>http://www.cpan.org/</a> among other places.</p>

<p>When you distribute your extension via CPAN, your <em  class="code">Extension.pm</em> should simply install itself as <em  class="code">Bugzilla/Extension/Foo.pm</em>, where <code  class="code">Foo</code> is the name of your module. You do not need a separate <em  class="code">Config.pm</em> file, because CPAN itself will handle installing the prerequisites of your module, so Bugzilla doesn&#39;t have to worry about it.</p>

<h3><a class='u' href='#___top' title='click to go to top of document'
name="Templates_in_extensions_distributed_on_CPAN"
>Templates in extensions distributed on CPAN</a></h3>

<p>If your extension is <em  class="code">/usr/lib/perl5/Bugzilla/Extension/Foo.pm</em>, then Bugzilla will look for templates in the directory <em  class="code">/usr/lib/perl5/Bugzilla/Extension/Foo/template/</em>.</p>

<p>You can change this behavior by overriding the <a href="#template_dir" class="podlinkpod"
>&#34;template_dir&#34;</a> or <a href="#package_dir" class="podlinkpod"
>&#34;package_dir&#34;</a> methods described lower down in this document.</p>

<h3><a class='u' href='#___top' title='click to go to top of document'
name="Using_an_extension_distributed_on_CPAN"
>Using an extension distributed on CPAN</a></h3>

<p>There is a file named <em  class="code">data/extensions/additional</em> in Bugzilla. This is a plain-text file. Each line is the name of a module, like <code  class="code">Bugzilla::Extension::Foo</code>. In addition to the extensions in the <em  class="code">extensions/</em> directory, each module listed in this file will be loaded as a Bugzilla Extension whenever Bugzilla loads or uses extensions.</p>

<h1><a class='u' href='#___top' title='click to go to top of document'
name="GETTING_HELP_WITH_WRITING_EXTENSIONS"
>GETTING HELP WITH WRITING EXTENSIONS</a></h1>

<p>If you are an extension author and you&#39;d like some assistance from other extension authors or the Bugzilla development team, you can use the normal support channels described at <a href="http://www.bugzilla.org/support/" class="podlinkurl"
>http://www.bugzilla.org/support/</a>.</p>

<h1><a class='u' href='#___top' title='click to go to top of document'
name="ADDITIONAL_CONSTANTS"
>ADDITIONAL CONSTANTS</a></h1>

<p>In addition to <code  class="code">NAME</code>, there are some other constants you might want to define:</p>

<h2><a class='u' href='#___top' title='click to go to top of document'
name="$VERSION"
><code  class="code">$VERSION</code></a></h2>

<p>This should be a string that describes what version of your extension this is. Something like <code  class="code">1.0</code>, <code  class="code">1.3.4</code> or a similar string.</p>

<p>There are no particular restrictions on the format of version numbers, but you should probably keep them to just numbers and periods, in the interest of other software that parses version numbers.</p>

<p>By default, this will be <code  class="code">undef</code> if you don&#39;t define it.</p>

<h1><a class='u' href='#___top' title='click to go to top of document'
name="SUBCLASS_METHODS"
>SUBCLASS METHODS</a></h1>

<p>In addition to hooks, there are a few methods that your extension can define to modify its behavior, if you want:</p>

<h2><a class='u' href='#___top' title='click to go to top of document'
name="Class_Methods"
>Class Methods</a></h2>

<p>These methods are called on your extension&#39;s class. (Like <code  class="code">Bugzilla::Extension::Foo-&#62;some_method</code>).</p>

<h3><a class='u' href='#___top' title='click to go to top of document'
name="new"
><code  class="code">new</code></a></h3>

<p>Once every request, this method is called on your extension in order to create an &#34;instance&#34; of it. (Extensions are treated like objects--they are instantiated once per request in Bugzilla, and then methods are called on the object.)</p>

<h2><a class='u' href='#___top' title='click to go to top of document'
name="Instance_Methods"
>Instance Methods</a></h2>

<p>These are called on an instantiated Extension object.</p>

<h3><a class='u' href='#___top' title='click to go to top of document'
name="enabled"
><code  class="code">enabled</code></a></h3>

<p>This should return <code  class="code">1</code> if this extension&#39;s hook code should be run by Bugzilla, and <code  class="code">0</code> otherwise.</p>

<h3><a class='u' href='#___top' title='click to go to top of document'
name="package_dir"
><code  class="code">package_dir</code></a></h3>

<p>This returns the directory that your extension is located in.</p>

<p>If this is an extension that was installed via CPAN, the directory will be the path to <em  class="code">Bugzilla/Extension/Foo/</em>, if <code  class="code">Foo.pm</code> is the name of your extension.</p>

<p>If you want to override this method, and you have a <em  class="code">Config.pm</em>, you must override this method in <em  class="code">Config.pm</em>.</p>

<h3><a class='u' href='#___top' title='click to go to top of document'
name="template_dir"
><code  class="code">template_dir</code></a></h3>

<p>The directory that your package&#39;s templates are in.</p>

<p>This defaults to the <code  class="code">template</code> subdirectory of the <a href="#package_dir" class="podlinkpod"
>&#34;package_dir&#34;</a>.</p>

<p>If you want to override this method, and you have a <em  class="code">Config.pm</em>, you must override this method in <em  class="code">Config.pm</em>.</p>

<h3><a class='u' href='#___top' title='click to go to top of document'
name="web_dir"
><code  class="code">web_dir</code></a></h3>

<p>The directory that your package&#39;s web related files are in, such as css and javascript.</p>

<p>This defaults to the <code  class="code">web</code> subdirectory of the <a href="#package_dir" class="podlinkpod"
>&#34;package_dir&#34;</a>.</p>

<p>If you want to override this method, and you have a <em  class="code">Config.pm</em>, you must override this method in <em  class="code">Config.pm</em>.</p>

<h3><a class='u' href='#___top' title='click to go to top of document'
name="lib_dir"
><code  class="code">lib_dir</code></a></h3>

<p>The directory where your extension&#39;s libraries are.</p>

<p>This defaults to the <code  class="code">lib</code> subdirectory of the <a href="#package_dir" class="podlinkpod"
>&#34;package_dir&#34;</a>.</p>

<p>If you want to override this method, and you have a <em  class="code">Config.pm</em>, you must override this method in <em  class="code">Config.pm</em>.</p>

<h1><a class='u' href='#___top' title='click to go to top of document'
name="BUGZILLA::EXTENSION_CLASS_METHODS"
>BUGZILLA::EXTENSION CLASS METHODS</a></h1>

<p>These are used internally by Bugzilla to load and set up extensions. If you are an extension author, you don&#39;t need to care about these.</p>

<h2><a class='u' href='#___top' title='click to go to top of document'
name="load"
><code  class="code">load</code></a></h2>

<p>Takes two arguments, the path to <em  class="code">Extension.pm</em> and the path to <em  class="code">Config.pm</em>, for an extension. Loads the extension&#39;s code packages into memory using <code  class="code">require</code>, does some sanity-checking on the extension, and returns the package name of the loaded extension.</p>

<h2><a class='u' href='#___top' title='click to go to top of document'
name="load_all"
><code  class="code">load_all</code></a></h2>

<p>Calls <a href="#load" class="podlinkpod"
>&#34;load&#34;</a> for every enabled extension installed into Bugzilla, and returns an arrayref of all the package names that were loaded.</p>

<h1><a class='u' href='#___top' title='click to go to top of document'
name="Methods_in_need_of_POD"
><b>Methods in need of POD</b></a></h1>

<dl>
<dt><a name="modify_inc"
>modify_inc</a></dt>

<dd>
<dt><a name="my_inc"
>my_inc</a></dt>
</dl>
<p class="backlinkbottom"><b><a name="___bottom" href="../index.html" title="All Documents">&lt;&lt;</a></b></p>

<!-- end doc -->

</body></html>