トップ | バージョン2 最新版 | バージョン3 β版

初期バージョン から バージョン 1 における更新: TracInterfaceCustomization

差分発生行の前後
無視リスト:
更新日時:
2009/01/08 04:02:11 (12 年 前)
更新者:
trac (IP アドレス: 127.0.0.1)
コメント:

--

凡例:

変更なし
追加
削除
変更
  • TracInterfaceCustomization

    v1 v1  
     1= Trac のインタフェースをカスタマイズする = #CustomizingtheTracInterface 
     2[[TracGuideToc]] 
     3 
     4== イントロダクション == #Introduction 
     5このページは Trac の外観をカスタマイズする方法をユーザに提案するために書きました。主要な話題は HTML テンプレートと CSS ファイルであり、プログラムコードではありません。ユーザ自身の特定のニーズを満たすために Trac の外観を変更する方法を、ユーザに示すことを意図しています。 Trac の全てのユーザにとって有益な、インタフェース変更の提案は、このページに書くのではなくチケットを使用してください。 [[BR]] '''(訳注: 本家サイトのチケットの話です)''' 
     6 
     7== プロジェクトのロゴとアイコン == #ProjectLogoandIcon 
     8Trac のインタフェースをカスタマイズする中で、最も簡単なのは、ロゴとサイトアイコンです。両方とも [wiki:TracIni trac.ini] に設定するだけで構成できます。 
     9 
     10ロゴやアイコンのイメージは、 Trac Environment フォルダの中の "htdocs" というフォルダに置かなければいけません。 (''Note: バージョン 0.9 以前の Trac で作成したプロジェクトでは、このフォルダを自分で作成する必要があります'') 
     11 
     12 ''Note: 実際は、ロゴとアイコンはサーバのどこのパスにおいてもかまいません(Web サーバがアクセスできるところならですが)。設定の中でそれらの絶対またはサーバの相対 URL を使用します。'' 
     13 
     14[wiki:TracIni trac.ini] の適切なセクションの構成は以下の通りです: 
     15 
     16=== ロゴ === #Logo 
     17`src` の設定を `site/` に続く画像ファイルの名前に変更してください。 `width` と `height` は画像ファイルにあわせて設定を変更してください。(Trac の chrome ハンドラはプロジェクトのディレクトリ `htdocs` と "`common/`" の中のファイル用に "`site/`" を使用します。) 
     18 
     19{{{ 
     20[header_logo] 
     21src = site/my_logo.gif 
     22alt = My Project 
     23width = 300 
     24height = 100 
     25}}} 
     26 
     27=== アイコン === #Icon 
     28アイコンは `.gif` か `.ico` 形式の 16x16 の画像である必要があります。 `icon` の設定を `site/` に続くアイコンファイルの名前に変更してください。アイコンは通常、サイトの URL の横や、 `ブックマーク` メニューに表示されます。 
     29 
     30{{{ 
     31[project] 
     32icon = site/my_icon.ico 
     33}}} 
     34 
     35Note: Internet Explorer では、ホストのルートディレクトリにある ``favicon.ico`` という名前のファイルしか許容しないため、このアイコンは無視されます。プロジェクトアイコンを IE と他のブラウザで共用したい場合、アイコンをホストのドキュメントルートに配置し、 ``trac.ini`` から以下のように参照します: 
     36 
     37{{{ 
     38[project] 
     39icon = /favicon.ico 
     40}}} 
     41 
     42== ナビゲーション項目のカスタマイズ == #CustomNavigationEntries 
     43[mainnav] と [metanav] を使用すると、ナビゲーション項目に使用されるテキストとリンクをカスタマイズしたり、無効化することができます (新規項目を追加することはできません)。 
     44 
     45以下の例では、 Wiki のスタートページへのリンク名を "Home" に変更して、 "Help/Guide" を非表示にします。さらに、 "View Tickets" エントリを特定のレポートにリンクさせます。 
     46{{{ 
     47[mainnav] 
     48wiki.label = Home 
     49tickets.href = /report/24 
     50 
     51[metanav] 
     52help = disabled 
     53}}} 
     54 
     55mainnav と metanav についての、より詳細な記述は TracNavigation を参照してください。 
     56 
     57== サイトの外観 == #SiteAppearance 
     58 
     59Trac はテンプレートエンジンに [http://genshi.edgewall.org Genshi] を使用しています。ドキュメントはまだ書かれていませんが、次の tip は動くはずです。 
     60 
     61カスタムスタイルシートへのリンクに加えて、独自のヘッダやフッタを追加したい場合、以下のような内容のファイル {{{/path/to/env/templates/site.html}}} または {{{/path/to/inherit/option/templates_dir/site.html}}} を作成してください: 
     62 
     63{{{ 
     64#!xml 
     65<html xmlns="http://www.w3.org/1999/xhtml" 
     66      xmlns:py="http://genshi.edgewall.org/" 
     67      py:strip=""> 
     68 
     69  <!--! Add site-specific style sheet --> 
     70  <head py:match="head" py:attrs="select('@*')"> 
     71    ${select('*|comment()|text()')} 
     72    <link rel="stylesheet" type="text/css" 
     73          href="${href.chrome('site/style.css')}" /> 
     74  </head> 
     75 
     76  <body py:match="body" py:attrs="select('@*')"> 
     77    <!--! Add site-specific header --> 
     78    <div id="siteheader"> 
     79      <!--! Place your header content here... --> 
     80    </div> 
     81 
     82    ${select('*|text()')} 
     83 
     84    <!--! Add site-specific footer --> 
     85    <div id="sitefooter"> 
     86      <!--! Place your footer content here... --> 
     87    </div> 
     88  </body> 
     89</html> 
     90}}} 
     91Note: この例では、 Environment の `htdocs/style.css` を参照しています。 
     92 
     93チケット登録のフォームに導入テキストを表示する (プレビューが非表示のとき) 場合は、次の例を追加してください。 
     94 
     95{{{ 
     96#!xml 
     97<form py:match="div[@id='content' and @class='ticket']/form" py:attrs="select('@*')"> 
     98  <py:if test="req.environ['PATH_INFO'] == '/newticket' and (not 'preview' in req.args)"> 
     99    <p>Please make sure to search for existing tickets before reporting a new one!</p> 
     100  </py:if> 
     101  ${select('*')}  
     102</form> 
     103}}} 
     104 
     1050.10 からアップグレードされた Environment で、かつ `site_newticket.cs` ファイルが既に存在している場合は、ワークアラウンドすることによってテンプレートをロードすることができます - !ClearSilver の処理が含まれていない場合に限ります (訳注: `<?cs?>` が含まれていない場合) 。また、この場合はただ一つの要素 (element) だけがインポートされるので、コンテンツはある種のラッパー (`<div>` ブロックやそれに似た親コンテナ) を必要とします。インクルードするためには XInclude の名前空間を指定しなければなりませんが、ドキュメントルート以外にも置くことができます: 
     106 
     107{{{ 
     108#!xml 
     109<form py:match="div[@id='content' and @class='ticket']/form" py:attrs="select('@*')" 
     110        xmlns:xi="http://www.w3.org/2001/XInclude"> 
     111  <py:if test="req.environ['PATH_INFO'] == '/newticket' and (not 'preview' in req.args)">  
     112    <xi:include href="site_newticket.cs"><xi:fallback /></xi:include> 
     113  </py:if> 
     114  ${select('*')}  
     115</form> 
     116}}} 
     117 
     118また、共通のテンプレートディレクトリに、 `site.html` (その名前にも関わらず) を置くことができます - `[inherit] templates_dir` オプションを参照してください。新しく、一個のグローバルな `site.html` ファイルに、ヘッダ, フッタ, チケット作成時の tips を組み込むことで、簡単なメンテナンス (および、大きなインストールを行った 0.10 からのバージョンアップのための移行パス) を提供しています。 
     119 
     120== プロジェクトリスト == #ProjectList 
     121 
     122複数の Trac プロジェクトを動かしているときに、カスタマイズした Genshi テンプレートを使用して、プロジェクトの一覧を表示することができます。 
     123 
     124以下に示すのは Trac が使用している、ホストするプロジェクトへのリンクのリストを表示するための基本のテンプレートです。ロードできないプロジェクトについては、エラーメッセージを表示します。これをあなた自身のインデックステンプレートのスタートポイントとして使用することができます。 
     125 
     126{{{ 
     127#!text/html 
     128<!DOCTYPE html 
     129    PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" 
     130    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> 
     131<html xmlns="http://www.w3.org/1999/xhtml" 
     132      xmlns:py="http://genshi.edgewall.org/" 
     133      xmlns:xi="http://www.w3.org/2001/XInclude"> 
     134  <head> 
     135    <title>プロジェクト一覧</title> 
     136  </head> 
     137  <body> 
     138    <h1>プロジェクト一覧</h1> 
     139    <ul> 
     140      <li py:for="project in projects" py:choose=""> 
     141        <a py:when="project.href" href="$project.href" 
     142           title="$project.description">$project.name</a> 
     143        <py:otherwise> 
     144          <small>$project.name: <em>エラー</em> <br /> ($project.description)</small> 
     145        </py:otherwise> 
     146      </li> 
     147    </ul> 
     148  </body> 
     149</html> 
     150}}} 
     151 
     152カスタムテンプレートを使用する場合、 Web サーバにテンプレートのロケーションの設定を読み込ませる必要があります (確かめてみてください ... まだ 0.11 向けに変更していません): 
     153 
     154[wiki:TracFastCgi FastCGI] 用: 
     155{{{ 
     156FastCgiConfig -initial-env TRAC_ENV_PARENT_DIR=/parent/dir/of/projects \ 
     157              -initial-env TRAC_ENV_INDEX_TEMPLATE=/path/to/template 
     158}}} 
     159 
     160[wiki:TracModPython mod_python] 用: 
     161{{{ 
     162PythonOption TracEnvParentDir /parent/dir/of/projects 
     163PythonOption TracEnvIndexTemplate /path/to/template 
     164}}} 
     165 
     166[wiki:TracCgi CGI] 用: 
     167{{{ 
     168SetEnv TRAC_ENV_INDEX_TEMPLATE /path/to/template 
     169}}} 
     170 
     171[wiki:TracStandalone] の tracd を動かすのに使用するシェルの中で `TRAC_ENV_INDEX_TEMPLATE` の環境変数を設定する必要があるでしょう: 
     172 - Unix 
     173   {{{ 
     174#!sh 
     175$ export TRAC_ENV_INDEX_TEMPLATE=/path/to/template 
     176   }}} 
     177 - Windows 
     178   {{{ 
     179#!sh 
     180$ set TRAC_ENV_INDEX_TEMPLATE=/path/to/template 
     181   }}} 
     182 
     183== プロジェクトテンプレート == # ProjectTemplates 
     184 
     185個々の Trac Environment (プロジェクトのインスタンス) の外観は、同じサーバにホストされている他のプロジェクトとは独立してカスタマイズできます。推奨するのは `site.html` テンプレート ([#SiteAppearance サイトの外観] 参照) を使う方法です。どのような場合でも可能な限り、この方法にしてください。 `site.html` を使う場合、変更はオリジナルのテンプレートがレンダリングした結果に対して適用されるので、 Trac を今後アップグレードした後も、通常はカスタマイズをそのまま使い続けることができます。 `theme.html` や他の Trac のテンプレートのコピーを作成する方法の場合、新しい Trac の機能追加や不具合修正の結果、動かなくなってしまったカスタマイズを新しいバージョンに移行する必要があるかもしれません。 
     186 
     187リスクを許容して扱う必要はありますが、 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` ディレクトリに配置されています。 
     188 
     189しかし、 Trac egg 内部のテンプレートやサイトのリソースは編集しないでください。 Trac を再インストールしたときに、カスタマイズの内容が完全に失われてしまいます。代わりに、以下に挙げる方法のいずれかを使ってください: 
     190 * カスタマイズが単独のプロジェクトに閉じているのであれば、テンプレートをプロジェクトの `templates` ディレクトリにコピーしてください。 
     191 * カスタマイズが複数のプロジェクトに渡るものであるなら、テンプレートを共有のロケーションにコピーし、各プロジェクトからは trac.ini の `[inherit] templates_dir =` オプションで、その位置を指定してください。 
     192 
     193Trac は以下の順序で、テンプレートファイルを探します。まず、プロジェクトの内部を探し、存在しなければ inherit で指定された場所、最後に Trac egg の内部を探します。 
     194 
     195---- 
     196See also TracGuide, TracIni