Changes between Initial Version and Version 1 of TracInterfaceCustomization


Ignore:
Timestamp:
Jun 4, 2009 4:14:46 PM (15 years ago)
Author:
trac
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • 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カスタムスタイルシートへのリンクや、独自のヘッダやフッタを追加したい場合、 
     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 
     93XSLT に慣れ親しんだ人であれば、 Genshi テンプレートには類似点があるのに気付くかもしれません。しかしながら Trac 固有の機能もあります。例えば '''${href.chrome('site/style.css')}''' は Environment に含まれる ''htdocs/'' にあるファイルへの参照の属性に置き換えられます。 '''${chrome.htdocs_location}''' は似ていますが、 Trac インストール時に作成された共通の ''htdocs/'' ディレクトリを指定するために使用します。 
     94 
     95site.html はサイト固有のすべての変更を含んでいる一つのファイルです。通常は、要素 (element) または属性 (attribute) として py:match を使用することでレンダリングされるページを変更することができるようになります。 py:match は特定のセクションに依存した記載が行われており、ページを検索してマッチした箇所を変更します。 
     96site.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 
     1130.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 が使用している、ホストするプロジェクトへのリンクのリストを表示するための基本のテンプレートです。ロードできないプロジェクトについては、エラーメッセージを表示します。これをあなた自身のインデックステンプレートのスタートポイントとして使用することができます。 
     132 
     133{{{ 
     134#!text/html 
     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> 
     156</html> 
     157}}} 
     158 
     159カスタムテンプレートを使用する場合、 Web サーバにテンプレートのロケーションの設定を読み込ませる必要があります (確かめてみてください ... まだ 0.11 向けに変更していません): 
     160 
     161[wiki:TracFastCgi FastCGI] 用: 
     162{{{ 
     163FastCgiConfig -initial-env TRAC_ENV_PARENT_DIR=/parent/dir/of/projects \ 
     164              -initial-env TRAC_ENV_INDEX_TEMPLATE=/path/to/template 
     165}}} 
     166 
     167[wiki:TracModPython mod_python] 用: 
     168{{{ 
     169PythonOption TracEnvParentDir /parent/dir/of/projects 
     170PythonOption TracEnvIndexTemplate /path/to/template 
     171}}} 
     172 
     173[wiki:TracCgi CGI] 用: 
     174{{{ 
     175SetEnv TRAC_ENV_INDEX_TEMPLATE /path/to/template 
     176}}} 
     177 
     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 
     200Trac は以下の順序で、テンプレートファイルを探します。まず、プロジェクトの内部を探し、存在しなければ inherit で指定された場所、最後に Trac egg の内部を探します。 
     201 
     202Trac は通常、パフォーマンスを向上させるために、テンプレートをメモリ上にキャッシュします。変更したテンプレートを適用するためには、 サーバプロセスの再起動が必要です。 
     203---- 
     204See also TracGuide, TracIni