= Customizing the Trac Interface (//Jinja2 edition//)
== Site Appearance #SiteAppearance
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
for that in the default theme.html and layout.html templates governing the
standard layout of Trac pages by including three custom templates:
- `site_head.html`, for adding customized content to the element
- `site_header.html`, for adding customized content at the beginning of the
element
- `site_footer.html`, for adding customized content at the end of the
element
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`:
{{{#!html+jinja
## Add site-specific style sheet
}}}
Likewise, for `site_header.html`:
{{{#!html+jinja
## Add site-specific header
}}}
And for `site_footer.html`:
{{{#!html+jinja
## Add site-specific footer
}}}
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.
Example snippet of adding introduction text to the new ticket form (but not shown during preview):
In `site_header.html`:
{{{#!html+jinja
# if req.path_info == '/newticket' and (not 'preview' in req.args):
Please make sure to search for existing tickets before reporting a new one!
# endif
}}}
Alternatively, the text can be present in a separate template:
{{{#!html+jinja
# if req.path_info == '/newticket' and (not 'preview' in req.args):
# include "site_newticket.html"
# endif
}}}
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.
More examples snippets for `site.html` can be found at [trac:wiki:CookBook/SiteHtml CookBook/SiteHtml]. (TODO)
Example snippets for `style.css` can be found at [trac:wiki:CookBook/SiteStyleCss CookBook/SiteStyleCss].
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.