From d41a0a76217ebbfd18807128e8bd552d5276e87a Mon Sep 17 00:00:00 2001 From: Gervase Markham Date: Fri, 5 Dec 2014 16:52:48 -0500 Subject: Bug 1067416 - reorganize and update Bugzilla docs --- docs/en/rst/integrating/apis.rst | 72 ++++++++ docs/en/rst/integrating/extensions.rst | 199 +++++++++++++++++++++++ docs/en/rst/integrating/faq.rst | 27 +++ docs/en/rst/integrating/index.rst | 22 +++ docs/en/rst/integrating/languages.rst | 19 +++ docs/en/rst/integrating/skins.rst | 27 +++ docs/en/rst/integrating/templates.rst | 289 +++++++++++++++++++++++++++++++++ 7 files changed, 655 insertions(+) create mode 100644 docs/en/rst/integrating/apis.rst create mode 100644 docs/en/rst/integrating/extensions.rst create mode 100644 docs/en/rst/integrating/faq.rst create mode 100644 docs/en/rst/integrating/index.rst create mode 100644 docs/en/rst/integrating/languages.rst create mode 100644 docs/en/rst/integrating/skins.rst create mode 100644 docs/en/rst/integrating/templates.rst (limited to 'docs/en/rst/integrating') diff --git a/docs/en/rst/integrating/apis.rst b/docs/en/rst/integrating/apis.rst new file mode 100644 index 000000000..6067c12df --- /dev/null +++ b/docs/en/rst/integrating/apis.rst @@ -0,0 +1,72 @@ +.. _api-list: + +APIs +#### + +Bugzilla has a number of APIs that you can call in your code to extract +information from and put information into Bugzilla. Some are deprecated and +will soon be removed. Which one to use? Short answer: the +:ref:`REST WebService API v1 ` +should be used for all new integrations, but keep an eye out for version 2, +coming soon. + +The APIs currently available are as follows: + +Ad-Hoc APIs +=========== + +Various pages on Bugzilla are available in machine-parseable formats as well +as HTML. For example, bugs can be downloaded as XML, and buglists as CSV. +CSV is useful for spreadsheet import. There should be links on the HTML page +to alternate data formats where they are available. + +XML-RPC +======= + +Bugzilla has an `XML-RPC API +`_. +This will receive no further updates and will be removed in a future version +of Bugzilla. + +Endpoint: :file:`/xmlrpc.cgi` + +JSON-RPC +======== + +Bugzilla has a `JSON-RPC API +`_. +This will receive no further updates and will be removed in a future version +of Bugzilla. + +Endpoint: :file:`/jsonrpc.cgi` + +REST +==== + +Bugzilla has a :ref:`REST API ` which is the currently-recommended API +for integrating with Bugzilla. The current REST API is version 1. It is stable, +and so will not be changed in a backwardly-incompatible way. + +**This is the currently-recommended API for new development.** + +Endpoint: :file:`/rest` + +BzAPI/BzAPI-Compatible REST +=========================== + +The first ever REST API for Bugzilla was implemented using an external proxy +called `BzAPI `_. This became popular +enough that a BzAPI-compatible shim on top of the (native) REST API has been +written, to allow code which used the BzAPI API to take advantage of the +speed improvements of direct integration without needing to be rewritten. +The shim is an extension which you would need to install in your Bugzilla. + +Neither BzAPI nor this BzAPI-compatible API shim will receive any further +updates, and they should not be used for new code. + +REST v2 +======= + +The future of Bugzilla's APIs is version 2 of the REST API, which will take +the best of the current REST API and the BzAPI API. It is still under +development. diff --git a/docs/en/rst/integrating/extensions.rst b/docs/en/rst/integrating/extensions.rst new file mode 100644 index 000000000..2097909fc --- /dev/null +++ b/docs/en/rst/integrating/extensions.rst @@ -0,0 +1,199 @@ +.. _extensions: + +Extensions +########## + +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 +`list of available extensions `_ +written by other people on our wiki. You would need to +make sure that the extension in question works with your version of Bugzilla. + +Or, you can write your own extension. See the `Bugzilla Extension +documentation <../html/api/Bugzilla/Extension.html>`_ for the core +documentation on how to do that. It would make sense to read +the section on :ref:`templates`. There is also a sample extension in +:file:`$BUGZILLA_HOME/extensions/Example/` which gives examples of how to +use all the code hooks. + +This section explains how to achieve some common tasks using the Extension APIs. + +Adding A New Page to Bugzilla +============================= + +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 :file:`page.cgi` and the ``page_before_template`` hook. + +Altering Data On An Existing Page +================================= + +The ``template_before_process`` 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. + +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``. + +* You can use ``bug_end_of_create``, ``bug_end_of_create_validators``, and + ``bug_end_of_update`` to create or update the values for your new field. + +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. + +You can use the hooks ``object_end_of_create``, +``object_end_of_create_validators``, ``object_end_of_set_all``, and +``object_end_of_update`` 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 ``products`` table: + +.. code-block:: perl + + sub object_end_of_create { + my ($self, $args) = @_; + my $class = $args->{'class'}; + my $object = $args->{'object'}; + if ($class->isa('Bugzilla::Product') { + [...] + } + } + +You will need to do this filtering for most of the hooks whose names begin with +``object_``. + +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. + +You can access param values from Templates using:: + + [% Param('param_name') %] + +and from code using: + +.. code-block:: perl + + Bugzilla->params->{'param_name'} + +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 `_. + +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. + diff --git a/docs/en/rst/integrating/faq.rst b/docs/en/rst/integrating/faq.rst new file mode 100644 index 000000000..19f8b59ff --- /dev/null +++ b/docs/en/rst/integrating/faq.rst @@ -0,0 +1,27 @@ + +.. _customization-faq: + +Customization FAQ +================= + +How do I... + +...add a new field on a bug? + Use :ref:`custom-fields` or, if you just want new form fields on bug entry + but don't need Bugzilla to track the field seperately thereafter, you can + use a :ref:`custom bug entry form `. + +...change the name of a built-in bug field? + :ref:`Edit ` the relevant value in the template + :file:`template/en/default/global/field-descs.none.tmpl`. + +...use a word other than 'bug' to describe bugs? + :ref:`Edit or override ` the appropriate values in the template + :file:`template/en/default/global/variables.none.tmpl`. + +...call the system something other than 'Bugzilla'? + :ref:`Edit or override ` the appropriate value in the template + :file:`template/en/default/global/variables.none.tmpl`. + +...alter who can change what field when? + See :ref:`who-can-change-what`. diff --git a/docs/en/rst/integrating/index.rst b/docs/en/rst/integrating/index.rst new file mode 100644 index 000000000..816ffe8e5 --- /dev/null +++ b/docs/en/rst/integrating/index.rst @@ -0,0 +1,22 @@ +.. highlight:: perl + +.. _integrating: + +=================================== +Integration and Customization Guide +=================================== + +You may find that Bugzilla already does what you want it to do, you just +need to configure it correctly. Read the :ref:`administering` sections +carefully to see if that's the case for you. If not, then this chapter +explains how to use the available mechanisms for integration and customization. + +.. toctree:: + :maxdepth: 2 + + faq + languages + skins + templates + extensions + apis diff --git a/docs/en/rst/integrating/languages.rst b/docs/en/rst/integrating/languages.rst new file mode 100644 index 000000000..01586d3fe --- /dev/null +++ b/docs/en/rst/integrating/languages.rst @@ -0,0 +1,19 @@ +Languages +========= + +Bugzilla's templates can be localized, although it's a `big job +`_. If you have +a localized set of templates for your version of Bugzilla, Bugzilla can +support multiple languages at once. In that case, Bugzilla honours the user's +``Accept-Language`` HTTP header when deciding which language to serve. If +multiple languages are installed, a menu will display in the header allowing +the user to manually select a different language. If they do this, their +choice will override the ``Accept-Language`` header. + +Many language templates can be obtained from +`the localization section of the Bugzilla website +`_. Instructions +for submitting new languages are also available from that location. There's +also a `list of localization teams +`_; you might +want to contact someone to ask about the status of their localization. diff --git a/docs/en/rst/integrating/skins.rst b/docs/en/rst/integrating/skins.rst new file mode 100644 index 000000000..2cd08b4c0 --- /dev/null +++ b/docs/en/rst/integrating/skins.rst @@ -0,0 +1,27 @@ +.. _skins: + +Skins +===== + +Bugzilla supports skins - ways of changing the look of the UI without altering +its underlying structure. It ships with two - "Classic" and "Dusk". You can +find some more listed +`on the wiki `_, and there +are a couple more which are part of +`bugzilla.mozilla.org `_. +However, in each +case you may need to check that the skin supports the version of Bugzilla +you have. + +To create a new custom skin, make a directory that contains all the same CSS +file names as :file:`skins/standard/`, and put your directory in +:file:`skins/contrib/`. Then, add your CSS to the appropriate files. + +After you put the directory there, make sure to run :file:`checksetup.pl` so +that it can set the file permissions correctly. + +After you have installed the new skin, it will show up as an option in the +user's :guilabel:`Preferences`, on the :guilabel:`General` tab. If you would +like to force a particular skin on all users, just select that skin in the +:guilabel:`Default Preferences` in the :guilabel:`Administration` UI, and +then uncheck "Enabled" on the preference, so users cannot change it. diff --git a/docs/en/rst/integrating/templates.rst b/docs/en/rst/integrating/templates.rst new file mode 100644 index 000000000..f30b4a848 --- /dev/null +++ b/docs/en/rst/integrating/templates.rst @@ -0,0 +1,289 @@ +.. _templates: + +Templates +######### + +Bugzilla uses a system of templates to define its user interface. The standard +templates can be modified, replaced or overridden. You can also use template +hooks in an :ref:`extension ` to add or modify the +behaviour of templates using a stable interface. + +.. _template-directory: + +Template Directory Structure +============================ + +The template directory structure starts with top level directory +named :file:`template`, which contains a directory +for each installed localization. Bugzilla comes with English +templates, so the directory name is :file:`en`, +and we will discuss :file:`template/en` throughout +the documentation. Below :file:`template/en` is the +:file:`default` directory, which contains all the +standard templates shipped with Bugzilla. + +.. warning:: A directory :file:`data/template` also exists; + this is where Template Toolkit puts the compiled versions (i.e. Perl code) + of the templates. *Do not* directly edit the files in this + directory, or all your changes will be lost the next time + Template Toolkit recompiles the templates. + +.. _template-method: + +Choosing a Customization Method +=============================== + +If you want to edit Bugzilla's templates, the first decision +you must make is how you want to go about doing so. There are three +choices, and which you use depends mainly on the scope of your +modifications, and the method you plan to use to upgrade Bugzilla. + +#. You can directly edit the templates found in :file:`template/en/default`. + +#. You can copy the templates to be modified into a mirrored directory + structure under :file:`template/en/custom`. Templates in this + directory structure automatically override any identically-named + and identically-located templates in the + :file:`template/en/default` directory. (The :file:`custom` directory does + not exist by default and must be created if you want to use it.) + +#. You can use the hooks built into many of the templates to add or modify + the UI from an :ref:`extension `. Hooks generally don't go away + and have a stable interface. + +The third method is the best if there are hooks in the appropriate places +and the change you want to do is possible using hooks. It's not very easy +to modify existing UI using hooks; they are most commonly used for additions. +You can make modifications if you add JS code which then makes the +modifications when the page is loaded. You can remove UI by adding CSS to hide +it. + +Unlike code hooks, there is no requirement to document template hooks, so +you just have to open up the template and see (search for ``Hook.process``). + +If there are no hooks available, then the second method of customization +should be used if you are going to make major changes, because it is +guaranteed that the contents of the :file:`custom` directory will not be +touched during an upgrade, and you can then decide whether +to revert to the standard templates, continue using yours, or make the effort +to merge your changes into the new versions by hand. It's also good for +entirely new files, and for a few files like +:file:`bug/create/user-message.html.tmpl` which are designed to be entirely +replaced. + +Using the second method, your user interface may break if incompatible +changes are made to the template interface. Templates do change regularly +and so interface changes are not individually documented, and you would +need to work out what had changed and adapt your template accordingly. + +For minor changes, the convenience of the first method is hard to beat. When +you upgrade Bugzilla, :command:`git` will merge your changes into the new +version for you. On the downside, if the merge fails then Bugzilla will not +work properly until you have fixed the problem and re-integrated your code. + +Also, you can see what you've changed using :command:`git diff`, which you +can't if you fork the file into the :file:`custom` directory. + +.. _template-edit: + +How To Edit Templates +===================== + +.. note:: If you are making template changes that you intend on submitting + back for inclusion in standard Bugzilla, you should read the relevant + sections of the + `Developers' Guide `_. + +Bugzilla uses a templating system called Template Toolkit. The syntax of the +language is beyond the scope of this guide. It's reasonably easy to pick up by +looking at the current templates; or, you can read the manual, available on +the `Template Toolkit home page `_. + +One thing you should take particular care about is the need +to properly HTML filter data that has been passed into the template. +This means that if the data can possibly contain special HTML characters +such as ``<``, and the data was not intended to be HTML, they need to be +converted to entity form, i.e. ``<``. You use the ``html`` filter in the +Template Toolkit to do this (or the ``uri`` filter to encode special +characters in URLs). If you forget, you may open up your installation +to cross-site scripting attacks. + + +You should run :command:`./checksetup.pl` after editing any templates. Failure +to do so may mean either that your changes are not picked up, or that the +permissions on the edited files are wrong so the webserver can't read them. + +.. _template-formats: + +Template Formats and Types +========================== + +Some CGI's have the ability to use more than one template. For example, +:file:`buglist.cgi` can output itself as two formats of HTML (complex and +simple). Each of these is a separate template. The mechanism that provides +this feature is extensible - you can create new templates to add new formats. + +You might use this feature to e.g. add a custom bug entry form for a +particular subset of users or a particular type of bug. + +Bugzilla can also support different types of output - e.g. bugs are available +as HTML and as XML, and this mechanism is extensible also to add new content +types. However, instead of using such interfaces or enhancing Bugzilla to add +more, you would be better off using the :ref:`apis` to integrate with +Bugzilla. + +To see if a CGI supports multiple output formats and types, grep the +CGI for ``get_format``. If it's not present, adding +multiple format/type support isn't too hard - see how it's done in +other CGIs, e.g. :file:`config.cgi`. + +To make a new format template for a CGI which supports this, +open a current template for +that CGI and take note of the INTERFACE comment (if present.) This +comment defines what variables are passed into this template. If +there isn't one, I'm afraid you'll have to read the template and +the code to find out what information you get. + +Write your template in whatever markup or text style is appropriate. + +You now need to decide what content type you want your template +served as. The content types are defined in the +:file:`Bugzilla/Constants.pm` file in the :file:`contenttypes` +constant. If your content type is not there, add it. Remember +the three- or four-letter tag assigned to your content type. +This tag will be part of the template filename. + +Save your new template as +:file:`-..tmpl`. +Try out the template by calling the CGI as +``.cgi?format=``. Add ``&ctype=`` if the type is +not HTML. + +.. _template-specific: + +Particular Templates +==================== + +There are a few templates you may be particularly interested in +customizing for your installation. + +:file:`index.html.tmpl`: + This is the Bugzilla front page. + +:file:`global/header.html.tmpl`: + This defines the header that goes on all Bugzilla pages. + The header includes the banner, which is what appears to users + and is probably what you want to edit instead. However the + header also includes the HTML HEAD section, so you could for + example add a stylesheet or META tag by editing the header. + +:file:`global/banner.html.tmpl`: + This contains the ``banner``, the part of the header that appears + at the top of all Bugzilla pages. The default banner is reasonably + barren, so you'll probably want to customize this to give your + installation a distinctive look and feel. It is recommended you + preserve the Bugzilla version number in some form so the version + you are running can be determined, and users know what docs to read. + +:file:`global/footer.html.tmpl`: + This defines the footer that goes on all Bugzilla pages. Editing + this is another way to quickly get a distinctive look and feel for + your Bugzilla installation. + +:file:`global/variables.none.tmpl`: + This allows you to change the word 'bug' to something else (e.g. "issue") + throughout the interface, and also to change the name Bugzilla to something + else (e.g. "FooCorp Bug Tracker"). + +:file:`list/table.html.tmpl`: + This template controls the appearance of the bug lists created + by Bugzilla. Editing this template allows per-column control of + the width and title of a column, the maximum display length of + each entry, and the wrap behaviour of long entries. + For long bug lists, Bugzilla inserts a 'break' every 100 bugs by + default; this behaviour is also controlled by this template, and + that value can be modified here. + +:file:`bug/create/user-message.html.tmpl`: + This is a message that appears near the top of the bug reporting page. + By modifying this, you can tell your users how they should report + bugs. + +:file:`bug/process/midair.html.tmpl`: + This is the page used if two people submit simultaneous changes to the + same bug. The second person to submit their changes will get this page + to tell them what the first person did, and ask if they wish to + overwrite those changes or go back and revisit the bug. The default + title and header on this page read "Mid-air collision detected!" If + you work in the aviation industry, or other environment where this + might be found offensive (yes, we have true stories of this happening) + you'll want to change this to something more appropriate for your + environment. + +.. _custom-bug-entry: + +:file:`bug/create/create.html.tmpl` and :file:`bug/create/comment.txt.tmpl`: + You may not wish to go to the effort of creating custom fields in + Bugzilla, yet you want to make sure that each bug report contains + a number of pieces of important information for which there is not + a special field. The bug entry system has been designed in an + extensible fashion to enable you to add arbitrary HTML widgets, + such as drop-down lists or textboxes, to the bug entry page + and have their values appear formatted in the initial comment. + + An example of this is the `guided bug submission form + `_. + The code for this comes with the Bugzilla distribution as an example for + you to copy. It can be found in the files + :file:`create-guided.html.tmpl` and :file:`comment-guided.html.tmpl`. + + A hidden field that indicates the format should be added inside + the form in order to make the template functional. Its value should + be the suffix of the template filename. For example, if the file + is called :file:`create-guided.html.tmpl`, then + + :: + + + + is used inside the form. + + So to use this feature, create a custom template for + :file:`enter_bug.cgi`. The default template, on which you + could base it, is + :file:`default/bug/create/create.html.tmpl`. + Call it :file:`custom/bug/create/create-.html.tmpl`, and + in it, add form inputs for each piece of information you'd like + collected - such as a build number, or set of steps to reproduce. + + Then, create a template based on + :file:`default/bug/create/comment.txt.tmpl`, and call it + :file:`custom/bug/create/comment-.txt.tmpl`. + It needs a couple of lines of boilerplate at the top like this:: + + [% USE Bugzilla %] + [% cgi = Bugzilla.cgi % + + Then, this template can reference the form fields you have created using + the syntax ``[% cgi.param("field_name") %]``. When a bug report is + submitted, the initial comment attached to the bug report will be + formatted according to the layout of this template. + + For example, if your custom enter_bug template had a field:: + + + + and then your comment.txt.tmpl had:: + + [% USE Bugzilla %] + [% cgi = Bugzilla.cgi %] + Build Identifier: [%+ cgi.param("buildid") %] + + then something like:: + + Build Identifier: 20140303 + + would appear in the initial comment. + + This system allows you to gather structured data in bug reports without + the overhead and UI complexity of a large number of custom fields. -- cgit v1.2.3-24-g4f1b