5.4. 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.

5.4.1. 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.

5.4.2. 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.

5.4.3. 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. &lt;. 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.

5.4.4. 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.

5.4.5. 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.