| 41 | | == サイトヘッダとサイトフッタ == |
| 42 | | それぞれのプロジェクトの Trac Environment フォルダには {{{templates}}} ディレクトリがあります。このフォルダには {{{site_header.cs}}} と {{{site_footer.cs}}} というファイルがあります。これらのファイルに HTML マークアップされた内容を追加することで、ユーザは Trac サイトをカスタマイズできます。2つのファイルはサイト内で {{{<body>}}} タグの直後と、 {{{</body>}}} タグの直前にそれぞれ展開されます。 |
| 43 | | |
| 44 | | これらのファイルでは、静的な HTML を記述することが出来ます。動的に生成されるコンテンツを置きたい場合、 [http://www.clearsilver.net/ ClearSilver] テンプレート言語も使用できます。テンプレートで利用可能な変数を見たい場合、 Trac に接続している URL にクエリ文字列 `?hdfdump=1` を追加してください。テンプレートデータを構造化表示できます。 |
| 45 | | |
| 46 | | == サイト CSS == |
| 47 | | Trac サイトのレイアウトを調整する主な方法は [http://www.w3.org/TR/REC-CSS2/ CSS] にスタイルのルールを追加し、デフォルトのルールをオーバレイすることです。このためのベストなやり方は、 Trac Environment の `templates` ディレクトリにあるファイル `site_css.cs` を編集することです。 テンプレートから取得したコンテンツは、 Trac が生成する全ての HTML ページで `<style type="text/css></style>` 要素に挿入されます。 |
| 48 | | |
| 49 | | カスタマイズしたスタイルのルールを `site_css.cs` ファイルに直接書くことも出来ますが、単に外部のスタイルシートへの参照を記述するのを推奨します。その結果、応答のたびにルールを送信するのではなく、ブラウザが CSS ファイルをキャッシュするのを可能にします。 |
| 50 | | |
| 51 | | この例はホストの `style` ディレクトリに配置したスタイルシートをインポートする書き方です: |
| 52 | | {{{ |
| 53 | | @import url(/style/mytrac.css); |
| 54 | | }}} |
| 55 | | |
| 56 | | !ClearSilver の変数を使用することで、 Trac Environment の `htdocs` ディレクトリに格納したスタイルシートを参照させることが出来ます。 |
| 57 | | {{{ |
| 58 | | @import url(<?cs var:chrome.href ?>/site/style.css); |
| 59 | | }}} |
| 60 | | |
| 61 | | == メインテンプレート == |
| 62 | | |
| 63 | | Trac の [http://www.clearsilver.net/ ClearSilver] テンプレートについても、カスタマイズしたバージョンを使用することが出来ます。 Note: Trac をアップグレードするときに多くの問題が発生するので、このテクニックは推奨されません: 残念ながら、テンプレートとアプリケーションコードの間には、フォームフィールドの名前やテンプレートデータの構造など、いくつか依存関係があります。また、これらは今後の Trac のバージョン間で互換性を持たないこともあります。 |
| 64 | | |
| 65 | | どうしてもテンプレートを変更する必要があるなら、デフォルトのテンプレートディレクトリ (通常は `$prefix/share/trac/templates`) から、 Trac Environment の `templates` ディレクトリにテンプレートファイルをコピーして、必要な結果が得られるようにコピーの方を変更してください。 |
| 66 | | |
| 67 | | |
| | 42 | Should your browser have issues with your favicon showing up in the address bar, you may put a "?" (less the quotation marks) after your favicon file extension. |
| | 43 | |
| | 44 | {{{ |
| | 45 | [project] |
| | 46 | icon = /favicon.ico? |
| | 47 | }}} |
| | 48 | |
| | 49 | == Custom Navigation Entries == |
| | 50 | The new [mainnav] and [metanav] can now be used to customize the text and link used for the navigation items, or even to disable them (but not for adding new ones). |
| | 51 | |
| | 52 | In the following example, we rename the link to the Wiki start "Home", and hide the "Help/Guide". We also make the "View Tickets" entry link to a specific report . |
| | 53 | {{{ |
| | 54 | [mainnav] |
| | 55 | wiki.label = Home |
| | 56 | tickets.href = /report/24 |
| | 57 | |
| | 58 | [metanav] |
| | 59 | help = disabled |
| | 60 | }}} |
| | 61 | |
| | 62 | See also TracNavigation for a more detailed explanation of the mainnav and metanav terms. |
| | 63 | |
| | 64 | == Site Appearance == #SiteAppearance |
| | 65 | |
| | 66 | Trac is using [http://genshi.edgewall.org Genshi] as the templating engine. Documentation is yet to be written, in the meantime the following tip should work. |
| | 67 | |
| | 68 | Say you want to add a link to a custom stylesheet, and then your own |
| | 69 | header and footer. Save the following content as 'site.html' inside your projects templates directory (each Trac project can have their own site.html), e.g. {{{/path/to/env/templates/site.html}}}: |
| | 70 | |
| | 71 | {{{ |
| | 72 | #!xml |
| | 73 | <html xmlns="http://www.w3.org/1999/xhtml" |
| | 74 | xmlns:py="http://genshi.edgewall.org/" |
| | 75 | py:strip=""> |
| | 76 | |
| | 77 | <!--! Add site-specific style sheet --> |
| | 78 | <head py:match="head" py:attrs="select('@*')"> |
| | 79 | ${select('*|comment()|text()')} |
| | 80 | <link rel="stylesheet" type="text/css" |
| | 81 | href="${href.chrome('site/style.css')}" /> |
| | 82 | </head> |
| | 83 | |
| | 84 | <body py:match="body" py:attrs="select('@*')"> |
| | 85 | <!--! Add site-specific header --> |
| | 86 | <div id="siteheader"> |
| | 87 | <!--! Place your header content here... --> |
| | 88 | </div> |
| | 89 | |
| | 90 | ${select('*|text()')} |
| | 91 | |
| | 92 | <!--! Add site-specific footer --> |
| | 93 | <div id="sitefooter"> |
| | 94 | <!--! Place your footer content here... --> |
| | 95 | </div> |
| | 96 | </body> |
| | 97 | </html> |
| | 98 | }}} |
| | 99 | |
| | 100 | Those who are familiar with XSLT may notice that Genshi templates bear some similarities. However, there are some Trac specific features - for example '''${href.chrome('site/style.css')}''' attribute references template placed into environment's ''htdocs/'' In a similar fashion '''${chrome.htdocs_location}''' is used to specify common ''htdocs/'' directory from Trac installation. |
| | 101 | |
| | 102 | `site.html` is one file to contain all your modifications. It usually works by the py:match (element or attribute), and it allows you to modify the page as it renders - the matches hook onto specific sections depending on what it tries to find |
| | 103 | and modify them. |
| | 104 | See [http://groups.google.com/group/trac-users/browse_thread/thread/70487fb2c406c937/ this thread] for a detailed explanation of the above example `site.html`. |
| | 105 | A site.html can contain any number of such py:match sections for whatever you need to modify. This is all [http://genshi.edgewall.org/ Genshi], so the docs on the exact syntax can be found there. |
| | 106 | |
| | 107 | |
| | 108 | Example snippet of adding introduction text to the new ticket form (hide when preview): |
| | 109 | |
| | 110 | {{{ |
| | 111 | #!xml |
| | 112 | <form py:match="div[@id='content' and @class='ticket']/form" py:attrs="select('@*')"> |
| | 113 | <py:if test="req.environ['PATH_INFO'] == '/newticket' and (not 'preview' in req.args)"> |
| | 114 | <p>Please make sure to search for existing tickets before reporting a new one!</p> |
| | 115 | </py:if> |
| | 116 | ${select('*')} |
| | 117 | </form> |
| | 118 | }}} |
| | 119 | |
| | 120 | This example illustrates a technique of using '''`req.environ['PATH_INFO']`''' to limit scope of changes to one view only. For instance, to make changes in site.html only for timeline and avoid modifying other sections - use ''`req.environ['PATH_INFO'] == '/timeline'`'' condition in <py:if> test. |
| | 121 | |
| | 122 | More examples snippets for `site.html` can be found at [trac:wiki:CookBook/SiteHtml CookBook/SiteHtml]. |
| | 123 | |
| | 124 | Example snippets for `style.css` can be found at [trac:wiki:CookBook/SiteStyleCss CookBook/SiteStyleCss]. |
| | 125 | |
| | 126 | If the environment is upgraded from 0.10 and a `site_newticket.cs` file already exists, it can actually be loaded by using a workaround - providing it contains no ClearSilver processing. In addition, as only one element can be imported, the content needs some sort of wrapper such as a `<div>` block or other similar parent container. The XInclude namespace must be specified to allow includes, but that can be moved to document root along with the others: |
| | 127 | {{{ |
| | 128 | #!xml |
| | 129 | <form py:match="div[@id='content' and @class='ticket']/form" py:attrs="select('@*')" |
| | 130 | xmlns:xi="http://www.w3.org/2001/XInclude"> |
| | 131 | <py:if test="req.environ['PATH_INFO'] == '/newticket' and (not 'preview' in req.args)"> |
| | 132 | <xi:include href="site_newticket.cs"><xi:fallback /></xi:include> |
| | 133 | </py:if> |
| | 134 | ${select('*')} |
| | 135 | </form> |
| | 136 | }}} |
| | 137 | |
| | 138 | Also note that the `site.html` (despite its name) can be put in a common templates directory - see the `[inherit] templates_dir` option. This could provide easier maintainence (and a migration path from 0.10 for larger installations) as one new global `site.html` file can be made to include any existing header, footer and newticket snippets. |
| | 139 | |
| | 140 | == Project List == #ProjectList |
| | 141 | |
| | 142 | You can use a custom Genshi template to display the list of projects if you are using Trac with multiple projects. |
| | 143 | |
| | 144 | The following is the basic template used by Trac to display a list of links to the projects. For projects that could not be loaded it displays an error message. You can use this as a starting point for your own index template. |
| | 145 | |
| | 146 | {{{ |
| | 147 | #!text/html |
| | 148 | <!DOCTYPE html |
| | 149 | PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" |
| | 150 | "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> |
| | 151 | <html xmlns="http://www.w3.org/1999/xhtml" |
| | 152 | xmlns:py="http://genshi.edgewall.org/" |
| | 153 | xmlns:xi="http://www.w3.org/2001/XInclude"> |
| | 154 | <head> |
| | 155 | <title>Available Projects</title> |
| | 156 | </head> |
| | 157 | <body> |
| | 158 | <h1>Available Projects</h1> |
| | 159 | <ul> |
| | 160 | <li py:for="project in projects" py:choose=""> |
| | 161 | <a py:when="project.href" href="$project.href" |
| | 162 | title="$project.description">$project.name</a> |
| | 163 | <py:otherwise> |
| | 164 | <small>$project.name: <em>Error</em> <br /> ($project.description)</small> |
| | 165 | </py:otherwise> |
| | 166 | </li> |
| | 167 | </ul> |
| | 168 | </body> |
| | 169 | </html> |
| | 170 | }}} |
| | 171 | |
| | 172 | Once you've created your custom template you will need to configure the webserver to tell Trac where the template is located (pls verify ... not yet changed to 0.11): |
| | 173 | |
| | 174 | For [wiki:TracModWSGI mod_wsgi]: |
| | 175 | {{{ |
| | 176 | os.environ['TRAC_ENV_INDEX_TEMPLATE'] = '/path/to/template' |
| | 177 | }}} |
| | 178 | |
| | 179 | For [wiki:TracFastCgi FastCGI]: |
| | 180 | {{{ |
| | 181 | FastCgiConfig -initial-env TRAC_ENV_PARENT_DIR=/parent/dir/of/projects \ |
| | 182 | -initial-env TRAC_ENV_INDEX_TEMPLATE=/path/to/template |
| | 183 | }}} |
| | 184 | |
| | 185 | For [wiki:TracModPython mod_python]: |
| | 186 | {{{ |
| | 187 | PythonOption TracEnvParentDir /parent/dir/of/projects |
| | 188 | PythonOption TracEnvIndexTemplate /path/to/template |
| | 189 | }}} |
| | 190 | |
| | 191 | For [wiki:TracCgi CGI]: |
| | 192 | {{{ |
| | 193 | SetEnv TRAC_ENV_INDEX_TEMPLATE /path/to/template |
| | 194 | }}} |
| | 195 | |
| | 196 | For [wiki:TracStandalone], you'll need to set up the `TRAC_ENV_INDEX_TEMPLATE` environment variable in the shell used to launch tracd: |
| | 197 | - Unix |
| | 198 | {{{ |
| | 199 | #!sh |
| | 200 | $ export TRAC_ENV_INDEX_TEMPLATE=/path/to/template |
| | 201 | }}} |
| | 202 | - Windows |
| | 203 | {{{ |
| | 204 | #!sh |
| | 205 | $ set TRAC_ENV_INDEX_TEMPLATE=/path/to/template |
| | 206 | }}} |
| | 207 | |
| | 208 | == Project Templates == |
| | 209 | |
| | 210 | The appearance of each individual Trac environment (that is, instance of a project) can be customized independently of other projects, even those hosted by the same server. The recommended way is to use a `site.html` template (see [#SiteAppearance]) whenever possible. Using `site.html` means changes are made to the original templates as they are rendered, and you should not normally need to redo modifications whenever Trac is upgraded. If you do make a copy of `theme.html` or any other Trac template, you need to migrate your modifiations to the newer version - if not, new Trac features or bug fixes may not work as expected. |
| | 211 | |
| | 212 | With that word of caution, any Trac template may be copied and customized. The default Trac templates are located inside the installed Trac egg (`/usr/lib/pythonVERSION/site-packages/Trac-VERSION.egg/trac/templates, .../trac/ticket/templates, .../trac/wiki/templates, ++`). The [#ProjectList] template file is called `index.html`, while the template responsible for main layout is called `theme.html`. Page assets such as images and CSS style sheets are located in the egg's `trac/htdocs` directory. |
| | 213 | |
| | 214 | However, do not edit templates or site resources inside the Trac egg - installing Trac again can completely delete your modifications. Instead use one of two alternatives: |
| | 215 | * For a modification to one project only, copy the template to project `templates` directory. |
| | 216 | * For a modification shared by several projects, copy the template to a shared location and have each project point to this location using the `[inherit] templates_dir =` trac.ini option. |
| | 217 | |
| | 218 | Trac resolves requests for a template by first looking inside the project, then in any inherited templates location, and finally inside the Trac egg. |
| | 219 | |
| | 220 | Trac caches templates in memory by default to improve performance. To apply a template you need to restart the server. |
