VirtualBox

自定义 Trac 界面

目录

目录

  1. 项目徽标和图标
    1. 徽标
    2. 图标
  2. 自定义导航条目
  3. 网站外观
    1. 在多个环境中共享模板
  4. 项目列表
  5. 项目模板

此页面提供了关于如何自定义 Trac 外观的建议。主题包括编辑 HTML 模板和 CSS 文件，但不包括程序代码本身。这些主题向用户展示了他们如何修改 Trac 的外观以满足其特定需求。适用于所有用户的 Trac 界面更改建议应以工单形式提交，而不是列在此页面上。

项目徽标和图标

Trac 界面中最容易定制的部分是徽标和站点图标。这两者都可以在 trac.ini 的设置中进行配置。

徽标或图标图像应放在您环境的 htdocs 目录中。您实际上可以将徽标和图标放在服务器上的任何位置（只要可以通过 Web 服务器访问），并在配置中使用它们的绝对 URL 或服务器相对 URL。

接下来，配置您的 trac.ini 中的相应部分

将 src 设置更改为 site/，后跟您的图像文件名。width 和 height 设置应修改为与您的图像尺寸匹配。Trac chrome 处理程序使用 site/ 来表示项目目录 htdocs 中的文件，以及 common/ 来表示 Trac 安装所共有的 htdocs 目录。请注意，site/ 不是您项目名称的占位符，它是一个字面量前缀。例如，如果您的项目名为 sandbox，图像文件为 red_logo.gif，那么 src 设置将是 site/red_logo.gif，而不是 sandbox/red_logo.gif。

[header_logo]
src = site/my_logo.gif
alt = My Project
width = 300
height = 100

图标

图标是网页浏览器在站点 URL 旁边和 Bookmarks 菜单中显示的小图像。图标应为 32x32 像素的 .gif 或 .ico 格式图像。将 icon 设置更改为 site/，后跟您的图标文件名

[project]
icon = site/my_icon.ico

自定义导航条目

trac.ini 的 [mainnav] 和 [metanav] 部分可用于自定义导航条目、禁用它们甚至添加新的条目。

在以下示例中，我们

  • 将指向 WikiStart 的链接重命名为 Home
  • 隐藏 About 条目
  • 使 View Tickets 条目链接到特定报告
  • 添加一个 Builds 条目，链接到外部构建系统
  • 将 Admin 条目移动到元导航栏
    [mainnav]
wiki.label = Home
tickets.href = /report/24

[metanav]
about = disabled
builds = enabled
builds.href = https://travis-ci.org/edgewall/trac
admin = enabled

另请参阅 TracNavigation，了解 mainnav 和 metanav 导航的更详细解释。

网站外观

Trac 使用 ​Jinja2 作为模板引擎。

我们已经设置了一些以“include”指令形式存在的“占位符”。这些文件不需要存在，但如果存在，其内容也将由 Jinja2 处理。因此，它们可以利用其他“include”指令或 Jinja2 的任何其他功能来生成动态内容。

存在三个此类占位符模板

  • site_head.html，可用于在生成的 <head> 元素内部添加内容
  • site_header.html，可用于在生成的 <body> 元素内部 前置 内容，位于 Trac 生成的标准内容之前
  • site_footer.html，可用于在生成的 <body> 元素内部 追加 内容，位于 Trac 生成的标准内容之后

假设您想添加一个指向自定义样式表的链接，然后是您自己的页眉和页脚。将以下内容保存为您的项目 templates/ 目录中的 site_head.html、site_header.html 和 site_footer.html（每个 Trac 项目都可以有自己的“占位符”文件），例如 /path/to/env/templates/site_head.html

site_head.html: 

  <!-- site_head.html: Add site-specific style sheet -->
  <link rel="stylesheet" href="${href.chrome('site/style.css')}" />
  <!-- /site_head.html -->

site_header.html: 

    <!-- site_header.html: Add site-specific header -->
    <div id="siteheader">
      ## Place your header content here...
    </div>
    <!-- /site_header.html -->

site_footer.html: 

    <!-- site_footer.html: Add site-specific footer -->
    <div id="sitefooter">
      ## Place your footer content here...
    </div>
    <!-- /site_footer.html -->

请注意，由于 Jinja2 大多与内容无关，您可以自由地在 site_header.html 文件中打开一些 <div> 元素，并仅在 site_footer.html 文件中关闭它。此外，与任何其他 Trac Jinja2 模板一样，您可以使用一些 Trac 特有的功能，例如 ${href.chrome('site/style.css')} 属性引用了环境的 htdocs/ 目录中的 style.css。类似地，${chrome.htdocs_location} 用于指定 Trac 安装所共有的 htdocs/ 目录。然而，后者可以通过使用 [trac] htdocs_location 设置来覆盖。

将介绍文本添加到新工单表单的示例代码片段（但在预览期间不显示）

  • 首先，如果适合请求，我们需要引入此通知的额外“内容”。为此，我们在 site_footer.html 占位符文件中添加此代码片段
    # if req.path_info == '/newticket' and 'preview' not in req.args:
  <p id="ntg">Please make sure to search for existing tickets before reporting a new one!</p>
# endif
  • 其次，我们需要动态地更改其余内容，以便将该通知放置在所需位置。为此，我们将此代码片段添加到 site_head.html 占位符文件中
<script>
  jQuery(function($) {
    var $ntg = $("#newticketguide");
    if ($ntg.length)
      $("#propertyform").prepend($ntg.detach());
  });
</script>

此示例说明了一种使用 req.path_info 将更改范围限制为仅一个视图的技术。例如，为了仅对时间线进行更改并避免修改其他部分，请在 # if 测试中使用 req.path_info == '/timeline' 作为条件。

更多占位符文件的示例代码片段可在 ​CookBook/SiteHtml 找到。

style.css 的示例代码片段可在 ​CookBook/SiteStyleCss 找到。

在多个环境中共享模板

尽管 site_*.html 模板名称如此，它们仍可放置在共享模板目录中，请参阅 [inherit] templates_dir 选项。这可以提供更简单的维护，因为全局的 site_head.html、site_header.html 和 site_footer.html 文件可以设置为 # include 任何其他本地存在的页眉、页脚和新工单代码片段。

项目列表

如果您使用 Trac 管理多个项目，可以使用自定义 Genshi 模板来显示项目列表。

以下是 Trac 用于显示项目链接列表的基本模板。对于无法加载的项目，它会显示错误消息。您可以将其用作自己索引模板的起点

FIXME

<!DOCTYPE html
    PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"
      xmlns:py="http://genshi.edgewall.org/"
      xmlns:xi="http://www.w3.org/2001/XInclude">
  <head>
    <title>Available Projects</title>
  </head>
  <body>
    <h1>Available Projects</h1>
    <ul>
      <li py:for="project in projects" py:choose="">
        <a py:when="project.href" href="$project.href"
           title="$project.description">$project.name</a>
        <py:otherwise>
          <small>$project.name: <em>Error</em> <br /> ($project.description)</small>
        </py:otherwise>
      </li>
    </ul>
  </body>
</html>

创建自定义模板后，您需要配置 Web 服务器以告诉 Trac 模板的位置

对于 mod_wsgi

os.environ['TRAC_ENV_INDEX_TEMPLATE'] = '/path/to/template.html'

对于 FastCGI

FastCgiConfig -initial-env TRAC_ENV_PARENT_DIR=/parent/dir/of/projects \
              -initial-env TRAC_ENV_INDEX_TEMPLATE=/path/to/template

对于 mod_python

PythonOption TracEnvParentDir /parent/dir/of/projects
PythonOption TracEnvIndexTemplate /path/to/template

对于 CGI

SetEnv TRAC_ENV_INDEX_TEMPLATE /path/to/template

对于 TracStandalone，您需要在用于启动 tracd 的 shell 中设置 TRAC_ENV_INDEX_TEMPLATE 环境变量

  • Unix
    $ export TRAC_ENV_INDEX_TEMPLATE=/path/to/template
  • Windows
    $ set TRAC_ENV_INDEX_TEMPLATE=/path/to/template

项目模板

每个 Trac 环境（即项目实例）的外观都可以独立于其他项目进行自定义，即使是托管在同一服务器上的项目。推荐的方法是尽可能使用 site_{head,header,footer}.html 模板，请参阅 #SiteAppearance。使用 site_{head,header,footer}.html 意味着在渲染时对原始模板进行更改，通常在 Trac 升级时不需要重新进行修改。如果您确实复制了 theme.html 或任何其他 Trac 模板，则需要将您的修改迁移到新版本。否则，新的 Trac 功能或错误修复可能无法按预期工作。

尽管有上述警告，任何 Trac 模板都可以被复制和自定义。默认的 Trac 模板位于 Trac egg 或 wheel 中，例如 /usr/lib/pythonVERSION/site-packages/Trac-VERSION.egg/trac/templates, ../trac/ticket/templates, ../trac/wiki/templates。#ProjectList 模板文件名为 index.html，而负责主布局的模板名为 theme.html。页面资产（如图像和 CSS 样式表）位于 egg 或 wheel 的 trac/htdocs 目录中。

但是，不要在 Trac egg/wheel 内部编辑模板或站点资源。重新安装 Trac 会覆盖您的修改。请改用以下替代方案之一

  • 如果只修改一个项目，将模板复制到项目 templates 目录。
  • 对于多个项目共享的修改，将模板复制到共享位置，并让每个项目使用 [inherit] templates_dir 选项指向此位置。

Trac 解析模板请求时，首先在项目内部查找，然后在任何继承的模板位置查找，最后在 Trac egg 或 wheel 内部查找。

Trac 默认将模板缓存到内存中以提高性能。要应用模板，您需要重新启动 Web 服务器。

另请参阅 TracIni, TracNavigation

上次修改 2 年前 上次修改于 06/02/2023 10:32:55 AM
注意： 查看 TracWiki 获取使用维基的帮助。

© 2025 Oracle 支持 隐私 / 请勿出售我的信息 使用条款 商标政策 自动化访问礼节