4.1. Template Customization
Administrators can 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. -
Templatization also makes localized versions of Bugzilla possible, - for the first time. It's possible to have Bugzilla's UI language - determined by the user's browser. More information is available in - Section 4.1.5. -
4.1.1. What to Edit
The template directory structure is that there's a top level directory, - template, which contains a directory for - each installed localization. The default English templates are - therefore in en. Underneath that, there - is the default directory and optionally the - custom directory. The default - directory contains all the templates shipped with Bugzilla, whereas - the custom directory does not exist at first and - must be created if you want to use it. -
There are two different ways of editing Bugzilla's templates, - and which you use depends mainly on the method you plan to use to - upgrade Bugzilla. - The first method of making customizations is to directly edit the - templates in template/en/default. This is - probably the best method for small changes if you are going to use - the CVS method of upgrading, because if you then execute a - cvs update, any template fixes will get - automagically merged into your modified versions. -
If you use this method, your installation will break if CVS conflicts - occur. -
The other method is to copy the templates to be modified into a - mirrored directory - structure under template/en/custom. The templates - in this directory automatically override those in default. - This is the technique you - need to use if you use the overwriting method of upgrade, because - otherwise your changes will be lost. This method is also better if - you are using the CVS method of upgrading and 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. -
If you use this method, your installation may break if incompatible - changes are made to the template interface. If such changes are made - they will be documented in the release notes, provided you are using a - stable release of Bugzilla. If you use using unstable code, you will - need to deal with this one yourself, although if possible the changes - will be mentioned before they occur in the deprecations section of the - previous stable release's release notes. -
Don't directly edit the compiled templates in - data/template/* - your - changes will be lost when Template Toolkit recompiles them. - |
It is recommended that you run ./checksetup.pl - after any template edits, especially if you've created a new file in - the custom directory. - |
4.1.2. How To Edit Templates
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. - |
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. -
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, ie <. You use the 'html' filter in the - Template Toolkit to do this. If you forget, you may open up - your installation to cross-site scripting attacks. -
Also note that Bugzilla adds a few filters of its own, that are not - in standard Template Toolkit. In particular, the 'url_quote' filter - can convert characters that are illegal or have special meaning in URLs, - such as &, to the encoded form, ie %26. This actually encodes most - characters (but not the common ones such as letters and numbers and so - on), including the HTML-special characters, so there's never a need to - HTML filter afterwards. -
Editing templates is a good way of doing a "poor man's custom fields". - For example, if you don't use the Status Whiteboard, but want to have - a free-form text entry box for "Build Identifier", then you can just - edit the templates to change the field labels. It's still be called - status_whiteboard internally, but your users don't need to know that. -
4.1.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 "GetFormat". If it's not present, adding - multiple format 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. 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> . -
4.1.4. 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. -
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/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. An example of this - is the mozilla.org - guided - bug submission form. -
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 use a format and - call it 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, also named - after your format if you are using one, 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"> |
BuildID: [% form.buildid %] |
BuildID: 20020303 |
4.1.5. Configuring Bugzilla to Detect the User's Language
Bugzilla honours the user's Accept: HTTP header. You can install - templates in other languages, and Bugzilla will pick the most appropriate - according to a priority order defined by you. Many - language templates can be obtained from http://www.bugzilla.org/download.html#localizations. Instructions - for submitting new languages are also available from that location. -
After untarring the localizations (or creating your own) in the - BUGZILLA_ROOT/template directory, - you must update the languages parameter to contain any - localizations you'd like to permit. You may also wish to set the - defaultlanguage parameter to something other than - "en" if you don't want Engish to be the default language. -