| 55 | | 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 | |
| 57 | | @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> |
| | 122 | You can use a custom Genshi template to display the list of projects if you are using Trac with multiple projects. |
| | 123 | |
| | 124 | 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. |
| | 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>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> |
| | 149 | </html> |
| | 150 | }}} |
| | 151 | |
| | 152 | 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): |
| | 153 | |
| | 154 | For [wiki:TracFastCgi FastCGI]: |
| | 155 | {{{ |
| | 156 | FastCgiConfig -initial-env TRAC_ENV_PARENT_DIR=/parent/dir/of/projects \ |
| | 157 | -initial-env TRAC_ENV_INDEX_TEMPLATE=/path/to/template |
| | 158 | }}} |
| | 159 | |
| | 160 | For [wiki:TracModPython mod_python]: |
| | 161 | {{{ |
| | 162 | PythonOption TracEnvParentDir /parent/dir/of/projects |
| | 163 | PythonOption TracEnvIndexTemplate /path/to/template |
| | 164 | }}} |
| | 165 | |
| | 166 | For [wiki:TracCgi CGI]: |
| | 167 | {{{ |
| | 168 | SetEnv TRAC_ENV_INDEX_TEMPLATE /path/to/template |
| | 169 | }}} |
| | 170 | |
| | 171 | For [wiki:TracStandalone], you'll need to set up the `TRAC_ENV_INDEX_TEMPLATE` environment variable in the shell used to launch tracd: |
| | 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 | == Project Templates == |
| | 184 | |
| | 185 | 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. |
| | 186 | |
| | 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. |
