One of the large changes for 2.16 was the templatization of the - entire user-facing UI, using the - Template Toolkit. - Administrators can now configure the look and feel of Bugzilla without +> 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. As of version 2.17.4 which will soon - become 2.18, it's possible to have Bugzilla's language determined by - the user's browser. More information is available in + 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 5.7.5Section 6.1.5.
There are two different ways of editing of Bugzilla's templates, - and which you use depends mainly on how you upgrade Bugzilla. The - template directory structure is that there's a top level directory, +> The template directory structure is that there's a top level directory, template
The first method of making customizations is to directly edit the +> 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
The other method is to copy the templates into a mirrored directory +> The other method is to copy the templates to be modified into a + mirrored directory structure under template/en/custom
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. However, you should particularly remember (for security - reasons) to always HTML filter things which come from the database or - user input, to prevent cross-site scripting attacks. -
However, 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 fail to do this, 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. -
6.1.2. How To Edit TemplatesThe 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. +
Some CGIs have the ability to use more than one template. For example, buglist.cgi can output bug lists as RDF or two @@ -350,9 +345,9 @@ CLASS="filename"
To see if a CGI supports multiple output formats, grep the - CGI for "ValidateOutputFormat". If it's not present, adding + CGI for "GetFormat". If it's not present, adding multiple format support isn't too hard - see how it's done in - other CGIs. + other CGIs, e.g. config.cgi.
To make a new format template for a CGI which supports this, @@ -396,9 +391,9 @@ CLASS="section" >
There are a few templates you may be particularly interested in customizing for your installation. @@ -454,21 +449,6 @@ CLASS="command" >
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 5.7.5. Configuring Bugzilla to Detect the User's Language6.1.5. Configuring Bugzilla to Detect the User's Language
Begining in version 2.18 (first introduced in version
- 2.17.4), it's now possible to have the users web browser tell Bugzilla
- which language templates to use for each visitor (using the HTTP_ACCEPT
- header). For this to work, Bugzilla needs to have the correct language
- templates installed for the version of Bugzilla you are using. Many
+>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 After untarring the localizations (or creating your own) in the
[Bugzilla_Root]/template$BUGZILLA_HOME/template directory,
you must update the PrevBugzilla SecurityCustomising BugzillaUp Change Permission CustomizationCustomizing Who Can Change What