| 43 | | 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 |
| 44 | | |
| 45 | | In the following example, we rename the link to the Wiki start "Home", and hide the " |
| | 51 | 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). |
| | 52 | |
| | 53 | 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 . |
| 91 | | Note that this references your environment's `htdocs/style.css`. |
| 92 | | |
| 93 | | Example snippet of adding introduction text to the new ticket form (hide when preview): |
| 94 | | |
| 95 | | {{{ |
| 96 | | #!xml |
| | 100 | |
| | 101 | 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 a CSS file placed into environment's `htdocs/` directory. In a similar fashion `${chrome.htdocs_location}` is used to specify the common `htdocs/` directory belonging to a Trac installation. That latter location can however be overriden using the [[TracIni#trac-config|[trac] htdocs_location]] configuration setting. |
| | 102 | |
| | 103 | `site.html` is one file to contain all your modifications. It usually works using the `py:match` directive (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 |
| | 104 | and modify them. |
| | 105 | See [http://groups.google.com/group/trac-users/browse_thread/thread/70487fb2c406c937/ this thread] for a detailed explanation of the above example `site.html`. |
| | 106 | A `site.html` can contain any number of such `py:match` sections for whatever you need to modify. This is all Genshi, so the [http://genshi.edgewall.org/wiki/Documentation/xml-templates.html docs on the exact syntax] can be found there. |
| | 107 | |
| | 108 | |
| | 109 | Example snippet of adding introduction text to the new ticket form (but not shown during preview): |
| | 110 | |
| | 111 | {{{#!xml |
| 105 | | 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: |
| | 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: |
| 117 | | 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. |
| 118 | | |
| 119 | | == Project List == |
| 120 | | You can use a custom ClearSilver template to display the list of projects if you are using Trac with multiple projects. |
| | 138 | Also note that the `site.html` (despite its name) can be put in a common templates directory - see the [[TracIni#inherit-section|[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. |
| | 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. |
| | 221 | |
