Edgewall Software

Version 1 (modified by Christian Boos, 8 years ago) ( diff )

prepare TracInterfaceCustomization#SiteAppearance for Trac 1.3.x

Customizing the Trac Interface (Jinja2 edition)

Site Appearance

Trac is now using ​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 <head> element
  • site_header.html, for adding customized content at the beginning of the <body> element
  • site_footer.html, for adding customized content at the end of the <body> 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: 

## Add site-specific style sheet
<link rel="stylesheet" href="${href.chrome('site/style.css')}"/>

Likewise, for site_header.html: 

## Add site-specific header
<div id="siteheader">
  <!--! Place your header content here... -->
</div>

And for site_footer.html: 

## Add site-specific footer
<div id="sitefooter">
  <!--! Place your footer content here... -->
</div>

You should refer to the Jinja2 ​documentation and also to the syntactical conventions we use in Trac, for example by reading 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 [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: 

# if req.path_info == '/newticket' and (not 'preview' in req.args):
<p>
 Please make sure to search for existing tickets before reporting a new one!
</p>
# endif

Alternatively, the text can be present in a separate template: 

# 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 CookBook/SiteHtml. TODO

Example snippets for style.css can be found at CookBook/SiteStyleCss.

Also note that the site_*.html files, despite their name, can be put in a shared templates directory, see the [inherit] templates_dir option.

Note: See TracWiki for help on using the wiki.