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 extension to add or modify the behaviour
of templates using a stable interface.
Template Directory Structure
============================
The template directory structure starts with top level directory named
"template", which contains a directory for each installed
localization. Bugzilla comes with English templates, so the directory
name is "en", and we will discuss "template/en" throughout the
documentation. Below "template/en" is the "default" directory, which
contains all the standard templates shipped with Bugzilla.
Warning: A directory "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.
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.
1. You can directly edit the templates found in
"template/en/default".
2. You can copy the templates to be modified into a mirrored
directory structure under "template/en/custom". Templates in this
directory structure automatically override any identically-named
and identically-located templates in the "template/en/default"
directory. (The "custom" directory does not exist by default and
must be created if you want to use it.)
3. You can use the hooks built into many of the templates to add or
modify the UI from an 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 "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 "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, **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 **git diff**, which you
can't if you fork the file into the "custom" directory.
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 **./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 and Types
==========================
Some CGI's have the ability to use more than one template. For
example, "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
WebService API Reference 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.
"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 "Bugzilla/Constants.pm" file
in the "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
"<stubname>-<formatname>.<contenttypetag>.tmpl". Try out the template
by calling the CGI as "<cginame>.cgi?format=<formatname>". Add
"&ctype=<type>" if the type is not HTML.
Particular Templates
====================
There are a few templates you may be particularly interested in
customizing for your installation.
"index.html.tmpl":
This is the Bugzilla front page.
"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.
"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.
"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.
"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").
"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.
"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.
"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.
"bug/create/create.html.tmpl" and "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 "create-guided.html.tmpl" and
"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 "create-guided.html.tmpl", then
<input type="hidden" name="format" value="guided">
is used inside the form.
So to use this feature, create a custom template for
"enter_bug.cgi". The default template, on which you could base it,
is "default/bug/create/create.html.tmpl". Call it
"custom/bug/create/create-<formatname>.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
"default/bug/create/comment.txt.tmpl", and call it
"custom/bug/create/comment-<formatname>.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:
<input type="text" name="buildid" size="30">
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.
======================================================================
This documentation undoubtedly has bugs; if you find some, please file
them here.
