| | 1 | = Customizing the Trac Interface (//Jinja2 edition//) |
| | 2 | |
| | 3 | |
| | 4 | == Site Appearance #SiteAppearance |
| | 5 | |
| | 6 | Trac is now using [http://http://jinja.pocoo.org/ Jinja2] as the templating engine. Say you want to add a link to a custom stylesheet, and then your own header and footer. This is the typical customization pattern, and we prepared |
| | 7 | for that in the default theme.html and layout.html templates governing the |
| | 8 | standard layout of Trac pages by including three custom templates: |
| | 9 | - `site_head.html`, for adding customized content to the <head> element |
| | 10 | - `site_header.html`, for adding customized content at the beginning of the |
| | 11 | <body> element |
| | 12 | - `site_footer.html`, for adding customized content at the end of the |
| | 13 | <body> element |
| | 14 | |
| | 15 | Save the following content as `site_head.html` inside your projects `templates/` directory (each Trac project can have their own `site_head.html` files), e.g. `/path/to/env/templates/site_head.html`: |
| | 16 | |
| | 17 | {{{#!html+jinja |
| | 18 | ## Add site-specific style sheet |
| | 19 | <link rel="stylesheet" href="${href.chrome('site/style.css')}"/> |
| | 20 | }}} |
| | 21 | |
| | 22 | Likewise, for `site_header.html`: |
| | 23 | {{{#!html+jinja |
| | 24 | ## Add site-specific header |
| | 25 | <div id="siteheader"> |
| | 26 | <!--! Place your header content here... --> |
| | 27 | </div> |
| | 28 | }}} |
| | 29 | |
| | 30 | And for `site_footer.html`: |
| | 31 | {{{#!html+jinja |
| | 32 | ## Add site-specific footer |
| | 33 | <div id="sitefooter"> |
| | 34 | <!--! Place your footer content here... --> |
| | 35 | </div> |
| | 36 | }}} |
| | 37 | |
| | 38 | You should refer to the Jinja2 [http://jinja.pocoo.org/docs/dev/ documentation] and also to the syntactical conventions we use in Trac, for example by reading [trac:TracDev/PortingFromGenshiToJinja]. In addition, there are some Trac specific features, for example the `${href.chrome('site/style.css')}` attribute references `style.css` in the 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 overridden using the [[TracIni#trac-section|[trac] htdocs_location]] configuration setting. |
| | 39 | |
| | 40 | |
| | 41 | Example snippet of adding introduction text to the new ticket form (but not shown during preview): |
| | 42 | |
| | 43 | In `site_header.html`: |
| | 44 | {{{#!html+jinja |
| | 45 | # if req.path_info == '/newticket' and (not 'preview' in req.args): |
| | 46 | <p> |
| | 47 | Please make sure to search for existing tickets before reporting a new one! |
| | 48 | </p> |
| | 49 | # endif |
| | 50 | }}} |
| | 51 | Alternatively, the text can be present in a separate template: |
| | 52 | {{{#!html+jinja |
| | 53 | # if req.path_info == '/newticket' and (not 'preview' in req.args): |
| | 54 | # include "site_newticket.html" |
| | 55 | # endif |
| | 56 | }}} |
| | 57 | |
| | 58 | |
| | 59 | This example illustrates a technique of using `req.path_info` to limit scope of changes to one view only. For instance, to make changes in `site_footer.html` only for timeline and avoid modifying other sections - use `req.path_info == '/timeline'` condition in `# if` test. |
| | 60 | |
| | 61 | More examples snippets for `site.html` can be found at [trac:wiki:CookBook/SiteHtml CookBook/SiteHtml]. (TODO) |
| | 62 | |
| | 63 | Example snippets for `style.css` can be found at [trac:wiki:CookBook/SiteStyleCss CookBook/SiteStyleCss]. |
| | 64 | |
| | 65 | Also note that the `site_*.html` files, despite their name, can be put in a shared templates directory, see the [[TracIni#inherit-section|[inherit] templates_dir]] option. |
