4
>Template Customisation</TITLE
7
CONTENT="Modular DocBook HTML Stylesheet Version 1.7"><LINK
9
TITLE="The Bugzilla Guide - 2.16.4 Release"
10
HREF="index.html"><LINK
12
TITLE="Administering Bugzilla"
13
HREF="administration.html"><LINK
15
TITLE="Bugzilla Security"
16
HREF="security.html"><LINK
18
TITLE="Upgrading to New Releases"
19
HREF="upgrading.html"></HEAD
30
SUMMARY="Header navigation table"
39
>The Bugzilla Guide - 2.16.4 Release</TH
55
>Chapter 5. Administering Bugzilla</TD
77
>5.7. Template Customisation</H1
79
> One of the large changes for 2.16 was the templatisation of the
80
entire user-facing UI, using the
82
HREF="http://www.template-toolkit.org"
86
Administrators can now configure the look and feel of Bugzilla without
87
having to edit Perl files or face the nightmare of massive merge
88
conflicts when they upgrade to a newer version in the future.
91
> Templatisation also makes localised versions of Bugzilla possible,
92
for the first time. In the future, a Bugzilla installation may
93
have templates installed for multiple localisations, and select
94
which ones to use based on the user's browser language setting.
103
>5.7.1. What to Edit</H2
105
> There are two different ways of editing of Bugzilla's templates,
106
and which you use depends mainly on how you upgrade Bugzilla. The
107
template directory structure is that there's a top level directory,
111
>, which contains a directory for
112
each installed localisation. The default English templates are
116
>. Underneath that, there
120
> directory and optionally the
128
directory contains all the templates shipped with Bugzilla, whereas
132
> directory does not exist at first and
133
must be created if you want to use it.
136
> The first method of making customisations is to directly edit the
139
>template/en/default</TT
141
probably the best method for small changes if you are going to use
142
the CVS method of upgrading, because if you then execute a
146
>, any template fixes will get
147
automagically merged into your modified versions.
150
> If you use this method, your installation will break if CVS conflicts
154
> The other method is to copy the templates into a mirrored directory
157
>template/en/custom</TT
159
in this directory automatically override those in default.
160
This is the technique you
161
need to use if you use the overwriting method of upgrade, because
162
otherwise your changes will be lost. This method is also better if
163
you are using the CVS method of upgrading and are going to make major
164
changes, because it is guaranteed that the contents of this directory
165
will not be touched during an upgrade, and you can then decide whether
166
to continue using your own templates, or make the effort to merge your
167
changes into the new versions by hand.
170
> If you use this method, your installation may break if incompatible
171
changes are made to the template interface. If such changes are made
172
they will be documented in the release notes, provided you are using a
173
stable release of Bugzilla. If you use using unstable code, you will
174
need to deal with this one yourself, although if possible the changes
175
will be mentioned before they occur in the deprecations section of the
176
previous stable release's release notes.
192
SRC="../images/note.gif"
199
> Don't directly edit the compiled templates in
204
changes will be lost when Template Toolkit recompiles them.
224
SRC="../images/note.gif"
231
>It is recommended that you run <B
235
after any template edits, especially if you've created a new file in
253
>5.7.2. How To Edit Templates</H2
255
> The syntax of the Template Toolkit language is beyond the scope of
256
this guide. It's reasonably easy to pick up by looking at the current
257
templates; or, you can read the manual, available on the
259
HREF="http://www.template-toolkit.org"
261
>Template Toolkit home
263
>. However, you should particularly remember (for security
264
reasons) to always HTML filter things which come from the database or
265
user input, to prevent cross-site scripting attacks.
268
> However, one thing you should take particular care about is the need
269
to properly HTML filter data that has been passed into the template.
270
This means that if the data can possibly contain special HTML characters
271
such as <, and the data was not intended to be HTML, they need to be
272
converted to entity form, ie &lt;. You use the 'html' filter in the
273
Template Toolkit to do this. If you fail to do this, you may open up
274
your installation to cross-site scripting attacks.
277
> Also note that Bugzilla adds a few filters of its own, that are not
278
in standard Template Toolkit. In particular, the 'url_quote' filter
279
can convert characters that are illegal or have special meaning in URLs,
280
such as &, to the encoded form, ie %26. This actually encodes most
281
characters (but not the common ones such as letters and numbers and so
282
on), including the HTML-special characters, so there's never a need to
283
HTML filter afterwards.
286
> Editing templates is a good way of doing a "poor man's custom fields".
287
For example, if you don't use the Status Whiteboard, but want to have
288
a free-form text entry box for "Build Identifier", then you can just
289
edit the templates to change the field labels. It's still be called
290
status_whiteboard internally, but your users don't need to know that.
306
SRC="../images/note.gif"
313
> If you are making template changes that you intend on submitting back
314
for inclusion in standard Bugzilla, you should read the relevant
317
HREF="http://www.bugzilla.org/developerguide.html"
335
>5.7.3. Template Formats</H2
337
> Some CGIs have the ability to use more than one template. For
338
example, buglist.cgi can output bug lists as RDF or two
339
different forms of HTML (complex and simple). (Try this out
342
>&format=simple</TT
344
URL on your Bugzilla installation.) This
345
mechanism, called template 'formats', is extensible.
348
> To see if a CGI supports multiple output formats, grep the
349
CGI for "ValidateOutputFormat". If it's not present, adding
350
multiple format support isn't too hard - see how it's done in
354
> To make a new format template for a CGI which supports this,
355
open a current template for
356
that CGI and take note of the INTERFACE comment (if present.) This
357
comment defines what variables are passed into this template. If
358
there isn't one, I'm afraid you'll have to read the template and
359
the code to find out what information you get.
362
> Write your template in whatever markup or text style is appropriate.
365
> You now need to decide what content type you want your template
366
served as. Open up the <TT
374
variable. If your content type is not there, add it. Remember
375
the three- or four-letter tag assigned to you content type.
376
This tag will be part of the template filename.
379
> Save the template as <TT
381
><stubname>-<formatname>.<contenttypetag>.tmpl</TT
383
Try out the template by calling the CGI as
386
><cginame>.cgi?format=<formatname></TT
397
>5.7.4. Particular Templates</H2
399
> There are a few templates you may be particularly interested in
400
customising for your installation.
407
This is the Bugzilla front page.
412
>global/header.html.tmpl</B
414
This defines the header that goes on all Bugzilla pages.
415
The header includes the banner, which is what appears to users
416
and is probably what you want to edit instead. However the
417
header also includes the HTML HEAD section, so you could for
418
example add a stylesheet or META tag by editing the header.
423
>global/banner.html.tmpl</B
425
This contains the "banner", the part of the header that appears
426
at the top of all Bugzilla pages. The default banner is reasonably
427
barren, so you'll probably want to customise this to give your
428
installation a distinctive look and feel. It is recommended you
429
preserve the Bugzilla version number in some form so the version
430
you are running can be determined, and users know what docs to read.
435
>global/footer.html.tmpl</B
437
This defines the footer that goes on all Bugzilla pages. Editing
438
this is another way to quickly get a distinctive look and feel for
439
your Bugzilla installation.
444
>bug/create/user-message.html.tmpl</B
446
This is a message that appears near the top of the bug reporting page.
447
By modifying this, you can tell your users how they should report
453
>bug/create/create.html.tmpl</B
457
>bug/create/comment.txt.tmpl</B
459
You may wish to get bug submitters to give certain bits of structured
460
information, each in a separate input widget, for which there is not a
461
field in the database. The bug entry system has been designed in an
462
extensible fashion to enable you to define arbitrary fields and widgets,
463
and have their values appear formatted in the initial
464
Description, rather than in database fields. An example of this
467
HREF="http://bugzilla.mozilla.org/enter_bug.cgi?format=guided"
470
bug submission form</A
474
> To make this work, create a custom template for
478
> (the default template, on which you
479
could base it, is <TT
481
>create.html.tmpl</TT
483
and either call it <TT
485
>create.html.tmpl</TT
486
> or use a format and
489
>create-<formatname>.html.tmpl</TT
493
>custom/bug/create</TT
495
directory. In it, add widgets for each piece of information you'd like
496
collected - such as a build number, or set of steps to reproduce.
499
> Then, create a template like
502
>custom/bug/create/comment.txt.tmpl</TT
504
after your format if you are using one, which
505
references the form fields you have created. When a bug report is
506
submitted, the initial comment attached to the bug report will be
507
formatted according to the layout of this template.
510
> For example, if your enter_bug template had a field
520
CLASS="programlisting"
521
><input type="text" name="buildid" size="30"></PRE
527
and then your comment.txt.tmpl had
537
CLASS="programlisting"
538
>BuildID: [% form.buildid %]</PRE
554
CLASS="programlisting"
555
>BuildID: 20020303</PRE
561
would appear in the initial checkin comment.
570
SUMMARY="Footer navigation table"
599
HREF="upgrading.html"
609
>Bugzilla Security</TD
615
HREF="administration.html"
623
>Upgrading to New Releases</TD
b'\\ No newline at end of file'
added
removed
docs/html/cust-templates.html
