5.7. 模板定制

5.7.1. 要编辑什么

编辑 Bugzilla 模板有两种不同的方法，您使用哪种方法主要取决于您如何升级 Bugzilla。模板目录结构是有一个顶级目录，template，其中包含每个已安装本地化的目录。因此，默认的英语模板位于en中。在其下，有default目录，以及可选的custom目录。

defaultdefault目录包含 Bugzilla 附带的所有模板，而custom目录最初不存在，如果您想使用它，则必须创建它。

进行定制的第一种方法是直接编辑template/en/default中的模板。如果您要使用 CVS 方法进行升级，这可能是进行小更改的最佳方法，因为如果您然后执行 cvs update，任何模板修复程序都会自动合并到您的修改版本中。

如果您使用此方法，如果发生 CVS 冲突，您的安装将会中断。

另一种方法是将模板复制到template/en/custom下的镜像目录结构中。此目录中的模板会自动覆盖 default 中的模板。如果您使用覆盖方法进行升级，则需要使用此技术，否则您的更改将丢失。如果您使用 CVS 方法进行升级并且要进行重大更改，此方法也更好，因为可以保证此目录的内容在升级期间不会被触及，然后您可以决定是继续使用您自己的模板，还是努力手动将您的更改合并到新版本中。

如果您使用此方法，如果对模板接口进行了不兼容的更改，您的安装可能会中断。如果进行了此类更改，它们将在发行说明中记录，前提是您使用的是 Bugzilla 的稳定版本。如果您使用的是不稳定代码，您将需要自己处理这个问题，尽管如果可能，这些更改将在之前的稳定版本的发行说明的弃用部分中提及。

不要直接编辑data/template/*中的已编译模板 - 当 Template Toolkit 重新编译它们时，您的更改将丢失。

5.7.2. 如何编辑模板

Template Toolkit 语言的语法超出了本指南的范围。通过查看当前模板，或者您可以阅读 Template Toolkit 主页上提供的手册，可以很容易地掌握它。但是，您应该特别记住（出于安全原因）始终对来自数据库或用户输入的内容进行 HTML 过滤，以防止跨站脚本攻击。

但是，您应该特别注意的一件事是需要正确地 HTML 过滤已传递到模板中的数据。这意味着如果数据可能包含特殊的 HTML 字符，例如 <，并且数据不打算作为 HTML，则需要将其转换为实体形式，即 &lt;。您可以使用 Template Toolkit 中的 'html' 过滤器来执行此操作。如果您未能做到这一点，您可能会使您的安装容易受到跨站脚本攻击。

另请注意，Bugzilla 添加了一些它自己的过滤器，这些过滤器不在标准 Template Toolkit 中。特别是，'url_quote' 过滤器可以将 URL 中非法或具有特殊含义的字符（例如 &）转换为编码形式，即 %26。这实际上编码了大多数字符（但不包括常见的字符，如字母和数字等），包括 HTML 特殊字符，因此永远不需要之后进行 HTML 过滤。

编辑模板是进行“穷人自定义字段”的一种好方法。例如，如果您不使用状态白板，但想要一个用于“构建标识符”的自由格式文本输入框，那么您可以只编辑模板来更改字段标签。它在内部仍然被称为 status_whiteboard，但您的用户不需要知道这一点。

如果您正在进行模板更改，并且打算将其提交回以包含在标准 Bugzilla 中，您应该阅读 开发者指南的相关章节。

5.7.3. 模板格式

一些 CGI 能够使用多个模板。例如，buglist.cgi 可以将错误列表输出为 RDF 或两种不同形式的 HTML（复杂和简单）。（通过附加&format=simple到 Bugzilla 安装上的 buglist.cgi URL 来尝试一下。）这种称为模板“格式”的机制是可扩展的。

要查看 CGI 是否支持多种输出格式，请在 CGI 中 grep “ValidateOutputFormat”。如果它不存在，添加多种格式支持也不太难 - 请参阅其他 CGI 中是如何完成的。

要为支持此功能的 CGI 创建新的格式模板，请打开该 CGI 的当前模板，并注意 INTERFACE 注释（如果存在）。此注释定义了传递到此模板中的变量。如果没有注释，恐怕您必须阅读模板和代码才能找出您获得了哪些信息。

以任何适合的标记或文本样式编写您的模板。

您现在需要决定要将模板作为哪种内容类型提供。打开localconfig文件并找到$contenttypes变量。如果您的内容类型不在那里，请添加它。记住分配给您的内容类型的三或四个字母的标签。此标签将是模板文件名的一部分。

将模板另存为<stubname>-<formatname>.<contenttypetag>.tmpl。通过调用 CGI 来试用模板，如<cginame>.cgi?format=<formatname> .

5.7.4. 特殊模板

您可能对为您的安装定制以下一些模板特别感兴趣。

index.html.tmpl：这是 Bugzilla 首页。

global/header.html.tmpl：这定义了所有 Bugzilla 页面上的页眉。页眉包括横幅，横幅是显示给用户的内容，可能是您想要编辑的内容。但是，页眉还包括 HTML HEAD 部分，因此例如，您可以通过编辑页眉来添加样式表或 META 标签。

global/banner.html.tmpl：这包含“横幅”，即页眉的一部分，显示在所有 Bugzilla 页面的顶部。默认横幅相当简陋，因此您可能需要定制它，以使您的安装具有独特的外观和感觉。建议您以某种形式保留 Bugzilla 版本号，以便可以确定您正在运行的版本，并且用户知道要阅读哪些文档。

global/footer.html.tmpl：这定义了所有 Bugzilla 页面上的页脚。编辑此项是快速为您的 Bugzilla 安装获得独特外观和感觉的另一种方法。

bug/create/user-message.html.tmpl：这是显示在错误报告页面顶部附近的消息。通过修改此项，您可以告诉您的用户他们应该如何报告错误。

bug/create/create.html.tmpl 和 bug/create/comment.txt.tmpl：您可能希望错误提交者提供某些结构化信息，每个信息都在单独的输入小部件中，而数据库中没有相应的字段。错误输入系统以可扩展的方式设计，使您能够定义任意字段和小部件，并使其值以格式化的形式出现在初始描述中，而不是在数据库字段中。mozilla.org 引导式错误提交表单 就是一个例子。

要使其工作，请为enter_bug.cgi创建一个自定义模板（您可以基于默认模板，即create.html.tmpl），并将其命名为create.html.tmplcreate.html.tmplcreate-<formatname>.html.tmpl。将其放在custom/bug/create目录中。在其中，为要收集的每条信息添加小部件 - 例如构建号或重现步骤集。

然后，创建一个类似custom/bug/create/comment.txt.tmpl的模板，如果您正在使用格式，也可以根据您的格式命名，该模板引用您创建的表单字段。当提交错误报告时，附加到错误报告的初始注释将根据此模板的布局进行格式化。

例如，如果您的 enter_bug 模板有一个字段

<input type="text" name="buildid" size="30">

并且您的 comment.txt.tmpl 有

BuildID: [% form.buildid %]

那么

BuildID: 20020303

将出现在初始签入注释中。