зеркало из https://github.com/mozilla/gecko-dev.git
585 строки
15 KiB
HTML
585 строки
15 KiB
HTML
<HTML
|
|
><HEAD
|
|
><TITLE
|
|
>Template Customisation</TITLE
|
|
><META
|
|
NAME="GENERATOR"
|
|
CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
|
|
"><LINK
|
|
REL="HOME"
|
|
TITLE="The Bugzilla Guide"
|
|
HREF="index.html"><LINK
|
|
REL="UP"
|
|
TITLE="Administering Bugzilla"
|
|
HREF="administration.html"><LINK
|
|
REL="PREVIOUS"
|
|
TITLE="Bugzilla Security"
|
|
HREF="security.html"><LINK
|
|
REL="NEXT"
|
|
TITLE="Upgrading to New Releases"
|
|
HREF="upgrading.html"></HEAD
|
|
><BODY
|
|
CLASS="section"
|
|
BGCOLOR="#FFFFFF"
|
|
TEXT="#000000"
|
|
LINK="#0000FF"
|
|
VLINK="#840084"
|
|
ALINK="#0000FF"
|
|
><DIV
|
|
CLASS="NAVHEADER"
|
|
><TABLE
|
|
SUMMARY="Header navigation table"
|
|
WIDTH="100%"
|
|
BORDER="0"
|
|
CELLPADDING="0"
|
|
CELLSPACING="0"
|
|
><TR
|
|
><TH
|
|
COLSPAN="3"
|
|
ALIGN="center"
|
|
>The Bugzilla Guide</TH
|
|
></TR
|
|
><TR
|
|
><TD
|
|
WIDTH="10%"
|
|
ALIGN="left"
|
|
VALIGN="bottom"
|
|
><A
|
|
HREF="security.html"
|
|
ACCESSKEY="P"
|
|
>Prev</A
|
|
></TD
|
|
><TD
|
|
WIDTH="80%"
|
|
ALIGN="center"
|
|
VALIGN="bottom"
|
|
>Chapter 5. Administering Bugzilla</TD
|
|
><TD
|
|
WIDTH="10%"
|
|
ALIGN="right"
|
|
VALIGN="bottom"
|
|
><A
|
|
HREF="upgrading.html"
|
|
ACCESSKEY="N"
|
|
>Next</A
|
|
></TD
|
|
></TR
|
|
></TABLE
|
|
><HR
|
|
ALIGN="LEFT"
|
|
WIDTH="100%"></DIV
|
|
><DIV
|
|
CLASS="section"
|
|
><H1
|
|
CLASS="section"
|
|
><A
|
|
NAME="cust-templates">5.7. Template Customisation</H1
|
|
><P
|
|
> One of the large changes for 2.16 was the templatisation of the
|
|
entire user-facing UI, using the
|
|
<A
|
|
HREF="http://www.template-toolkit.org"
|
|
TARGET="_top"
|
|
>Template Toolkit</A
|
|
>.
|
|
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.
|
|
</P
|
|
><P
|
|
> 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.
|
|
</P
|
|
><DIV
|
|
CLASS="section"
|
|
><H2
|
|
CLASS="section"
|
|
><A
|
|
NAME="AEN1539">5.7.1. What to Edit</H2
|
|
><P
|
|
> 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,
|
|
<TT
|
|
CLASS="filename"
|
|
>template</TT
|
|
>, which contains a directory for
|
|
each installed localisation. The default English templates are
|
|
therefore in <TT
|
|
CLASS="filename"
|
|
>en</TT
|
|
>. Underneath that, there
|
|
is the <TT
|
|
CLASS="filename"
|
|
>default</TT
|
|
> directory and optionally the
|
|
<TT
|
|
CLASS="filename"
|
|
>custom</TT
|
|
> directory. The <TT
|
|
CLASS="filename"
|
|
>default</TT
|
|
>
|
|
directory contains all the templates shipped with Bugzilla, whereas
|
|
the <TT
|
|
CLASS="filename"
|
|
>custom</TT
|
|
> directory does not exist at first and
|
|
must be created if you want to use it.
|
|
</P
|
|
><P
|
|
> The first method of making customisations is to directly edit the
|
|
templates in <TT
|
|
CLASS="filename"
|
|
>template/en/default</TT
|
|
>. 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
|
|
<B
|
|
CLASS="command"
|
|
>cvs update</B
|
|
>, any template fixes will get
|
|
automagically merged into your modified versions.
|
|
</P
|
|
><P
|
|
> If you use this method, your installation will break if CVS conflicts
|
|
occur.
|
|
</P
|
|
><P
|
|
> The other method is to copy the templates into a mirrored directory
|
|
structure under <TT
|
|
CLASS="filename"
|
|
>template/en/custom</TT
|
|
>. 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.
|
|
</P
|
|
><P
|
|
> 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.
|
|
</P
|
|
><DIV
|
|
CLASS="note"
|
|
><P
|
|
></P
|
|
><TABLE
|
|
CLASS="note"
|
|
WIDTH="100%"
|
|
BORDER="0"
|
|
><TR
|
|
><TD
|
|
WIDTH="25"
|
|
ALIGN="CENTER"
|
|
VALIGN="TOP"
|
|
><IMG
|
|
SRC="../images/note.gif"
|
|
HSPACE="5"
|
|
ALT="Note"></TD
|
|
><TD
|
|
ALIGN="LEFT"
|
|
VALIGN="TOP"
|
|
><P
|
|
> Don't directly edit the compiled templates in
|
|
<TT
|
|
CLASS="filename"
|
|
>data/template/*</TT
|
|
> - your
|
|
changes will be lost when Template Toolkit recompiles them.
|
|
</P
|
|
></TD
|
|
></TR
|
|
></TABLE
|
|
></DIV
|
|
></DIV
|
|
><DIV
|
|
CLASS="section"
|
|
><H2
|
|
CLASS="section"
|
|
><A
|
|
NAME="AEN1558">5.7.2. How To Edit Templates</H2
|
|
><P
|
|
> 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
|
|
<A
|
|
HREF="http://www.template-toolkit.org"
|
|
TARGET="_top"
|
|
>Template Toolkit home
|
|
page</A
|
|
>. 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.
|
|
</P
|
|
><P
|
|
> 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 &lt;. 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.
|
|
</P
|
|
><P
|
|
> 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.
|
|
</P
|
|
><P
|
|
> 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.
|
|
</P
|
|
><DIV
|
|
CLASS="note"
|
|
><P
|
|
></P
|
|
><TABLE
|
|
CLASS="note"
|
|
WIDTH="100%"
|
|
BORDER="0"
|
|
><TR
|
|
><TD
|
|
WIDTH="25"
|
|
ALIGN="CENTER"
|
|
VALIGN="TOP"
|
|
><IMG
|
|
SRC="../images/note.gif"
|
|
HSPACE="5"
|
|
ALT="Note"></TD
|
|
><TD
|
|
ALIGN="LEFT"
|
|
VALIGN="TOP"
|
|
><P
|
|
> 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
|
|
<A
|
|
HREF="http://www.bugzilla.org/developerguide.html"
|
|
TARGET="_top"
|
|
>Developers'
|
|
Guide</A
|
|
>.
|
|
</P
|
|
></TD
|
|
></TR
|
|
></TABLE
|
|
></DIV
|
|
></DIV
|
|
><DIV
|
|
CLASS="section"
|
|
><H2
|
|
CLASS="section"
|
|
><A
|
|
NAME="AEN1568">5.7.3. Template Formats</H2
|
|
><P
|
|
> 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 <TT
|
|
CLASS="filename"
|
|
>&format=simple</TT
|
|
> to a buglist.cgi
|
|
URL on your Bugzilla installation.) This
|
|
mechanism, called template 'formats', is extensible.
|
|
</P
|
|
><P
|
|
> 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.
|
|
</P
|
|
><P
|
|
> 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.
|
|
</P
|
|
><P
|
|
> Write your template in whatever markup or text style is appropriate.
|
|
</P
|
|
><P
|
|
> You now need to decide what content type you want your template
|
|
served as. Open up the <TT
|
|
CLASS="filename"
|
|
>localconfig</TT
|
|
> file and find the
|
|
<TT
|
|
CLASS="filename"
|
|
>$contenttypes</TT
|
|
>
|
|
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.
|
|
</P
|
|
><P
|
|
> Save the template as <TT
|
|
CLASS="filename"
|
|
><stubname>-<formatname>.<contenttypetag>.tmpl</TT
|
|
>.
|
|
Try out the template by calling the CGI as
|
|
<TT
|
|
CLASS="filename"
|
|
><cginame>.cgi?format=<formatname></TT
|
|
> .
|
|
</P
|
|
></DIV
|
|
><DIV
|
|
CLASS="section"
|
|
><H2
|
|
CLASS="section"
|
|
><A
|
|
NAME="AEN1581">5.7.4. Particular Templates</H2
|
|
><P
|
|
> There are a few templates you may be particularly interested in
|
|
customising for your installation.
|
|
</P
|
|
><P
|
|
> <B
|
|
CLASS="command"
|
|
>index.html.tmpl</B
|
|
>:
|
|
This is the Bugzilla front page.
|
|
</P
|
|
><P
|
|
> <B
|
|
CLASS="command"
|
|
>global/header.html.tmpl</B
|
|
>:
|
|
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.
|
|
</P
|
|
><P
|
|
> <B
|
|
CLASS="command"
|
|
>global/banner.html.tmpl</B
|
|
>:
|
|
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 customise 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.
|
|
</P
|
|
><P
|
|
> <B
|
|
CLASS="command"
|
|
>global/footer.html.tmpl</B
|
|
>:
|
|
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.
|
|
</P
|
|
><P
|
|
> <B
|
|
CLASS="command"
|
|
>bug/create/user-message.html.tmpl</B
|
|
>:
|
|
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.
|
|
</P
|
|
><P
|
|
> <B
|
|
CLASS="command"
|
|
>bug/create/create.html.tmpl</B
|
|
> and
|
|
<B
|
|
CLASS="command"
|
|
>bug/create/comment.txt.tmpl</B
|
|
>:
|
|
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
|
|
<A
|
|
HREF="http://bugzilla.mozilla.org/enter_bug.cgi?format=guided"
|
|
TARGET="_top"
|
|
>guided
|
|
bug submission form</A
|
|
>.
|
|
</P
|
|
><P
|
|
> To make this work, create a custom template for
|
|
<TT
|
|
CLASS="filename"
|
|
>enter_bug.cgi</TT
|
|
> (the default template, on which you
|
|
could base it, is <TT
|
|
CLASS="filename"
|
|
>create.html.tmpl</TT
|
|
>),
|
|
and either call it <TT
|
|
CLASS="filename"
|
|
>create.html.tmpl</TT
|
|
> or use a format and
|
|
call it <TT
|
|
CLASS="filename"
|
|
>create-<formatname>.html.tmpl</TT
|
|
>.
|
|
Put it in the <TT
|
|
CLASS="filename"
|
|
>custom/bug/create</TT
|
|
>
|
|
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.
|
|
</P
|
|
><P
|
|
> Then, create a template like
|
|
<TT
|
|
CLASS="filename"
|
|
>custom/bug/create/comment.txt.tmpl</TT
|
|
>, 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.
|
|
</P
|
|
><P
|
|
> For example, if your enter_bug template had a field
|
|
<TABLE
|
|
BORDER="0"
|
|
BGCOLOR="#E0E0E0"
|
|
WIDTH="100%"
|
|
><TR
|
|
><TD
|
|
><FONT
|
|
COLOR="#000000"
|
|
><PRE
|
|
CLASS="programlisting"
|
|
><input type="text" name="buildid" size="30"></PRE
|
|
></FONT
|
|
></TD
|
|
></TR
|
|
></TABLE
|
|
>
|
|
and then your comment.txt.tmpl had
|
|
<TABLE
|
|
BORDER="0"
|
|
BGCOLOR="#E0E0E0"
|
|
WIDTH="100%"
|
|
><TR
|
|
><TD
|
|
><FONT
|
|
COLOR="#000000"
|
|
><PRE
|
|
CLASS="programlisting"
|
|
>BuildID: [% form.buildid %]</PRE
|
|
></FONT
|
|
></TD
|
|
></TR
|
|
></TABLE
|
|
>
|
|
then
|
|
<TABLE
|
|
BORDER="0"
|
|
BGCOLOR="#E0E0E0"
|
|
WIDTH="100%"
|
|
><TR
|
|
><TD
|
|
><FONT
|
|
COLOR="#000000"
|
|
><PRE
|
|
CLASS="programlisting"
|
|
>BuildID: 20020303</PRE
|
|
></FONT
|
|
></TD
|
|
></TR
|
|
></TABLE
|
|
>
|
|
would appear in the initial checkin comment.
|
|
</P
|
|
></DIV
|
|
></DIV
|
|
><DIV
|
|
CLASS="NAVFOOTER"
|
|
><HR
|
|
ALIGN="LEFT"
|
|
WIDTH="100%"><TABLE
|
|
SUMMARY="Footer navigation table"
|
|
WIDTH="100%"
|
|
BORDER="0"
|
|
CELLPADDING="0"
|
|
CELLSPACING="0"
|
|
><TR
|
|
><TD
|
|
WIDTH="33%"
|
|
ALIGN="left"
|
|
VALIGN="top"
|
|
><A
|
|
HREF="security.html"
|
|
ACCESSKEY="P"
|
|
>Prev</A
|
|
></TD
|
|
><TD
|
|
WIDTH="34%"
|
|
ALIGN="center"
|
|
VALIGN="top"
|
|
><A
|
|
HREF="index.html"
|
|
ACCESSKEY="H"
|
|
>Home</A
|
|
></TD
|
|
><TD
|
|
WIDTH="33%"
|
|
ALIGN="right"
|
|
VALIGN="top"
|
|
><A
|
|
HREF="upgrading.html"
|
|
ACCESSKEY="N"
|
|
>Next</A
|
|
></TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
WIDTH="33%"
|
|
ALIGN="left"
|
|
VALIGN="top"
|
|
>Bugzilla Security</TD
|
|
><TD
|
|
WIDTH="34%"
|
|
ALIGN="center"
|
|
VALIGN="top"
|
|
><A
|
|
HREF="administration.html"
|
|
ACCESSKEY="U"
|
|
>Up</A
|
|
></TD
|
|
><TD
|
|
WIDTH="33%"
|
|
ALIGN="right"
|
|
VALIGN="top"
|
|
>Upgrading to New Releases</TD
|
|
></TR
|
|
></TABLE
|
|
></DIV
|
|
></BODY
|
|
></HTML
|
|
> |