close
Warning:
Can't synchronize with repository "(default)" (/common/SVN/wimax does not appear to be a Subversion repository.). Look in the Trac log for more information.
- Timestamp:
-
Oct 18, 2012, 8:09:28 PM (11 years ago)
- Author:
-
trac
- Comment:
-
—
Legend:
- Unmodified
- Added
- Removed
- Modified
-
v1
|
v2
|
|
1 | 1 | = Customizing the Trac Interface = |
2 | 2 | [[TracGuideToc]] |
| 3 | [[PageOutline]] |
3 | 4 | |
4 | 5 | == Introduction == |
… |
… |
|
15 | 16 | |
16 | 17 | === Logo === |
17 | | Change the `src` setting to `site/` followed by the name of your image file. The `width` and `height` settings should be modified to match your image's dimensions (the Trac chrome handler uses "`site/`" for files within the project directory `htdocs` and "`common/`" for the common ones). |
| 18 | Change the `src` setting to `site/` followed by the name of your image file. The `width` and `height` settings should be modified to match your image's dimensions (the Trac chrome handler uses "`site/`" for files within the project directory `htdocs`, and "`common/`" for the common `htdocs` directory belonging to a Trac installation). Note that 'site/' is not a placeholder for your project name, it is the actual prefix that should be used (literally). For example, if your project is named 'sandbox', and the image file is 'red_logo.gif' then the 'src' setting would be 'site/red_logo.gif', not 'sandbox/red_logo.gif'. |
18 | 19 | |
19 | 20 | {{{ |
… |
… |
|
26 | 27 | |
27 | 28 | === Icon === |
28 | | Icons should be a 16x16 image in `.gif` or `.ico` format. Change the `icon` setting to `site/` followed by the name of your icon file. Icons will typically be displayed by your web browser next to the site's URL and in the `Bookmarks` menu. |
| 29 | Icons should be a 32x32 image in `.gif` or `.ico` format. Change the `icon` setting to `site/` followed by the name of your icon file. Icons will typically be displayed by your web browser next to the site's URL and in the `Bookmarks` menu. |
29 | 30 | |
30 | 31 | {{{ |
… |
… |
|
40 | 41 | }}} |
41 | 42 | |
| 43 | 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. |
| 44 | |
| 45 | {{{ |
| 46 | [project] |
| 47 | icon = /favicon.ico? |
| 48 | }}} |
| 49 | |
42 | 50 | == Custom Navigation Entries == |
43 | 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). |
44 | 52 | |
45 | | 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 | 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 . |
46 | 54 | {{{ |
47 | 55 | [mainnav] |
… |
… |
|
60 | 68 | |
61 | 69 | Say you want to add a link to a custom stylesheet, and then your own |
62 | | 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 | 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}}}: |
63 | 71 | |
64 | 72 | {{{ |
… |
… |
|
91 | 99 | }}} |
92 | 100 | |
93 | | 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. |
94 | | |
95 | | site.html is one file to contain all your modifications. It usually works by the py:match (element of 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 |
96 | | and modify them. 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. |
97 | | |
98 | | |
99 | | Example snippet of adding introduction text to the new ticket form (hide when preview): |
100 | | |
101 | | {{{ |
102 | | #!xml |
| 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 |
103 | 112 | <form py:match="div[@id='content' and @class='ticket']/form" py:attrs="select('@*')"> |
104 | 113 | <py:if test="req.environ['PATH_INFO'] == '/newticket' and (not 'preview' in req.args)"> |
… |
… |
|
109 | 118 | }}} |
110 | 119 | |
111 | | 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. |
| 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]. |
112 | 125 | |
113 | 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: |
… |
… |
|
123 | 136 | }}} |
124 | 137 | |
125 | | 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. |
| 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. |
126 | 139 | |
127 | 140 | == Project List == #ProjectList |
… |
… |
|
159 | 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): |
160 | 173 | |
| 174 | For [wiki:TracModWSGI mod_wsgi]: |
| 175 | {{{ |
| 176 | os.environ['TRAC_ENV_INDEX_TEMPLATE'] = '/path/to/template' |
| 177 | }}} |
| 178 | |
161 | 179 | For [wiki:TracFastCgi FastCGI]: |
162 | 180 | {{{ |
… |
… |
|
201 | 219 | |
202 | 220 | Trac caches templates in memory by default to improve performance. To apply a template you need to restart the server. |
| 221 | |
203 | 222 | ---- |
204 | 223 | See also TracGuide, TracIni |