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

Table of Contents

イントロダクション

このページは 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

サイトヘッダとサイトフッタ

それぞれのプロジェクトの Trac Environment フォルダには templates ディレクトリがあります。このフォルダには site_header.cs と site_footer.cs というファイルがあります。これらのファイルに HTML マークアップされた内容を追加することで、ユーザは Trac サイトをカスタマイズできます。2つのファイルはサイト内で <body> タグの直後と、 </body> タグの直前にそれぞれ展開されます。

これらのファイルでは、静的な HTML を記述することが出来ます。動的に生成されるコンテンツを置きたい場合、 ClearSilver テンプレート言語も使用できます。テンプレートで利用可能な変数を見たい場合、 Trac に接続している URL にクエリ文字列 ?hdfdump=1 を追加してください。テンプレートデータを構造化表示できます。

サイト CSS

Trac サイトのレイアウトを調整する主な方法は CSS にスタイルのルールを追加し、デフォルトのルールをオーバレイすることです。このためのベストなやり方は、 Trac Environment の templates ディレクトリにあるファイル site_css.cs を編集することです。 テンプレートから取得したコンテンツは、 Trac が生成する全ての HTML ページで <style type="text/css"></style> 要素に挿入されます。

カスタマイズしたスタイルのルールを site_css.cs ファイルに直接書くことも出来ますが、単に外部のスタイルシートへの参照を記述するのを推奨します。その結果、応答のたびにルールを送信するのではなく、ブラウザが CSS ファイルをキャッシュするのを可能にします。

この例はホストの style ディレクトリに配置したスタイルシートをインポートする書き方です: 

@import url(/style/mytrac.css);

ClearSilver の変数を使用することで、 Trac Environment の htdocs ディレクトリに格納したスタイルシートを参照させることが出来ます。 

@import url(<?cs var:chrome.href ?>/site/style.css);

プロジェクトリスト

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

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

<html>
<head><title>プロジェクト一覧</title></head>
<body>
 <h1>プロジェクト一覧</h1>
 <ul><?cs
 each:project = projects ?><li><?cs
  if:project.href ?>
   <a href="<?cs var:project.href ?>" title="<?cs var:project.description ?>">
    <?cs var:project.name ?></a><?cs
  else ?>
   <small><?cs var:project.name ?>: <em>エラー</em> <br />
   (<?cs var:project.description ?>)</small><?cs
  /if ?>
  </li><?cs
 /each ?>
 </ul>
</body>
</html>

いったんカスタムテンプレートを作ると、web サーバにテンプレートのロケーションの設定を読み込ませる必要があります:

FastCGI 用: 

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

mod_python 用: 

PythonOption TracEnvIndexTemplate /path/to/template

CGI 用: 

SetEnv TRAC_ENV_INDEX_TEMPLATE /path/to/template

メインテンプレート

Trac の ClearSilver テンプレートについても、カスタマイズしたバージョンを使用することが出来ます。 Note: Trac をアップグレードするときに多くの問題が発生するので、このテクニックは推奨されません: 残念ながら、テンプレートとアプリケーションコードの間には、フォームフィールドの名前やテンプレートデータの構造など、いくつか依存関係があります。また、これらは今後の Trac のバージョン間で互換性を持たないこともあります。

どうしてもテンプレートを変更する必要があるなら、デフォルトのテンプレートディレクトリ (通常は $prefix/share/trac/templates) から、 Trac Environment の templates ディレクトリにテンプレートファイルをコピーして、必要な結果が得られるようにコピーの方を変更してください。

See also TracGuide, TracIni

track feed