| 42 | | == サイトヘッダとサイトフッタ == |
| 43 | | |
| 44 | | それぞれのプロジェクトの Trac Environment フォルダには {{{templates}}} ディレクトリがあります。このフォルダには {{{site_header.cs}}} と {{{site_footer.cs}}} というファイルがあります。これらのファイルに HTML マークアップされた内容を追加することで、ユーザは Trac サイトをカスタマイズできます。2つのファイルはサイト内で {{{<body>}}} タグの直後と、 {{{</body>}}} タグの直前にそれぞれ展開されます。 |
| 45 | | |
| 46 | | これらのファイルでは、静的な HTML を記述することが出来ます。動的に生成されるコンテンツを置きたい場合、 [http://www.clearsilver.net/ ClearSilver] テンプレート言語も使用できます。テンプレートで利用可能な変数を見たい場合、 Trac に接続している URL にクエリ文字列 `?hdfdump=1` を追加してください。テンプレートデータを構造化表示できます。 |
| 47 | | |
| 48 | | == サイト CSS == |
| 49 | | Trac サイトのレイアウトを調整する主な方法は [http://www.w3.org/TR/REC-CSS2/ CSS] にスタイルのルールを追加し、デフォルトのルールをオーバレイすることです。このためのベストなやり方は、 Trac Environment の `templates` ディレクトリにあるファイル `site_css.cs` を編集することです。 テンプレートから取得したコンテンツは、 Trac が生成する全ての HTML ページで `<style type="text/css"></style>` 要素に挿入されます。 |
| 50 | | |
| 51 | | カスタマイズしたスタイルのルールを `site_css.cs` ファイルに直接書くことも出来ますが、単に外部のスタイルシートへの参照を記述するのを推奨します。その結果、応答のたびにルールを送信するのではなく、ブラウザが CSS ファイルをキャッシュするのを可能にします。 |
| 52 | | |
| 53 | | この例はホストの `style` ディレクトリに配置したスタイルシートをインポートする書き方です: |
| 54 | | {{{ |
| 55 | | @import url(/style/mytrac.css); |
| 56 | | }}} |
| 57 | | |
| 58 | | !ClearSilver の変数を使用することで、 Trac Environment の `htdocs` ディレクトリに格納したスタイルシートを参照させることが出来ます。 |
| 59 | | {{{ |
| 60 | | @import url(<?cs var:chrome.href ?>/site/style.css); |
| 61 | | }}} |
| 62 | | |
| 63 | | == プロジェクトリスト == |
| 64 | | 複数の Trac プロジェクトを動かしているときに、ClearSilver テンプレートをカスタマイズして、プロジェクトの一覧を表示することができます。 |
| 65 | | |
| 66 | | 以下に示すのは Trac が使用しているプロジェクトのリンクリストを表示するための基本のテンプレートです。ロードできないプロジェクトについては、エラーメッセージを表示します。これをあなた自身のインデックステンプレートのスタートポイントとして使用することができます。 |
| | 42 | == ナビゲーション項目のカスタマイズ == #CustomNavigationEntries |
| | 43 | [mainnav] と [metanav] を使用すると、ナビゲーション項目に使用されるテキストとリンクをカスタマイズしたり、無効化することができます (新規項目を追加することはできません)。 |
| | 44 | |
| | 45 | 以下の例では、 Wiki のスタートページへのリンク名を "Home" に変更して、 "Help/Guide" を非表示にします。さらに、 "View Tickets" エントリを特定のレポートにリンクさせます。 |
| | 46 | {{{ |
| | 47 | [mainnav] |
| | 48 | wiki.label = Home |
| | 49 | tickets.href = /report/24 |
| | 50 | |
| | 51 | [metanav] |
| | 52 | help = disabled |
| | 53 | }}} |
| | 54 | |
| | 55 | mainnav と metanav についての、より詳細な記述は TracNavigation を参照してください。 |
| | 56 | |
| | 57 | == サイトの外観 == #SiteAppearance |
| | 58 | |
| | 59 | Trac はテンプレートエンジンに [http://genshi.edgewall.org Genshi] を使用しています。ドキュメントはまだ書かれていませんが、次の tip は動くはずです。 |
| | 60 | |
| | 61 | カスタムスタイルシートへのリンクや、独自のヘッダやフッタを追加したい場合、 |
| | 62 | 以下のようなの内容ファイルを、プロジェクトの templates ディレクトリに 'site.html' という名前で作成してください (各 Trac プロジェクトは独自の内容の site.html を持つことができます)。{{{/path/to/env/templates/site.html}}} の例: |
| | 63 | |
| | 64 | {{{ |
| | 65 | #!xml |
| | 66 | <html xmlns="http://www.w3.org/1999/xhtml" |
| | 67 | xmlns:py="http://genshi.edgewall.org/" |
| | 68 | py:strip=""> |
| | 69 | |
| | 70 | <!--! Add site-specific style sheet --> |
| | 71 | <head py:match="head" py:attrs="select('@*')"> |
| | 72 | ${select('*|comment()|text()')} |
| | 73 | <link rel="stylesheet" type="text/css" |
| | 74 | href="${href.chrome('site/style.css')}" /> |
| | 75 | </head> |
| | 76 | |
| | 77 | <body py:match="body" py:attrs="select('@*')"> |
| | 78 | <!--! Add site-specific header --> |
| | 79 | <div id="siteheader"> |
| | 80 | <!--! Place your header content here... --> |
| | 81 | </div> |
| | 82 | |
| | 83 | ${select('*|text()')} |
| | 84 | |
| | 85 | <!--! Add site-specific footer --> |
| | 86 | <div id="sitefooter"> |
| | 87 | <!--! Place your footer content here... --> |
| | 88 | </div> |
| | 89 | </body> |
| | 90 | </html> |
| | 91 | }}} |
| | 92 | |
| | 93 | XSLT に慣れ親しんだ人であれば、 Genshi テンプレートには類似点があるのに気付くかもしれません。しかしながら Trac 固有の機能もあります。例えば '''${href.chrome('site/style.css')}''' は Environment に含まれる ''htdocs/'' にあるファイルへの参照の属性に置き換えられます。 '''${chrome.htdocs_location}''' は似ていますが、 Trac インストール時に作成された共通の ''htdocs/'' ディレクトリを指定するために使用します。 |
| | 94 | |
| | 95 | site.html はサイト固有のすべての変更を含んでいる一つのファイルです。通常は、要素 (element) または属性 (attribute) として py:match を使用することでレンダリングされるページを変更することができるようになります。 py:match は特定のセクションに依存した記載が行われており、ページを検索してマッチした箇所を変更します。 |
| | 96 | site.html には変更を行うための py:match セクションをいくつでも記載することができます。これらはすべて [http://genshi.edgewall.org/ Genshi] の文法に沿って行います。ドキュメントや詳細なシンタックスは前述のリンクを参考にしてください。 |
| | 97 | |
| | 98 | |
| | 99 | チケット登録のフォームに導入テキストを表示する (プレビューが非表示のとき) 場合は、次の例を追加してください: |
| | 100 | |
| | 101 | {{{ |
| | 102 | #!xml |
| | 103 | <form py:match="div[@id='content' and @class='ticket']/form" py:attrs="select('@*')"> |
| | 104 | <py:if test="req.environ['PATH_INFO'] == '/newticket' and (not 'preview' in req.args)"> |
| | 105 | <p>Please make sure to search for existing tickets before reporting a new one!</p> |
| | 106 | </py:if> |
| | 107 | ${select('*')} |
| | 108 | </form> |
| | 109 | }}} |
| | 110 | |
| | 111 | この例では '''`req.environ['PATH_INFO']`''' を使用して、特定のビューだけで変更が行われるようにスコープを限定しています。例えば site.html でタイムラインだけで変更を行い、他のセクションには影響を及ぼしたくない場合は、 ''`req.environ['PATH_INFO'] == '/timelime'`'' を <py:if> での test に記載します。 |
| | 112 | |
| | 113 | 0.10 からアップグレードされた Environment で、かつ `site_newticket.cs` ファイルが既に存在している場合は、ワークアラウンドすることによってテンプレートをロードすることができます - !ClearSilver の処理が含まれていない場合に限ります (訳注: `<?cs?>` が含まれていない場合) 。また、この場合はただ一つの要素 (element) だけがインポートされるので、コンテンツはある種のラッパー (`<div>` ブロックやそれに似た親コンテナ) を必要とします。インクルードするためには XInclude の名前空間を指定しなければなりませんが、ドキュメントルート以外にも置くことができます: |
| | 114 | {{{ |
| | 115 | #!xml |
| | 116 | <form py:match="div[@id='content' and @class='ticket']/form" py:attrs="select('@*')" |
| | 117 | xmlns:xi="http://www.w3.org/2001/XInclude"> |
| | 118 | <py:if test="req.environ['PATH_INFO'] == '/newticket' and (not 'preview' in req.args)"> |
| | 119 | <xi:include href="site_newticket.cs"><xi:fallback /></xi:include> |
| | 120 | </py:if> |
| | 121 | ${select('*')} |
| | 122 | </form> |
| | 123 | }}} |
| | 124 | |
| | 125 | また、共通のテンプレートディレクトリに、 `site.html` (その名前にも関わらず) を置くことができます - `[inherit] templates_dir` オプションを参照してください。新しく、一個のグローバルな `site.html` ファイルに、ヘッダ, フッタ, チケット作成時の tips を組み込むことで、簡単なメンテナンス (および、大きなインストールを行った 0.10 からのバージョンアップのための移行パス) を提供しています。 |
| | 126 | |
| | 127 | == プロジェクトリスト == #ProjectList |
| | 128 | |
| | 129 | 複数の Trac プロジェクトを動かしているときに、カスタマイズした Genshi テンプレートを使用して、プロジェクトの一覧を表示することができます。 |
| | 130 | |
| | 131 | 以下に示すのは Trac が使用している、ホストするプロジェクトへのリンクのリストを表示するための基本のテンプレートです。ロードできないプロジェクトについては、エラーメッセージを表示します。これをあなた自身のインデックステンプレートのスタートポイントとして使用することができます。 |
| 70 | | <html> |
| 71 | | <head><title>プロジェクト一覧</title></head> |
| 72 | | <body> |
| 73 | | <h1>プロジェクト一覧</h1> |
| 74 | | <ul><?cs |
| 75 | | each:project = projects ?><li><?cs |
| 76 | | if:project.href ?> |
| 77 | | <a href="<?cs var:project.href ?>" title="<?cs var:project.description ?>"> |
| 78 | | <?cs var:project.name ?></a><?cs |
| 79 | | else ?> |
| 80 | | <small><?cs var:project.name ?>: <em>エラー</em> <br /> |
| 81 | | (<?cs var:project.description ?>)</small><?cs |
| 82 | | /if ?> |
| 83 | | </li><?cs |
| 84 | | /each ?> |
| 85 | | </ul> |
| 86 | | </body> |
| | 135 | <!DOCTYPE html |
| | 136 | PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" |
| | 137 | "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> |
| | 138 | <html xmlns="http://www.w3.org/1999/xhtml" |
| | 139 | xmlns:py="http://genshi.edgewall.org/" |
| | 140 | xmlns:xi="http://www.w3.org/2001/XInclude"> |
| | 141 | <head> |
| | 142 | <title>プロジェクト一覧</title> |
| | 143 | </head> |
| | 144 | <body> |
| | 145 | <h1>プロジェクト一覧</h1> |
| | 146 | <ul> |
| | 147 | <li py:for="project in projects" py:choose=""> |
| | 148 | <a py:when="project.href" href="$project.href" |
| | 149 | title="$project.description">$project.name</a> |
| | 150 | <py:otherwise> |
| | 151 | <small>$project.name: <em>エラー</em> <br /> ($project.description)</small> |
| | 152 | </py:otherwise> |
| | 153 | </li> |
| | 154 | </ul> |
| | 155 | </body> |
| 108 | | |
| 109 | | == メインテンプレート == |
| 110 | | |
| 111 | | Trac の [http://www.clearsilver.net/ ClearSilver] テンプレートについても、カスタマイズしたバージョンを使用することが出来ます。 Note: Trac をアップグレードするときに多くの問題が発生するので、このテクニックは推奨されません: 残念ながら、テンプレートとアプリケーションコードの間には、フォームフィールドの名前やテンプレートデータの構造など、いくつか依存関係があります。また、これらは今後の Trac のバージョン間で互換性を持たないこともあります。 |
| 112 | | |
| 113 | | どうしてもテンプレートを変更する必要があるなら、デフォルトのテンプレートディレクトリ (通常は `$prefix/share/trac/templates`) から、 Trac Environment の `templates` ディレクトリにテンプレートファイルをコピーして、必要な結果が得られるようにコピーの方を変更してください。 |
| 114 | | |
| | 178 | [wiki:TracStandalone] の tracd を動かすのに使用するシェルの中で `TRAC_ENV_INDEX_TEMPLATE` の環境変数を設定する必要があるでしょう: |
| | 179 | - Unix |
| | 180 | {{{ |
| | 181 | #!sh |
| | 182 | $ export TRAC_ENV_INDEX_TEMPLATE=/path/to/template |
| | 183 | }}} |
| | 184 | - Windows |
| | 185 | {{{ |
| | 186 | #!sh |
| | 187 | $ set TRAC_ENV_INDEX_TEMPLATE=/path/to/template |
| | 188 | }}} |
| | 189 | |
| | 190 | == プロジェクトテンプレート == # ProjectTemplates |
| | 191 | |
| | 192 | 個々の Trac Environment (プロジェクトのインスタンス) の外観は、同じサーバにホストされている他のプロジェクトとは独立してカスタマイズできます。推奨するのは `site.html` テンプレート ([#SiteAppearance サイトの外観] 参照) を使う方法です。どのような場合でも可能な限り、この方法にしてください。 `site.html` を使う場合、変更はオリジナルのテンプレートがレンダリングした結果に対して適用されるので、 Trac を今後アップグレードした後も、通常はカスタマイズをそのまま使い続けることができます。 `theme.html` や他の Trac のテンプレートのコピーを作成する方法の場合、新しい Trac の機能追加や不具合修正の結果、動かなくなってしまったカスタマイズを新しいバージョンに移行する必要があるかもしれません。 |
| | 193 | |
| | 194 | リスクを許容して扱う必要はありますが、 Trac テンプレートはコピーしてカスタマイズすることもできます。デフォルトの Trac テンプレートはインストールされた Trac egg (`/usr/lib/pythonVERSION/site-packages/Trac-VERSION.egg/trac/templates, .../trac/ticket/templates, .../trac/wiki/templates, ++`) 内に配置されています。 [#ProjectList プロジェクトリスト] のテンプレートファイルは `index.html` が使用されており、各ページに共通する主要なレイアウトを提供するテンプレートは `theme.html` が使用されます。画像や CSS スタイルシートなどのページの部品は、 egg の `trac/htdocs` ディレクトリに配置されています。 |
| | 195 | |
| | 196 | しかし、 Trac egg 内部のテンプレートやサイトのリソースは編集しないでください。 Trac を再インストールしたときに、カスタマイズの内容が完全に失われてしまいます。代わりに、以下に挙げる方法のいずれかを使ってください: |
| | 197 | * カスタマイズが単独のプロジェクトに閉じているのであれば、テンプレートをプロジェクトの `templates` ディレクトリにコピーしてください。 |
| | 198 | * カスタマイズが複数のプロジェクトに渡るものであるなら、テンプレートを共有のロケーションにコピーし、各プロジェクトからは trac.ini の `[inherit] templates_dir =` オプションで、その位置を指定してください。 |
| | 199 | |
| | 200 | Trac は以下の順序で、テンプレートファイルを探します。まず、プロジェクトの内部を探し、存在しなければ inherit で指定された場所、最後に Trac egg の内部を探します。 |
| | 201 | |
| | 202 | Trac は通常、パフォーマンスを向上させるために、テンプレートをメモリ上にキャッシュします。変更したテンプレートを適用するためには、 サーバプロセスの再起動が必要です。 |
