5.7. Template Customisation

One of the large changes for 2.16 was the templatisation of the entire user-facing UI, using the Template Toolkit. Administrators can now configure the look and feel of Bugzilla without having to edit Perl files or face the nightmare of massive merge conflicts when they upgrade to a newer version in the future.

Templatisation also makes localised versions of Bugzilla possible, for the first time. In the future, a Bugzilla installation may have templates installed for multiple localisations, and select which ones to use based on the user's browser language setting.

5.7.1. What to Edit

There are several ways to take advantage of Bugzilla's templates, and which you use depends on what you want to do. The Bugzilla template directory structure is that there's a top level directory, template, which contains a directory for each installed localisation. The default English templates are therefore in en. Underneath that, there are two directories - default and custom. The default directory contains all the templates shipped with Bugzilla.

One method of making customisations is to directly edit the templates in template/en/default. This is probably the best method for small changes, because if you then execute a cvs update, any template fixes will get automagically merged into your modified versions.

The other method is to copy the templates into a mirrored directory structure under template/en/custom. This method is better if you are going to make major changes, because it is guaranteed that the contents of this directory will not be touched during an upgrade, and you can then decide whether to continue using your own templates, or make the effort to merge your changes into the new versions by hand.

The syntax of the Template Toolkit 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.

Note

Don't directly edit the compiled templates in data/template/* - your changes will be lost when Template Toolkit recompiles them.

5.7.2. Particular Templates

There are a few templates you may be particularly interested in customising for your installation.

global/header.html.tmpl and global/footer.html.tmpl: These define the header and footer that go on all Bugzilla pages. Editing these is a way to quickly get a distinctive look and feel for your Bugzilla installation.

bug/create/create.html.tmpl and bug/create/comment.txt.tmpl: You may wish to get bug submitters to give certain bits of structured information, each in a separate input widget, for which there is not a field in the database. The bug entry system has been designed in an extensible fashion to enable you to define arbitrary fields and widgets, and have their values appear formatted in the initial Description (rather than in database fields.)

To make this work, create a custom template for enter_bug.cgi (the default template, on which you could base it, is create.html.tmpl), and either call it create.html.tmpl or create-<formatname>.html.tmpl. Put it in the custom/bug/create directory. In it, add widgets for each piece of information you'd like collected - such as a build number, or set of steps to reproduce.

Then, create a template like custom/bug/create/comment.txt.tmpl, which references the form fields you have created. 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 enter_bug template had a field

        <input type="text" name="buildid" size="30">
        
and then your comment.txt.tmpl had

        BuildID: [% form.buildid %]
        
then

        BuildID: 20020303
        
would appear in the initial checkin comment.

5.7.3. Template Formats

Some CGIs have the ability to use more than one template. For example, buglist.cgi can output bug lists as RDF or two different forms of HTML (complex and simple). (Try this out by appending &format=simple to a buglist.cgi URL on your Bugzilla installation.) This mechanism, called template 'formats', is extensible.

To see if a CGI supports multiple output formats, grep the CGI for "ValidateOutputFormat". If it's not present, adding multiple format support isn't too hard - see how it's done in other CGIs.

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. Open up the localconfig file and find the $contenttypes variable. If your content type is not there, add it. Remember the three- or four-letter tag assigned to you content type. This tag will be part of the template filename.

Save the template as <stubname>-<formatname>.<contenttypetag>.tmpl. Try out the template by calling the CGI as <cginame>.cgi?format=<formatname> .