| 46 | | These files may contain static HTML, though if users desire to have dynamically generated content they can make use of the [http://www.clearsilver.net/ ClearSilver] templating language from within the pages as well. When you need to see what variables are available to the template, append the query string `?hdfdump=1` to the URL of your Trac site. This will display a structured view of the template data. |
| 47 | | |
| 48 | | == Site CSS == |
| 49 | | The primary means to adjust the layout of a Trac site is to add [http://www.w3.org/TR/REC-CSS2/ CSS] style rules that overlay the default rules. This is best done by editing the `site_css.cs` file in the enviroment's `templates` directory. The content of that template gets inserted into a `<style type="text/css"></style>` element on every HTML page generated by Trac. |
| 50 | | |
| 51 | | While you can add your custom style rules directly to the `site_css.cs` file, it is recommended that you simply reference an external style sheet, thereby enabling browsers to cache the CSS file instead of transmitting the rules with every response. |
| 52 | | |
| 53 | | The following example would import a style sheet located in the `style` root directory of your host: |
| 54 | | {{{ |
| 55 | | @import url(/style/mytrac.css); |
| | 51 | [metanav] |
| | 52 | help = disabled |
| 58 | | You can use a !ClearSilver variable to reference a style sheet stored in the project environment's `htdocs` directory: |
| | 55 | See also TracNavigation for a more detailed explanation of the mainnav and metanav terms. |
| | 56 | |
| | 57 | == Site Appearance == #SiteAppearance |
| | 58 | |
| | 59 | 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. |
| | 60 | |
| | 61 | Say you want to add a link to a custom stylesheet, and then your own |
| | 62 | header and footer. Create a file {{{/path/to/env/templates/site.html}}} or {{{/path/to/inherit/option/templates_dir/site.html}}}, with contents like this: |
| | 63 | |
| 60 | | @import url(<?cs var:chrome.href ?>/site/style.css); |
| | 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 | Note that this references your environment's `htdocs/style.css`. |
| | 93 | |
| | 94 | Example snippet of adding introduction text to the new ticket form (hide when preview): |
| | 95 | |
| | 96 | {{{ |
| | 97 | #!xml |
| | 98 | <form py:match="div[@id='content' and @class='ticket']/form" py:attrs="select('@*')"> |
| | 99 | <py:if test="req.environ['PATH_INFO'] == '/newticket' and (not 'preview' in req.args)"> |
| | 100 | <p>Please make sure to search for existing tickets before reporting a new one!</p> |
| | 101 | </py:if> |
| | 102 | ${select('*')} |
| | 103 | </form> |
| 63 | | == Project List == |
| 64 | | You can use a custom ClearSilver template to display the list of projects if you are using Trac with multiple projects. |
| | 106 | If the environment is upgraded from 0.10 and a `site_newticket.cs` file already exists, it can actually be loaded by using a workaroud - 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: |
| | 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 | 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. |
| | 119 | |
| | 120 | == Project List == #ProjectList |
| | 121 | |
| | 122 | You can use a custom Genshi template to display the list of projects if you are using Trac with multiple projects. |
| 70 | | <html> |
| 71 | | <head><title>Available Projects</title></head> |
| 72 | | <body> |
| 73 | | <h1>Available Projects</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>Error</em> <br /> |
| 81 | | (<?cs var:project.description ?>)</small><?cs |
| 82 | | /if ?> |
| 83 | | </li><?cs |
| 84 | | /each ?> |
| 85 | | </ul> |
| 86 | | </body> |
| | 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>Available Projects</title> |
| | 136 | </head> |
| | 137 | <body> |
| | 138 | <h1>Available Projects</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>Error</em> <br /> ($project.description)</small> |
| | 145 | </py:otherwise> |
| | 146 | </li> |
| | 147 | </ul> |
| | 148 | </body> |
| 113 | | If you absolutely need to use modified templates, copy the template files from the default templates directory (usually in found in `$prefix/share/trac/templates`) into the `templates` directory of the project environment. Then modify those copies to get the desired results. |
| | 187 | 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. |
| | 188 | |
| | 189 | 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: |
| | 190 | * For a modification to one project only, copy the template to project `templates` directory. |
| | 191 | * 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. |
| | 192 | |
| | 193 | Trac resolves requests for a template by first looking inside the project, then in any inherited templates location, and finally inside the Trac egg. |
