<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>5.4. Templates — Bugzilla 5.0.4 documentation</title>
<link rel="stylesheet" href="../_static/bugzilla.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../',
VERSION: '5.0.4',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true,
SOURCELINK_SUFFIX: '.txt'
};
</script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<link rel="shortcut icon" href="../_static/favicon.ico"/>
<link rel="search" title="Search" href="../search.html" />
<link rel="next" title="5.5. Extensions" href="extensions.html" />
<link rel="prev" title="5.3. Skins" href="skins.html" />
</head>
<body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="extensions.html" title="5.5. Extensions"
accesskey="N">next</a></li>
<li class="right" >
<a href="skins.html" title="5.3. Skins"
accesskey="P">previous</a> |</li>
<li class="nav-item nav-item-0"><a href="../index.html">Bugzilla 5.0.4 documentation</a> »</li>
<li class="nav-item nav-item-1"><a href="index.html" accesskey="U">5. Integration and Customization Guide</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="templates">
<span id="id1"></span><h1>5.4. Templates<a class="headerlink" href="#templates" title="Permalink to this headline">¶</a></h1>
<p>Bugzilla uses a system of templates to define its user interface. The standard
templates can be modified, replaced or overridden. You can also use template
hooks in an <a class="reference internal" href="extensions.html#extensions"><span class="std std-ref">extension</span></a> to add or modify the
behaviour of templates using a stable interface.</p>
<div class="section" id="template-directory-structure">
<span id="template-directory"></span><h2>5.4.1. Template Directory Structure<a class="headerlink" href="#template-directory-structure" title="Permalink to this headline">¶</a></h2>
<p>The template directory structure starts with top level directory
named <code class="file docutils literal"><span class="pre">template</span></code>, which contains a directory
for each installed localization. Bugzilla comes with English
templates, so the directory name is <code class="file docutils literal"><span class="pre">en</span></code>,
and we will discuss <code class="file docutils literal"><span class="pre">template/en</span></code> throughout
the documentation. Below <code class="file docutils literal"><span class="pre">template/en</span></code> is the
<code class="file docutils literal"><span class="pre">default</span></code> directory, which contains all the
standard templates shipped with Bugzilla.</p>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">A directory <code class="file docutils literal"><span class="pre">data/template</span></code> also exists;
this is where Template Toolkit puts the compiled versions (i.e. Perl code)
of the templates. <em>Do not</em> directly edit the files in this
directory, or all your changes will be lost the next time
Template Toolkit recompiles the templates.</p>
</div>
</div>
<div class="section" id="choosing-a-customization-method">
<span id="template-method"></span><h2>5.4.2. Choosing a Customization Method<a class="headerlink" href="#choosing-a-customization-method" title="Permalink to this headline">¶</a></h2>
<p>If you want to edit Bugzilla's templates, the first decision
you must make is how you want to go about doing so. There are three
choices, and which you use depends mainly on the scope of your
modifications, and the method you plan to use to upgrade Bugzilla.</p>
<ol class="arabic simple">
<li>You can directly edit the templates found in <code class="file docutils literal"><span class="pre">template/en/default</span></code>.</li>
<li>You can copy the templates to be modified into a mirrored directory
structure under <code class="file docutils literal"><span class="pre">template/en/custom</span></code>. Templates in this
directory structure automatically override any identically-named
and identically-located templates in the
<code class="file docutils literal"><span class="pre">template/en/default</span></code> directory. (The <code class="file docutils literal"><span class="pre">custom</span></code> directory does
not exist by default and must be created if you want to use it.)</li>
<li>You can use the hooks built into many of the templates to add or modify
the UI from an <a class="reference internal" href="extensions.html#extensions"><span class="std std-ref">extension</span></a>. Hooks generally don't go away
and have a stable interface.</li>
</ol>
<p>The third method is the best if there are hooks in the appropriate places
and the change you want to do is possible using hooks. It's not very easy
to modify existing UI using hooks; they are most commonly used for additions.
You can make modifications if you add JS code which then makes the
modifications when the page is loaded. You can remove UI by adding CSS to hide
it.</p>
<p>Unlike code hooks, there is no requirement to document template hooks, so
you just have to open up the template and see (search for <code class="docutils literal"><span class="pre">Hook.process</span></code>).</p>
<p>If there are no hooks available, then the second method of customization
should be used if you are going to make major changes, because it is
guaranteed that the contents of the <code class="file docutils literal"><span class="pre">custom</span></code> directory will not be
touched during an upgrade, and you can then decide whether
to revert to the standard templates, continue using yours, or make the effort
to merge your changes into the new versions by hand. It's also good for
entirely new files, and for a few files like
<code class="file docutils literal"><span class="pre">bug/create/user-message.html.tmpl</span></code> which are designed to be entirely
replaced.</p>
<p>Using the second method, your user interface may break if incompatible
changes are made to the template interface. Templates do change regularly
and so interface changes are not individually documented, and you would
need to work out what had changed and adapt your template accordingly.</p>
<p>For minor changes, the convenience of the first method is hard to beat. When
you upgrade Bugzilla, <strong class="command">git</strong> will merge your changes into the new
version for you. On the downside, if the merge fails then Bugzilla will not
work properly until you have fixed the problem and re-integrated your code.</p>
<p>Also, you can see what you've changed using <strong class="command">git diff</strong>, which you
can't if you fork the file into the <code class="file docutils literal"><span class="pre">custom</span></code> directory.</p>
</div>
<div class="section" id="how-to-edit-templates">
<span id="template-edit"></span><h2>5.4.3. How To Edit Templates<a class="headerlink" href="#how-to-edit-templates" title="Permalink to this headline">¶</a></h2>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">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 class="reference external" href="http://www.bugzilla.org/docs/developer.html">Developers' Guide</a>.</p>
</div>
<p>Bugzilla uses a templating system called Template Toolkit. The syntax of the
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 class="reference external" href="http://www.template-toolkit.org">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 <code class="docutils literal"><span class="pre"><</span></code>, and the data was not intended to be HTML, they need to be
converted to entity form, i.e. <code class="docutils literal"><span class="pre">&lt;</span></code>. You use the <code class="docutils literal"><span class="pre">html</span></code> filter in the
Template Toolkit to do this (or the <code class="docutils literal"><span class="pre">uri</span></code> filter to encode special
characters in URLs). If you forget, you may open up your installation
to cross-site scripting attacks.</p>
<p>You should run <strong class="command">./checksetup.pl</strong> after editing any templates. Failure
to do so may mean either that your changes are not picked up, or that the
permissions on the edited files are wrong so the webserver can't read them.</p>
</div>
<div class="section" id="template-formats-and-types">
<span id="template-formats"></span><h2>5.4.4. Template Formats and Types<a class="headerlink" href="#template-formats-and-types" title="Permalink to this headline">¶</a></h2>
<p>Some CGI's have the ability to use more than one template. For example,
<code class="file docutils literal"><span class="pre">buglist.cgi</span></code> can output itself as two formats of HTML (complex and
simple). Each of these is a separate template. The mechanism that provides
this feature is extensible - you can create new templates to add new formats.</p>
<p>You might use this feature to e.g. add a custom bug entry form for a
particular subset of users or a particular type of bug.</p>
<p>Bugzilla can also support different types of output - e.g. bugs are available
as HTML and as XML, and this mechanism is extensible also to add new content
types. However, instead of using such interfaces or enhancing Bugzilla to add
more, you would be better off using the <a class="reference internal" href="../api/index.html#apis"><span class="std std-ref">WebService API Reference</span></a> to integrate with
Bugzilla.</p>
<p>To see if a CGI supports multiple output formats and types, grep the
CGI for <code class="docutils literal"><span class="pre">get_format</span></code>. If it's not present, adding
multiple format/type support isn't too hard - see how it's done in
other CGIs, e.g. <code class="file docutils literal"><span class="pre">config.cgi</span></code>.</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. The content types are defined in the
<code class="file docutils literal"><span class="pre">Bugzilla/Constants.pm</span></code> file in the <code class="file docutils literal"><span class="pre">contenttypes</span></code>
constant. If your content type is not there, add it. Remember
the three- or four-letter tag assigned to your content type.
This tag will be part of the template filename.</p>
<p>Save your new template as
<code class="file docutils literal"><span class="pre"><stubname>-<formatname>.<contenttypetag>.tmpl</span></code>.
Try out the template by calling the CGI as
<code class="docutils literal"><span class="pre"><cginame>.cgi?format=<formatname></span></code>. Add <code class="docutils literal"><span class="pre">&ctype=<type></span></code> if the type is
not HTML.</p>
</div>
<div class="section" id="particular-templates">
<span id="template-specific"></span><h2>5.4.5. Particular Templates<a class="headerlink" href="#particular-templates" title="Permalink to this headline">¶</a></h2>
<p>There are a few templates you may be particularly interested in
customizing for your installation.</p>
<dl class="docutils">
<dt><code class="file docutils literal"><span class="pre">index.html.tmpl</span></code>:</dt>
<dd>This is the Bugzilla front page.</dd>
<dt><code class="file docutils literal"><span class="pre">global/header.html.tmpl</span></code>:</dt>
<dd>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.</dd>
<dt><code class="file docutils literal"><span class="pre">global/banner.html.tmpl</span></code>:</dt>
<dd>This contains the <code class="docutils literal"><span class="pre">banner</span></code>, 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.</dd>
<dt><code class="file docutils literal"><span class="pre">global/footer.html.tmpl</span></code>:</dt>
<dd>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.</dd>
<dt><code class="file docutils literal"><span class="pre">global/variables.none.tmpl</span></code>:</dt>
<dd>This allows you to change the word 'bug' to something else (e.g. "issue")
throughout the interface, and also to change the name Bugzilla to something
else (e.g. "FooCorp Bug Tracker").</dd>
<dt><code class="file docutils literal"><span class="pre">list/table.html.tmpl</span></code>:</dt>
<dd>This template controls the appearance of the bug lists created
by Bugzilla. Editing this template allows per-column control of
the width and title of a column, the maximum display length of
each entry, and the wrap behaviour of long entries.
For long bug lists, Bugzilla inserts a 'break' every 100 bugs by
default; this behaviour is also controlled by this template, and
that value can be modified here.</dd>
<dt><code class="file docutils literal"><span class="pre">bug/create/user-message.html.tmpl</span></code>:</dt>
<dd>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.</dd>
<dt><code class="file docutils literal"><span class="pre">bug/process/midair.html.tmpl</span></code>:</dt>
<dd>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.</dd>
</dl>
<dl class="docutils" id="custom-bug-entry">
<dt><code class="file docutils literal"><span class="pre">bug/create/create.html.tmpl</span></code> and <code class="file docutils literal"><span class="pre">bug/create/comment.txt.tmpl</span></code>:</dt>
<dd><p class="first">You may not wish to go to the effort of creating custom fields in
Bugzilla, yet you want to make sure that each bug report contains
a number of pieces of important information for which there is not
a special field. The bug entry system has been designed in an
extensible fashion to enable you to add arbitrary HTML widgets,
such as drop-down lists or textboxes, to the bug entry page
and have their values appear formatted in the initial comment.</p>
<p>An example of this is the <a class="reference external" href="http://landfill.bugzilla.org/bugzilla-tip/enter_bug.cgi?product=WorldControl;format=guided">guided bug submission form</a>.
The code for this comes with the Bugzilla distribution as an example for
you to copy. It can be found in the files
<code class="file docutils literal"><span class="pre">create-guided.html.tmpl</span></code> and <code class="file docutils literal"><span class="pre">comment-guided.html.tmpl</span></code>.</p>
<p>A hidden field that indicates the format should be added inside
the form in order to make the template functional. Its value should
be the suffix of the template filename. For example, if the file
is called <code class="file docutils literal"><span class="pre">create-guided.html.tmpl</span></code>, then</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="o"><</span><span class="nb">input</span> <span class="nb">type</span><span class="o">=</span><span class="s2">"hidden"</span> <span class="n">name</span><span class="o">=</span><span class="s2">"format"</span> <span class="n">value</span><span class="o">=</span><span class="s2">"guided"</span><span class="o">></span>
</pre></div>
</div>
<p>is used inside the form.</p>
<p>So to use this feature, create a custom template for
<code class="file docutils literal"><span class="pre">enter_bug.cgi</span></code>. The default template, on which you
could base it, is
<code class="file docutils literal"><span class="pre">default/bug/create/create.html.tmpl</span></code>.
Call it <code class="file docutils literal"><span class="pre">custom/bug/create/create-<formatname>.html.tmpl</span></code>, and
in it, add form inputs 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 based on
<code class="file docutils literal"><span class="pre">default/bug/create/comment.txt.tmpl</span></code>, and call it
<code class="file docutils literal"><span class="pre">custom/bug/create/comment-<formatname>.txt.tmpl</span></code>.
It needs a couple of lines of boilerplate at the top like this:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="p">[</span><span class="o">%</span> <span class="n">USE</span> <span class="n">Bugzilla</span> <span class="o">%</span><span class="p">]</span>
<span class="p">[</span><span class="o">%</span> <span class="n">cgi</span> <span class="o">=</span> <span class="n">Bugzilla</span><span class="o">.</span><span class="n">cgi</span> <span class="o">%</span>
</pre></div>
</div>
<p>Then, this template can reference the form fields you have created using
the syntax <code class="docutils literal"><span class="pre">[%</span> <span class="pre">cgi.param("field_name")</span> <span class="pre">%]</span></code>. 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 custom enter_bug template had a field:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="o"><</span><span class="nb">input</span> <span class="nb">type</span><span class="o">=</span><span class="s2">"text"</span> <span class="n">name</span><span class="o">=</span><span class="s2">"buildid"</span> <span class="n">size</span><span class="o">=</span><span class="s2">"30"</span><span class="o">></span>
</pre></div>
</div>
<p>and then your comment.txt.tmpl had:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="p">[</span><span class="o">%</span> <span class="n">USE</span> <span class="n">Bugzilla</span> <span class="o">%</span><span class="p">]</span>
<span class="p">[</span><span class="o">%</span> <span class="n">cgi</span> <span class="o">=</span> <span class="n">Bugzilla</span><span class="o">.</span><span class="n">cgi</span> <span class="o">%</span><span class="p">]</span>
<span class="n">Build</span> <span class="n">Identifier</span><span class="p">:</span> <span class="p">[</span><span class="o">%+</span> <span class="n">cgi</span><span class="o">.</span><span class="n">param</span><span class="p">(</span><span class="s2">"buildid"</span><span class="p">)</span> <span class="o">%</span><span class="p">]</span>
</pre></div>
</div>
<p>then something like:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">Build</span> <span class="n">Identifier</span><span class="p">:</span> <span class="mi">20140303</span>
</pre></div>
</div>
<p>would appear in the initial comment.</p>
<p class="last">This system allows you to gather structured data in bug reports without
the overhead and UI complexity of a large number of custom fields.</p>
</dd>
</dl>
<hr class="docutils" />
<p>This documentation undoubtedly has bugs; if you find some, please file
them <a class="reference external" href="https://bugzilla.mozilla.org/enter_bug.cgi?product=Bugzilla&component=Documentation">here</a>.</p>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<p class="logo"><a href="../index.html">
<img class="logo" src="../_static/bugzilla.png" alt="Logo"/>
</a></p>
<h3><a href="../index.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">5.4. Templates</a><ul>
<li><a class="reference internal" href="#template-directory-structure">5.4.1. Template Directory Structure</a></li>
<li><a class="reference internal" href="#choosing-a-customization-method">5.4.2. Choosing a Customization Method</a></li>
<li><a class="reference internal" href="#how-to-edit-templates">5.4.3. How To Edit Templates</a></li>
<li><a class="reference internal" href="#template-formats-and-types">5.4.4. Template Formats and Types</a></li>
<li><a class="reference internal" href="#particular-templates">5.4.5. Particular Templates</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="skins.html"
title="previous chapter">5.3. Skins</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="extensions.html"
title="next chapter">5.5. Extensions</a></p>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<form class="search" action="../search.html" method="get">
<div><input type="text" name="q" /></div>
<div><input type="submit" value="Go" /></div>
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="extensions.html" title="5.5. Extensions"
>next</a></li>
<li class="right" >
<a href="skins.html" title="5.3. Skins"
>previous</a> |</li>
<li class="nav-item nav-item-0"><a href="../index.html">Bugzilla 5.0.4 documentation</a> »</li>
<li class="nav-item nav-item-1"><a href="index.html" >5. Integration and Customization Guide</a> »</li>
</ul>
</div>
<div class="footer" role="contentinfo">
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.6.6.
</div>
</body>
</html>
