diff options
Diffstat (limited to 'docs/en/rst/integrating/templates.rst')
| -rw-r--r-- | docs/en/rst/integrating/templates.rst | 289 |
1 files changed, 289 insertions, 0 deletions
diff --git a/docs/en/rst/integrating/templates.rst b/docs/en/rst/integrating/templates.rst new file mode 100644 index 000000000..f30b4a848 --- /dev/null +++ b/docs/en/rst/integrating/templates.rst @@ -0,0 +1,289 @@ +.. _templates: + +Templates +######### + +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 :ref:`extension <extensions>` to add or modify the +behaviour of templates using a stable interface. + +.. _template-directory: + +Template Directory Structure +============================ + +The template directory structure starts with top level directory +named :file:`template`, which contains a directory +for each installed localization. Bugzilla comes with English +templates, so the directory name is :file:`en`, +and we will discuss :file:`template/en` throughout +the documentation. Below :file:`template/en` is the +:file:`default` directory, which contains all the +standard templates shipped with Bugzilla. + +.. warning:: A directory :file:`data/template` also exists; + this is where Template Toolkit puts the compiled versions (i.e. Perl code) + of the templates. *Do not* directly edit the files in this + directory, or all your changes will be lost the next time + Template Toolkit recompiles the templates. + +.. _template-method: + +Choosing a Customization Method +=============================== + +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. + +#. You can directly edit the templates found in :file:`template/en/default`. + +#. You can copy the templates to be modified into a mirrored directory + structure under :file:`template/en/custom`. Templates in this + directory structure automatically override any identically-named + and identically-located templates in the + :file:`template/en/default` directory. (The :file:`custom` directory does + not exist by default and must be created if you want to use it.) + +#. You can use the hooks built into many of the templates to add or modify + the UI from an :ref:`extension <extensions>`. Hooks generally don't go away + and have a stable interface. + +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. + +Unlike code hooks, there is no requirement to document template hooks, so +you just have to open up the template and see (search for ``Hook.process``). + +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 :file:`custom` 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 +:file:`bug/create/user-message.html.tmpl` which are designed to be entirely +replaced. + +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. + +For minor changes, the convenience of the first method is hard to beat. When +you upgrade Bugzilla, :command:`git` 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. + +Also, you can see what you've changed using :command:`git diff`, which you +can't if you fork the file into the :file:`custom` directory. + +.. _template-edit: + +How To Edit Templates +===================== + +.. note:: 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 + `Developers' Guide <http://www.bugzilla.org/docs/developer.html>`_. + +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 `Template Toolkit home page <http://www.template-toolkit.org>`_. + +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, i.e. ``<``. You use the ``html`` filter in the +Template Toolkit to do this (or the ``uri`` filter to encode special +characters in URLs). If you forget, you may open up your installation +to cross-site scripting attacks. + + +You should run :command:`./checksetup.pl` 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. + +.. _template-formats: + +Template Formats and Types +========================== + +Some CGI's have the ability to use more than one template. For example, +:file:`buglist.cgi` 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. + +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. + +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 :ref:`apis` to integrate with +Bugzilla. + +To see if a CGI supports multiple output formats and types, grep the +CGI for ``get_format``. If it's not present, adding +multiple format/type support isn't too hard - see how it's done in +other CGIs, e.g. :file:`config.cgi`. + +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. + +Write your template in whatever markup or text style is appropriate. + +You now need to decide what content type you want your template +served as. The content types are defined in the +:file:`Bugzilla/Constants.pm` file in the :file:`contenttypes` +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. + +Save your new template as +:file:`<stubname>-<formatname>.<contenttypetag>.tmpl`. +Try out the template by calling the CGI as +``<cginame>.cgi?format=<formatname>``. Add ``&ctype=<type>`` if the type is +not HTML. + +.. _template-specific: + +Particular Templates +==================== + +There are a few templates you may be particularly interested in +customizing for your installation. + +:file:`index.html.tmpl`: + This is the Bugzilla front page. + +:file:`global/header.html.tmpl`: + 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. + +:file:`global/banner.html.tmpl`: + 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. + +:file:`global/footer.html.tmpl`: + 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. + +:file:`global/variables.none.tmpl`: + 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"). + +:file:`list/table.html.tmpl`: + 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. + +:file:`bug/create/user-message.html.tmpl`: + 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. + +:file:`bug/process/midair.html.tmpl`: + 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. + +.. _custom-bug-entry: + +:file:`bug/create/create.html.tmpl` and :file:`bug/create/comment.txt.tmpl`: + 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. + + An example of this is the `guided bug submission form + <http://landfill.bugzilla.org/bugzilla-tip/enter_bug.cgi?product=WorldControl;format=guided>`_. + The code for this comes with the Bugzilla distribution as an example for + you to copy. It can be found in the files + :file:`create-guided.html.tmpl` and :file:`comment-guided.html.tmpl`. + + 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 :file:`create-guided.html.tmpl`, then + + :: + + <input type="hidden" name="format" value="guided"> + + is used inside the form. + + So to use this feature, create a custom template for + :file:`enter_bug.cgi`. The default template, on which you + could base it, is + :file:`default/bug/create/create.html.tmpl`. + Call it :file:`custom/bug/create/create-<formatname>.html.tmpl`, 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. + + Then, create a template based on + :file:`default/bug/create/comment.txt.tmpl`, and call it + :file:`custom/bug/create/comment-<formatname>.txt.tmpl`. + It needs a couple of lines of boilerplate at the top like this:: + + [% USE Bugzilla %] + [% cgi = Bugzilla.cgi % + + Then, this template can reference the form fields you have created using + the syntax ``[% cgi.param("field_name") %]``. When a bug report is + submitted, the initial comment attached to the bug report will be + formatted according to the layout of this template. + + For example, if your custom enter_bug template had a field:: + + <input type="text" name="buildid" size="30"> + + and then your comment.txt.tmpl had:: + + [% USE Bugzilla %] + [% cgi = Bugzilla.cgi %] + Build Identifier: [%+ cgi.param("buildid") %] + + then something like:: + + Build Identifier: 20140303 + + would appear in the initial comment. + + This system allows you to gather structured data in bug reports without + the overhead and UI complexity of a large number of custom fields. |