diff options
Diffstat (limited to 'docs/html/cust-templates.html')
| -rw-r--r-- | docs/html/cust-templates.html | 585 |
1 files changed, 585 insertions, 0 deletions
diff --git a/docs/html/cust-templates.html b/docs/html/cust-templates.html new file mode 100644 index 000000000..7987f2aba --- /dev/null +++ b/docs/html/cust-templates.html @@ -0,0 +1,585 @@ +<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 +>
\ No newline at end of file |