If there is one thing that annoys me it is the lack of helpful documentation around a task for popular scripts and applications. One of those such tasks is Building a Trac Theme. This will be the first guide I have compiled and I don’t intend on making it my last, so feedback and comments would be welcomed.
Before we begin, I will be assuming that you have installed Trac, have it running on your server and do not have additional themes installed.
Step 1
Build a simple HTML and CSS design that you wish to use as the theme for Trac. While building this it is best that the number of images used in the HTML is kept to a minimum. Best option is to only have the logo defined in an image (img) tag within the design. The logo can be defined in your trac.ini file. This will make it easier for you to make changes to the logo and logo related information without changing the template.
Step 2
This part can get a bit messy but you should be alright if you understand the basics of HTML. You will need to place some extra code into the HTML for the theme to work, and so it can display the menus.
Important Areas
HTML (Opening HTML Tag)
Replace the opening HTML tag with the following code
<html xmlns="http://www.w3.org/1999/xhtml" xmlns:py="http://genshi.edgewall.org/" py:strip="">
HEAD (Entire Head)
Replace the entire HEAD section with the following code
<head py:mathc="head" py:attrs="select('@*')"> ${select('*')} </head>
BODY (Opening BODY Tag)
Replace the opening BODY tag with the following code
<body py:match="body" py:attrs="select('@*')">
Logo
The logo is set using the trac.ini file. The following variables will set your logo in your trac.ini.
[header_logo] alt = Trac Name height = 100 link = http://www.yoururl.com/ src = yourlogo.jpg width = 200
After you have set your logo up you then need to place the following code into your HTML file where you want the logo to appear
<a href="${chrome.logo.link}"> <img longdesc="${chrome.logo.alt}" src="${chrome.logo.src}" alt="${chrome.logo.alt}" width="${chrome.logo.width}" height="${chrome.logo.height}" /> </a>
Navigation Bars
There are three different navigation bars in Trac;
- Meta Navigation: The one that has links to Login, Logout, Preferences and Help/Guide
- Content Text Navigation: The navigation bar that has the links Start Page, Index, History and Last Change on it.
- Main Mavigation: This is the main navigation for Trac and will have links to Wiki, Timeline, Roadmap, Browse Source, View Tickets, New Ticket and Admin
To display each of these menus place the code for that menu in the HTML where you want it to display. Each menu is output as an unordered list and is best placed within a div tag.
Meta Navigation
<ul> <li> ${item.label}</li> </ul>
Content Text Navigation
<ul> <li class="${classes(first_last(i, chrome.ctxtnav), active=elm.active)}"> $elm</li> </ul>
Main Navigation
<ul> <li class="${classes(first_last(idx, chrome.nav['mainnav']), active=item.active)}"> ${item.label}</li> </ul>
Content
The rest of the content of the page can be called by a very simple piece of code. Just place this code where you want the bulk of the content to appear.
${select('*')}
Step 3
The easiest way to package a theme is to place it in an SVN repository. The repository will need to have the following structure.
- themename (All lowercase)
- htdocs
-
- (Contains all the CSS and image files for the theme)
- templates
-
- name_theme.html (This is the file that was created in step 2)
- theme.py
- setup.py
Create a new SVN repository and then import the theme files in it and commit.
Step 4
The following command will pull down a copy of the SVN repository and package it into a Python .egg file.
easy_install -d "/path/to/packages/" svn://directtory/to/svn/repository
Step 5
The next step is to install the Trac Theme Engine
See ThemeEnginePlugin on Trac Hacks.
Step 6
The final thing to do is to enable the theme. Place the following parts of the code in the trac.ini.
[components] themename.* = enabled [theme] theme = name-of-theme
Hi Derek, nice intro to templates for Trac. The Files setup.py and theme.py from step 3 are somewhat missing
Can you reupload them?
thx Bastian
Bastian, I have sent you the files to your email address. Thank you for the comment.