<!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>