Context Navigation

Trac のインタフェースをカスタマイズする

イントロダクション

このページは Trac の外観をカスタマイズする方法をユーザに提案するために書きました。主要な話題は HTML テンプレートと CSS ファイルであり、プログラムコードではありません。ユーザ自身の特定のニーズを満たすために Trac の外観を変更する方法を、ユーザに示すことを意図しています。 Trac の全てのユーザにとって有益な、インタフェース変更の提案は、このページに書くのではなくチケットを使用してください。
(訳注: 本家サイトのチケットの話です)

プロジェクトのロゴとアイコン

Trac のインタフェースをカスタマイズする中で、最も簡単なのは、ロゴとサイトアイコンです。両方とも trac.ini に設定するだけで構成できます。

ロゴやアイコンのイメージは、 Trac Environment フォルダの中の "htdocs" というフォルダに置かなければいけません。 (Note: バージョン 0.9 以前の Trac で作成したプロジェクトでは、このフォルダを自分で作成する必要があります)

Note: 実際は、ロゴとアイコンはサーバのどこのパスにおいてもかまいません(Web サーバがアクセスできるところならですが)。設定の中でそれらの絶対またはサーバの相対 URL を使用します。

trac.ini の適切なセクションの構成は以下の通りです:

ロゴ

src の設定を site/ に続く画像ファイルの名前に変更してください。 width と height は画像ファイルにあわせて設定を変更してください。(Trac の chrome ハンドラはプロジェクトのディレクトリ htdocs と "common/" の中のファイル用に "site/" を使用します。)

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

アイコン

アイコンは .gif か .ico 形式の 16x16 の画像である必要があります。 icon の設定を site/ に続くアイコンファイルの名前に変更してください。アイコンは通常、サイトの URL の横や、 ブックマーク メニューに表示されます。

[project]
icon = site/my_icon.ico

Note: Internet Explorer では、ホストのルートディレクトリにある favicon.ico という名前のファイルしか許容しないため、このアイコンは無視されます。プロジェクトアイコンを IE と他のブラウザで共用したい場合、アイコンをホストのドキュメントルートに配置し、 trac.ini から以下のように参照します:

[project]
icon = /favicon.ico

ナビゲーション項目のカスタマイズ

[mainnav] と [metanav] を使用すると、ナビゲーション項目に使用されるテキストとリンクをカスタマイズしたり、無効化することができます (新規項目を追加することはできません)。

以下の例では、 Wiki のスタートページへのリンク名を "Home" に変更して、 "Help/Guide" を非表示にします。さらに、 "View Tickets" エントリを特定のレポートにリンクさせます。

[mainnav]
wiki.label = Home
tickets.href = /report/24

[metanav]
help = disabled

mainnav と metanav についての、より詳細な記述は TracNavigation を参照してください。

サイトの外観

Trac はテンプレートエンジンに Genshi を使用しています。ドキュメントはまだ書かれていませんが、次の tip は動くはずです。

カスタムスタイルシートへのリンクに加えて、独自のヘッダやフッタを追加したい場合、以下のような内容のファイル /path/to/env/templates/site.html または /path/to/inherit/option/templates_dir/site.html を作成してください:

<html xmlns="http://www.w3.org/1999/xhtml"
      xmlns:py="http://genshi.edgewall.org/"
      py:strip="">

  <!--! Add site-specific style sheet -->
  <head py:match="head" py:attrs="select('@*')">
    ${select('*|comment()|text()')}
    <link rel="stylesheet" type="text/css"
          href="${href.chrome('site/style.css')}" />
  </head>

  <body py:match="body" py:attrs="select('@*')">
    <!--! Add site-specific header -->
    <div id="siteheader">
      <!--! Place your header content here... -->
    </div>

    ${select('*|text()')}

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

Note: この例では、 Environment の htdocs/style.css を参照しています。

チケット登録のフォームに導入テキストを表示する (プレビューが非表示のとき) 場合は、次の例を追加してください。

<form py:match="div[@id='content' and @class='ticket']/form" py:attrs="select('@*')">
  <py:if test="req.environ['PATH_INFO'] == '/newticket' and (not 'preview' in req.args)">
    <p>Please make sure to search for existing tickets before reporting a new one!</p>
  </py:if>
  ${select('*')} 
</form>

0.10 からアップグレードされた Environment で、かつ site_newticket.cs ファイルが既に存在している場合は、ワークアラウンドすることによってテンプレートをロードすることができます - ClearSilver の処理が含まれていない場合に限ります (訳注: <?cs?> が含まれていない場合) 。また、この場合はただ一つの要素 (element) だけがインポートされるので、コンテンツはある種のラッパー (<div> ブロックやそれに似た親コンテナ) を必要とします。インクルードするためには XInclude の名前空間を指定しなければなりませんが、ドキュメントルート以外にも置くことができます:

<form py:match="div[@id='content' and @class='ticket']/form" py:attrs="select('@*')"
        xmlns:xi="http://www.w3.org/2001/XInclude">
  <py:if test="req.environ['PATH_INFO'] == '/newticket' and (not 'preview' in req.args)"> 
    <xi:include href="site_newticket.cs"><xi:fallback /></xi:include>
  </py:if>
  ${select('*')} 
</form>

また、共通のテンプレートディレクトリに、 site.html (その名前にも関わらず) を置くことができます - [inherit] templates_dir オプションを参照してください。新しく、一個のグローバルな site.html ファイルに、ヘッダ, フッタ, チケット作成時の tips を組み込むことで、簡単なメンテナンス (および、大きなインストールを行った 0.10 からのバージョンアップのための移行パス) を提供しています。

プロジェクトリスト

複数の Trac プロジェクトを動かしているときに、カスタマイズした Genshi テンプレートを使用して、プロジェクトの一覧を表示することができます。

以下に示すのは Trac が使用している、ホストするプロジェクトへのリンクのリストを表示するための基本のテンプレートです。ロードできないプロジェクトについては、エラーメッセージを表示します。これをあなた自身のインデックステンプレートのスタートポイントとして使用することができます。

<!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>プロジェクト一覧</title>
  </head>
  <body>
    <h1>プロジェクト一覧</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>エラー</em> <br /> ($project.description)</small>
        </py:otherwise>
      </li>
    </ul>
  </body>
</html>

カスタムテンプレートを使用する場合、 Web サーバにテンプレートのロケーションの設定を読み込ませる必要があります (確かめてみてください ... まだ 0.11 向けに変更していません):

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 を動かすのに使用するシェルの中で TRAC_ENV_INDEX_TEMPLATE の環境変数を設定する必要があるでしょう:

Unix

$ export TRAC_ENV_INDEX_TEMPLATE=/path/to/template

Windows

$ set TRAC_ENV_INDEX_TEMPLATE=/path/to/template

プロジェクトテンプレート

# ProjectTemplates?

個々の Trac Environment (プロジェクトのインスタンス) の外観は、同じサーバにホストされている他のプロジェクトとは独立してカスタマイズできます。推奨するのは site.html テンプレート (サイトの外観参照) を使う方法です。どのような場合でも可能な限り、この方法にしてください。 site.html を使う場合、変更はオリジナルのテンプレートがレンダリングした結果に対して適用されるので、 Trac を今後アップグレードした後も、通常はカスタマイズをそのまま使い続けることができます。 theme.html や他の Trac のテンプレートのコピーを作成する方法の場合、新しい Trac の機能追加や不具合修正の結果、動かなくなってしまったカスタマイズを新しいバージョンに移行する必要があるかもしれません。

リスクを許容して扱う必要はありますが、 Trac テンプレートはコピーしてカスタマイズすることもできます。デフォルトの Trac テンプレートはインストールされた Trac egg (/usr/lib/pythonVERSION/site-packages/Trac-VERSION.egg/trac/templates, .../trac/ticket/templates, .../trac/wiki/templates, ++) 内に配置されています。プロジェクトリストのテンプレートファイルは index.html が使用されており、各ページに共通する主要なレイアウトを提供するテンプレートは theme.html が使用されます。画像や CSS スタイルシートなどのページの部品は、 egg の trac/htdocs ディレクトリに配置されています。

しかし、 Trac egg 内部のテンプレートやサイトのリソースは編集しないでください。 Trac を再インストールしたときに、カスタマイズの内容が完全に失われてしまいます。代わりに、以下に挙げる方法のいずれかを使ってください:

カスタマイズが単独のプロジェクトに閉じているのであれば、テンプレートをプロジェクトの templates ディレクトリにコピーしてください。
カスタマイズが複数のプロジェクトに渡るものであるなら、テンプレートを共有のロケーションにコピーし、各プロジェクトからは trac.ini の [inherit] templates_dir = オプションで、その位置を指定してください。

Trac は以下の順序で、テンプレートファイルを探します。まず、プロジェクトの内部を探し、存在しなければ inherit で指定された場所、最後に Trac egg の内部を探します。

異なるフォーマットでダウンロード:

テキスト

mi