wiki:TracInterfaceCustomization

Version 1 (modified by trac, 18 years ago) (diff)

--

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

Table of Contents

イントロダクション

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

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

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

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

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

ロゴ

src の設定を site/ に続く画像ファイルの名前に変更してください。 width と height は画像ファイルにあわせて設定を変更してください。 

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

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

See also TracGuide, TracIni