139 lines
4.8 KiB
ReStructuredText
139 lines
4.8 KiB
ReStructuredText
.. _writing-extensions:
|
|
|
|
Writing Extensions
|
|
##################
|
|
|
|
See the `Bugzilla Extension
|
|
documentation <../html/api/Bugzilla/Extension.html>`_ for the core
|
|
documentation on how to write an Extension. It would make sense to read
|
|
the section on :ref:`templates`. This section explains how to achieve some
|
|
common tasks using the Extension APIs.
|
|
|
|
Adding New Fields To Bugs
|
|
=========================
|
|
|
|
To add new fields to a bug, you need to do the following:
|
|
|
|
* Add an ``install_update_db`` hook to add the fields by calling
|
|
``Bugzilla::Field->create`` (only if the field doesn't already exist).
|
|
Here's what it might look like for a single field:
|
|
|
|
.. code-block:: perl
|
|
|
|
my $field = new Bugzilla::Field({ name => $name });
|
|
return if $field;
|
|
|
|
$field = Bugzilla::Field->create({
|
|
name => $name,
|
|
description => $description,
|
|
type => $type, # From list in Constants.pm
|
|
enter_bug => 0,
|
|
buglist => 0,
|
|
custom => 1,
|
|
});
|
|
|
|
* Push the name of the field onto the relevant arrays in the ``bug_columns``
|
|
and ``bug_fields`` hooks.
|
|
|
|
* If you want direct accessors, or other functions on the object, you need to
|
|
add a BEGIN block to your Extension.pm:
|
|
|
|
.. code-block:: perl
|
|
|
|
BEGIN {
|
|
*Bugzilla::Bug::is_foopy = \&_bug_is_foopy;
|
|
}
|
|
|
|
...
|
|
|
|
sub _bug_is_foopy {
|
|
return $_[0]->{'is_foopy'};
|
|
}
|
|
|
|
* You don't have to change ``Bugzilla/DB/Schema.pm``.
|
|
|
|
Adding New Fields To Other Things
|
|
=================================
|
|
|
|
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:
|
|
|
|
* In ``install_update_db``, use ``bz_add_column`` instead
|
|
|
|
* Push on the columns in ``object_columns`` and ``object_update_columns``
|
|
instead of ``bug_columns``.
|
|
|
|
* Add validators for the values in ``object_validators``
|
|
|
|
The process for adding accessor functions is the same.
|
|
|
|
Adding Admin Configuration Panels
|
|
=================================
|
|
|
|
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.
|
|
|
|
As well as using the ``config_add_panels`` hook, you will need a template to
|
|
define the UI strings for the panel. See the templates in
|
|
:file:`template/en/default/admin/params` for examples, and put your own
|
|
template in :file:`template/en/default/admin/params` in your extension's
|
|
directory.
|
|
|
|
Adding User Preferences
|
|
=======================
|
|
|
|
To add a new user preference:
|
|
|
|
* Call ``add_setting('setting_name', ['some_option', 'another_option'],
|
|
'some_option')`` in the ``install_before_final_checks`` hook. (The last
|
|
parameter is the name of the option which should be the default.)
|
|
|
|
* Add descriptions for the identifiers for your setting and choices
|
|
(setting_name, some_option etc.) to the hash defined in
|
|
:file:`global/setting-descs.none.tmpl`. Do this in a template hook:
|
|
:file:`hook/global/setting-descs-settings.none.tmpl`. Your code can see the
|
|
hash variable; just set more members in it.
|
|
|
|
* To change behaviour based on the setting, reference it in templates using
|
|
``[% user.settings.setting_name.value %]``. Reference it in code using
|
|
``$user->settings->{'setting_name'}->{'value'}``. The value will be one of
|
|
the option tag names (e.g. some_option).
|
|
|
|
.. _who-can-change-what:
|
|
|
|
Altering Who Can Change What
|
|
============================
|
|
|
|
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.
|
|
|
|
By default, assignees, QA owners and users
|
|
with *editbugs* 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
|
|
*editbugs* privileges, cannot edit
|
|
bugs, except to comment and add themselves to the CC list.
|
|
|
|
Because this kind of change is such a common request, we have added a
|
|
specific hook for it that :ref:`extensions` can call. It's called
|
|
``bug_check_can_change_field``, and it's documented `in the Hooks
|
|
documentation <http://www.bugzilla.org/docs/tip/en/html/api/Bugzilla/Hook.html#bug_check_can_change_field>`_.
|
|
|
|
Checking Syntax
|
|
===============
|
|
|
|
It's not immediately obvious how to check the syntax of your extension's
|
|
Perl modules, if it contains any. Running :command:`checksetup.pl` might do
|
|
some of it, but the errors aren't necessarily massively informative.
|
|
|
|
:command:`perl -Mlib=lib -MBugzilla -e 'BEGIN { Bugzilla->extensions; } use Bugzilla::Extension::ExtensionName::Class;'`
|
|
|
|
(run from ``$BUGZILLA_HOME``) is what you need.
|
|
|