diff options
Diffstat (limited to 'docs/html/cust-templates.html')
| -rw-r--r-- | docs/html/cust-templates.html | 668 |
1 files changed, 0 insertions, 668 deletions
diff --git a/docs/html/cust-templates.html b/docs/html/cust-templates.html deleted file mode 100644 index 90a800dc9..000000000 --- a/docs/html/cust-templates.html +++ /dev/null @@ -1,668 +0,0 @@ -<HTML -><HEAD -><TITLE ->Template Customization</TITLE -><META -NAME="GENERATOR" -CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+ -"><LINK -REL="HOME" -TITLE="The Bugzilla Guide - 2.17.7 - Development Release" -HREF="index.html"><LINK -REL="UP" -TITLE="Customising Bugzilla" -HREF="customization.html"><LINK -REL="PREVIOUS" -TITLE="Customising Bugzilla" -HREF="customization.html"><LINK -REL="NEXT" -TITLE="Template Hooks" -HREF="cust-hooks.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 - 2.17.7 - Development Release</TH -></TR -><TR -><TD -WIDTH="10%" -ALIGN="left" -VALIGN="bottom" -><A -HREF="customization.html" -ACCESSKEY="P" ->Prev</A -></TD -><TD -WIDTH="80%" -ALIGN="center" -VALIGN="bottom" ->Chapter 4. Customising Bugzilla</TD -><TD -WIDTH="10%" -ALIGN="right" -VALIGN="bottom" -><A -HREF="cust-hooks.html" -ACCESSKEY="N" ->Next</A -></TD -></TR -></TABLE -><HR -ALIGN="LEFT" -WIDTH="100%"></DIV -><DIV -CLASS="section" -><H1 -CLASS="section" -><A -NAME="cust-templates" -></A ->4.1. Template Customization</H1 -><P -> 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. - </P -><P -> 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 - <A -HREF="cust-templates.html#template-http-accept" ->Section 4.1.5</A ->. - </P -><DIV -CLASS="section" -><H2 -CLASS="section" -><A -NAME="AEN1208" -></A ->4.1.1. What to Edit</H2 -><P -> The template directory structure is that there's a top level directory, - <TT -CLASS="filename" ->template</TT ->, which contains a directory for - each installed localization. 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 -> 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 <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 to be modified 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 -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 ->It is recommended that you run <B -CLASS="command" ->./checksetup.pl</B -> - after any template edits, especially if you've created a new file in - the <TT -CLASS="filename" ->custom</TT -> directory. - </P -></TD -></TR -></TABLE -></DIV -></DIV -><DIV -CLASS="section" -><H2 -CLASS="section" -><A -NAME="AEN1231" -></A ->4.1.2. How To Edit Templates</H2 -><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 -><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 ->. - </P -><P -> 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 forget, 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 -><DIV -CLASS="section" -><H2 -CLASS="section" -><A -NAME="AEN1241" -></A ->4.1.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 "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. - </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="AEN1254" -></A ->4.1.4. Particular Templates</H2 -><P -> There are a few templates you may be particularly interested in - customizing 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 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. - </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 -CLASS="section" -><H2 -CLASS="section" -><A -NAME="template-http-accept" -></A ->4.1.5. Configuring Bugzilla to Detect the User's Language</H2 -><P ->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 <A -HREF="http://www.bugzilla.org/download.html#localizations" -TARGET="_top" ->http://www.bugzilla.org/download.html#localizations</A ->. Instructions - for submitting new languages are also available from that location. - </P -><P ->After untarring the localizations (or creating your own) in the - <TT -CLASS="filename" ->BUGZILLA_ROOT/template</TT -> directory, - you must update the <TT -CLASS="option" ->languages</TT -> parameter to contain any - localizations you'd like to permit. You may also wish to set the - <TT -CLASS="option" ->defaultlanguage</TT -> parameter to something other than - <SPAN -CLASS="QUOTE" ->"en"</SPAN -> if you don't want Engish to be the default language. - </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="customization.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="cust-hooks.html" -ACCESSKEY="N" ->Next</A -></TD -></TR -><TR -><TD -WIDTH="33%" -ALIGN="left" -VALIGN="top" ->Customising Bugzilla</TD -><TD -WIDTH="34%" -ALIGN="center" -VALIGN="top" -><A -HREF="customization.html" -ACCESSKEY="U" ->Up</A -></TD -><TD -WIDTH="33%" -ALIGN="right" -VALIGN="top" ->Template Hooks</TD -></TR -></TABLE -></DIV -></BODY -></HTML ->
\ No newline at end of file |