<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>5.5. Extensions — Bugzilla 5.0.4 documentation</title>
<link rel="stylesheet" href="../_static/bugzilla.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../',
VERSION: '5.0.4',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true,
SOURCELINK_SUFFIX: '.txt'
};
</script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<link rel="shortcut icon" href="../_static/favicon.ico"/>
<link rel="search" title="Search" href="../search.html" />
<link rel="next" title="5.6. APIs" href="apis.html" />
<link rel="prev" title="5.4. Templates" href="templates.html" />
</head>
<body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="apis.html" title="5.6. APIs"
accesskey="N">next</a></li>
<li class="right" >
<a href="templates.html" title="5.4. Templates"
accesskey="P">previous</a> |</li>
<li class="nav-item nav-item-0"><a href="../index.html">Bugzilla 5.0.4 documentation</a> »</li>
<li class="nav-item nav-item-1"><a href="index.html" accesskey="U">5. Integration and Customization Guide</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="extensions">
<span id="id1"></span><h1>5.5. Extensions<a class="headerlink" href="#extensions" title="Permalink to this headline">¶</a></h1>
<p>One of the best ways to customize Bugzilla is by using a Bugzilla
Extension. Extensions can modify both the code and UI of Bugzilla in a way
that can be distributed to other Bugzilla users and ported forward to future
versions of Bugzilla with minimal effort. We maintain a
<a class="reference external" href="https://wiki.mozilla.org/Bugzilla:Addons">list of available extensions</a>
written by other people on our wiki. You would need to
make sure that the extension in question works with your version of Bugzilla.</p>
<p>Or, you can write your own extension. See the <a class="reference external" href="../integrating/api/Bugzilla/Extension.html">Bugzilla Extension
documentation</a>
for the core documentation on how to do that. It would make sense to read
the section on <a class="reference internal" href="templates.html#templates"><span class="std std-ref">Templates</span></a>. There is also a sample extension in
<code class="file docutils literal"><span class="pre">$BUGZILLA_HOME/extensions/Example/</span></code> which gives examples of how to
use all the code hooks.</p>
<p>This section explains how to achieve some common tasks using the Extension APIs.</p>
<div class="section" id="adding-a-new-page-to-bugzilla">
<h2>5.5.1. Adding A New Page to Bugzilla<a class="headerlink" href="#adding-a-new-page-to-bugzilla" title="Permalink to this headline">¶</a></h2>
<p>There are occasions where it's useful to add a new page to Bugzilla which
has little or no relation to other pages, and perhaps doesn't use very much
Bugzilla data. A help page, or a custom report for example. The best mechanism
for this is to use <code class="file docutils literal"><span class="pre">page.cgi</span></code> and the <code class="docutils literal"><span class="pre">page_before_template</span></code> hook.</p>
</div>
<div class="section" id="altering-data-on-an-existing-page">
<h2>5.5.2. Altering Data On An Existing Page<a class="headerlink" href="#altering-data-on-an-existing-page" title="Permalink to this headline">¶</a></h2>
<p>The <code class="docutils literal"><span class="pre">template_before_process</span></code> hook can be used to tweak the data displayed
on a particular existing page, if you know what template is used. It has
access to all the template variables before they are passed to the templating
engine.</p>
</div>
<div class="section" id="adding-new-fields-to-bugs">
<h2>5.5.3. Adding New Fields To Bugs<a class="headerlink" href="#adding-new-fields-to-bugs" title="Permalink to this headline">¶</a></h2>
<p>To add new fields to a bug, you need to do the following:</p>
<ul>
<li><p class="first">Add an <code class="docutils literal"><span class="pre">install_update_db</span></code> hook to add the fields by calling
<code class="docutils literal"><span class="pre">Bugzilla::Field->create</span></code> (only if the field doesn't already exist).
Here's what it might look like for a single field:</p>
<div class="highlight-perl"><div class="highlight"><pre><span></span><span class="k">my</span> <span class="nv">$field</span> <span class="o">=</span> <span class="k">new</span> <span class="nn">Bugzilla::</span><span class="n">Field</span><span class="p">({</span> <span class="n">name</span> <span class="o">=></span> <span class="nv">$name</span> <span class="p">});</span>
<span class="k">return</span> <span class="k">if</span> <span class="nv">$field</span><span class="p">;</span>
<span class="nv">$field</span> <span class="o">=</span> <span class="nn">Bugzilla::Field</span><span class="o">-></span><span class="n">create</span><span class="p">({</span>
<span class="n">name</span> <span class="o">=></span> <span class="nv">$name</span><span class="p">,</span>
<span class="n">description</span> <span class="o">=></span> <span class="nv">$description</span><span class="p">,</span>
<span class="n">type</span> <span class="o">=></span> <span class="nv">$type</span><span class="p">,</span> <span class="c1"># From list in Constants.pm</span>
<span class="n">enter_bug</span> <span class="o">=></span> <span class="mi">0</span><span class="p">,</span>
<span class="n">buglist</span> <span class="o">=></span> <span class="mi">0</span><span class="p">,</span>
<span class="n">custom</span> <span class="o">=></span> <span class="mi">1</span><span class="p">,</span>
<span class="p">});</span>
</pre></div>
</div>
</li>
<li><p class="first">Push the name of the field onto the relevant arrays in the <code class="docutils literal"><span class="pre">bug_columns</span></code>
and <code class="docutils literal"><span class="pre">bug_fields</span></code> hooks.</p>
</li>
<li><p class="first">If you want direct accessors, or other functions on the object, you need to
add a BEGIN block to your Extension.pm:</p>
<div class="highlight-perl"><div class="highlight"><pre><span></span><span class="k">BEGIN</span> <span class="p">{</span>
<span class="o">*</span><span class="nn">Bugzilla::Bug::</span><span class="n">is_foopy</span> <span class="o">=</span> <span class="o">\&</span><span class="n">_bug_is_foopy</span><span class="p">;</span>
<span class="p">}</span>
<span class="o">...</span>
<span class="k">sub</span> <span class="nf">_bug_is_foopy</span> <span class="p">{</span>
<span class="k">return</span> <span class="nv">$_</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span><span class="o">-></span><span class="p">{</span><span class="s">'is_foopy'</span><span class="p">};</span>
<span class="p">}</span>
</pre></div>
</div>
</li>
<li><p class="first">You don't have to change <code class="docutils literal"><span class="pre">Bugzilla/DB/Schema.pm</span></code>.</p>
</li>
<li><p class="first">You can use <code class="docutils literal"><span class="pre">bug_end_of_create</span></code>, <code class="docutils literal"><span class="pre">bug_end_of_create_validators</span></code>, and
<code class="docutils literal"><span class="pre">bug_end_of_update</span></code> to create or update the values for your new field.</p>
</li>
</ul>
</div>
<div class="section" id="adding-new-fields-to-other-things">
<h2>5.5.4. Adding New Fields To Other Things<a class="headerlink" href="#adding-new-fields-to-other-things" title="Permalink to this headline">¶</a></h2>
<p>If you are adding the new fields to an object other than a bug, you need to
go a bit lower-level. With reference to the instructions above:</p>
<ul class="simple">
<li>In <code class="docutils literal"><span class="pre">install_update_db</span></code>, use <code class="docutils literal"><span class="pre">bz_add_column</span></code> instead</li>
<li>Push on the columns in <code class="docutils literal"><span class="pre">object_columns</span></code> and <code class="docutils literal"><span class="pre">object_update_columns</span></code>
instead of <code class="docutils literal"><span class="pre">bug_columns</span></code>.</li>
<li>Add validators for the values in <code class="docutils literal"><span class="pre">object_validators</span></code></li>
</ul>
<p>The process for adding accessor functions is the same.</p>
<p>You can use the hooks <code class="docutils literal"><span class="pre">object_end_of_create</span></code>,
<code class="docutils literal"><span class="pre">object_end_of_create_validators</span></code>, <code class="docutils literal"><span class="pre">object_end_of_set_all</span></code>, and
<code class="docutils literal"><span class="pre">object_end_of_update</span></code> to create or update the values for the new object
fields you have added. In the hooks you can check the object type being
operated on and skip any objects you don't care about. For example, if you
added a new field to the <code class="docutils literal"><span class="pre">products</span></code> table:</p>
<div class="highlight-perl"><div class="highlight"><pre><span></span><span class="k">sub</span> <span class="nf">object_end_of_create</span> <span class="p">{</span>
<span class="k">my</span> <span class="p">(</span><span class="nv">$self</span><span class="p">,</span> <span class="nv">$args</span><span class="p">)</span> <span class="o">=</span> <span class="nv">@_</span><span class="p">;</span>
<span class="k">my</span> <span class="nv">$class</span> <span class="o">=</span> <span class="nv">$args</span><span class="o">-></span><span class="p">{</span><span class="s">'class'</span><span class="p">};</span>
<span class="k">my</span> <span class="nv">$object</span> <span class="o">=</span> <span class="nv">$args</span><span class="o">-></span><span class="p">{</span><span class="s">'object'</span><span class="p">};</span>
<span class="k">if</span> <span class="p">(</span><span class="nv">$class</span><span class="o">-></span><span class="n">isa</span><span class="p">(</span><span class="s">'Bugzilla::Product'</span><span class="p">)</span> <span class="p">{</span>
<span class="p">[</span><span class="o">...</span><span class="p">]</span>
<span class="p">}</span>
<span class="p">}</span>
</pre></div>
</div>
<p>You will need to do this filtering for most of the hooks whose names begin with
<code class="docutils literal"><span class="pre">object_</span></code>.</p>
</div>
<div class="section" id="adding-admin-configuration-panels">
<h2>5.5.5. Adding Admin Configuration Panels<a class="headerlink" href="#adding-admin-configuration-panels" title="Permalink to this headline">¶</a></h2>
<p>If you add new functionality to Bugzilla, it may well have configurable
options or parameters. The way to allow an administrator to set those
is to add a new configuration panel.</p>
<p>As well as using the <code class="docutils literal"><span class="pre">config_add_panels</span></code> hook, you will need a template to
define the UI strings for the panel. See the templates in
<code class="file docutils literal"><span class="pre">template/en/default/admin/params</span></code> for examples, and put your own
template in <code class="file docutils literal"><span class="pre">template/en/default/admin/params</span></code> in your extension's
directory.</p>
<p>You can access param values from Templates using:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="p">[</span><span class="o">%</span> <span class="n">Param</span><span class="p">(</span><span class="s1">'param_name'</span><span class="p">)</span> <span class="o">%</span><span class="p">]</span>
</pre></div>
</div>
<p>and from code using:</p>
<div class="highlight-perl"><div class="highlight"><pre><span></span><span class="nn">Bugzilla</span><span class="o">-></span><span class="nn">params</span><span class="o">-></span><span class="p">{</span><span class="s">'param_name'</span><span class="p">}</span>
</pre></div>
</div>
</div>
<div class="section" id="adding-user-preferences">
<h2>5.5.6. Adding User Preferences<a class="headerlink" href="#adding-user-preferences" title="Permalink to this headline">¶</a></h2>
<p>To add a new user preference:</p>
<ul class="simple">
<li>Call <code class="docutils literal"><span class="pre">add_setting('setting_name',</span> <span class="pre">['some_option',</span> <span class="pre">'another_option'],</span>
<span class="pre">'some_option')</span></code> in the <code class="docutils literal"><span class="pre">install_before_final_checks</span></code> hook. (The last
parameter is the name of the option which should be the default.)</li>
<li>Add descriptions for the identifiers for your setting and choices
(setting_name, some_option etc.) to the hash defined in
<code class="file docutils literal"><span class="pre">global/setting-descs.none.tmpl</span></code>. Do this in a template hook:
<code class="file docutils literal"><span class="pre">hook/global/setting-descs-settings.none.tmpl</span></code>. Your code can see the
hash variable; just set more members in it.</li>
<li>To change behaviour based on the setting, reference it in templates using
<code class="docutils literal"><span class="pre">[%</span> <span class="pre">user.settings.setting_name.value</span> <span class="pre">%]</span></code>. Reference it in code using
<code class="docutils literal"><span class="pre">$user->settings->{'setting_name'}->{'value'}</span></code>. The value will be one of
the option tag names (e.g. some_option).</li>
</ul>
</div>
<div class="section" id="altering-who-can-change-what">
<span id="who-can-change-what"></span><h2>5.5.7. Altering Who Can Change What<a class="headerlink" href="#altering-who-can-change-what" title="Permalink to this headline">¶</a></h2>
<p>Companies often have rules about which employees, or classes of employees,
are allowed to change certain things in the bug system. For example,
only the bug's designated QA Contact may be allowed to VERIFY the bug.
Bugzilla has been
designed to make it easy for you to write your own custom rules to define
who is allowed to make what sorts of value transition.</p>
<p>By default, assignees, QA owners and users
with <em>editbugs</em> privileges can edit all fields of bugs,
except group restrictions (unless they are members of the groups they
are trying to change). Bug reporters also have the ability to edit some
fields, but in a more restrictive manner. Other users, without
<em>editbugs</em> privileges, cannot edit
bugs, except to comment and add themselves to the CC list.</p>
<p>Because this kind of change is such a common request, we have added a
specific hook for it that <a class="reference internal" href="#extensions"><span class="std std-ref">Extensions</span></a> can call. It's called
<code class="docutils literal"><span class="pre">bug_check_can_change_field</span></code>, and it's documented <a class="reference external" href="../integrating/api/Bugzilla/Hook.html#bug_check_can_change_field">in the Hooks
documentation</a>.</p>
</div>
<div class="section" id="checking-syntax">
<h2>5.5.8. Checking Syntax<a class="headerlink" href="#checking-syntax" title="Permalink to this headline">¶</a></h2>
<p>It's not immediately obvious how to check the syntax of your extension's
Perl modules, if it contains any. Running <strong class="command">checksetup.pl</strong> might do
some of it, but the errors aren't necessarily massively informative.</p>
<p><strong class="command">perl -Mlib=lib -MBugzilla -e 'BEGIN { Bugzilla->extensions; } use Bugzilla::Extension::ExtensionName::Class;'</strong></p>
<p>(run from <code class="docutils literal"><span class="pre">$BUGZILLA_HOME</span></code>) is what you need.</p>
<hr class="docutils" />
<p>This documentation undoubtedly has bugs; if you find some, please file
them <a class="reference external" href="https://bugzilla.mozilla.org/enter_bug.cgi?product=Bugzilla&component=Documentation">here</a>.</p>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<p class="logo"><a href="../index.html">
<img class="logo" src="../_static/bugzilla.png" alt="Logo"/>
</a></p>
<h3><a href="../index.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">5.5. Extensions</a><ul>
<li><a class="reference internal" href="#adding-a-new-page-to-bugzilla">5.5.1. Adding A New Page to Bugzilla</a></li>
<li><a class="reference internal" href="#altering-data-on-an-existing-page">5.5.2. Altering Data On An Existing Page</a></li>
<li><a class="reference internal" href="#adding-new-fields-to-bugs">5.5.3. Adding New Fields To Bugs</a></li>
<li><a class="reference internal" href="#adding-new-fields-to-other-things">5.5.4. Adding New Fields To Other Things</a></li>
<li><a class="reference internal" href="#adding-admin-configuration-panels">5.5.5. Adding Admin Configuration Panels</a></li>
<li><a class="reference internal" href="#adding-user-preferences">5.5.6. Adding User Preferences</a></li>
<li><a class="reference internal" href="#altering-who-can-change-what">5.5.7. Altering Who Can Change What</a></li>
<li><a class="reference internal" href="#checking-syntax">5.5.8. Checking Syntax</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="templates.html"
title="previous chapter">5.4. Templates</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="apis.html"
title="next chapter">5.6. APIs</a></p>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<form class="search" action="../search.html" method="get">
<div><input type="text" name="q" /></div>
<div><input type="submit" value="Go" /></div>
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="apis.html" title="5.6. APIs"
>next</a></li>
<li class="right" >
<a href="templates.html" title="5.4. Templates"
>previous</a> |</li>
<li class="nav-item nav-item-0"><a href="../index.html">Bugzilla 5.0.4 documentation</a> »</li>
<li class="nav-item nav-item-1"><a href="index.html" >5. Integration and Customization Guide</a> »</li>
</ul>
</div>
<div class="footer" role="contentinfo">
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.6.6.
</div>
</body>
</html>
distrib
>
Mageia
>
7
>
armv7hl
>
media
>
core-release
>
by-pkgid
>
4e237fd705495e1e21ef20696443e053
>
files
>
1158
