Login

Repoze Blog

2007-12-06 00:00:00-05:00

Theming Trac with Deliverance

Click the screenshot images below to see them without scaling.

While in North Carolina to present Repoze to Zope and Python user groups, we worked with our host, Chris Calloway, to help wrap his trac instances within the theming and branding of his project site.

Chris supports SECOORA, a regional marine science collaboration, and needed a way to share branding for the Trac instances he maintains for the various SECOORA software projects.

Installing Trac as a WSGI app

We first worked out how to make Trac installable under Paste. Chris McDonough figured out how to get Trac installed via repoze.project, using a new dependency package, repoze.trac:


$ bin/repozeproject --path=/tmp/trac repoze.trac

Paste configuration

The standard Paste configuration that repoze.trac sets up looks like so:


$ cat etc/paste.ini

[app:trac]

paste.app_factory = repoze.trac:make_trac

path = %(here)s/../var



[pipeline:main]

pipeline = egg:Paste#cgitb

           demo

Setting up the Trac Instance

Before starting the server, we need to initialize the Trac instance in the var directory:


$ bin/trac-admin var initenv

...

Running Trac under Paste

Now we can start the server:


$ bin/paster serve etc/paste.ini

And view the Trac homepage.

Adding Deliverance to the Mix

First, install Deliverance:


$ bin/easy_install Deliverance

...

Then add a minimal rules file defining how Deliverance will merge the application into the theme:


$ cat /etc/minimal_rules.xml

<?xml version="1.0" encoding="UTF-8"?>

<rules xmlns="http://www.plone.org/deliverance" >

  <prepend theme="//head" content="//head/link" nocontent="ignore" /> 

  <prepend theme="//head" content="//head/style" nocontent="ignore" /> 

  <append theme="//head" content="//head/script" nocontent="ignore" />    

  <append theme="//head" content="//head/meta" nocontent="ignore" />

  <copy theme="//table[@id='portal-columns']"

      content="//div[@id='content']" />

</rules>

And configure Deliverance into the pipeline, using those rules:


$ cat /etc/paste.ini

...

[filter:deliverance]

paste.filter_app_factory = deliverance.wsgimiddleware:make_filter

theme_uri = http://secoora.org/

rule_uri = file:///%(here)s/minimal_rules.xml

...

[pipeline:main]

pipeline = egg:Paste#cgitb

           deliverance

           trac

Making Trac's Nav Fit into the Theme

As you can see, the minimal site does not expose any of the standard Trac navigation links: instead, its navigation is thet from the theme (a Plone site). We modified the rules file to merge the Trac links into the theme, along with the search form.


$ cat /etc/trac_rules.xml

<?xml version="1.0" encoding="UTF-8"?>

<rules xmlns="http://www.plone.org/deliverance" >

  <prepend theme="//head" content="//head/link" nocontent="ignore" /> 

  <prepend theme="//head" content="//head/style" nocontent="ignore" /> 

  <append theme="//head" content="//head/script" nocontent="ignore" />    

  <append theme="//head" content="//head/meta" nocontent="ignore" />

  <drop theme="//ul[@id='portal-siteactions']" />

  <append-or-replace theme="//head" content="//head/title" nocontent="ignore" />

  <replace theme="//form[@name='searchform']" content="//form[@id='search']" />

  <copy theme="//ul[@id='portal-globalnav']"

           content="//div[@id='ctxtnav']/ul/*" nocontent="ignore" />

  <copy theme="//ul[@id='portal-personaltools']"

           content="//div[@id='mainnav']/ul/*" />

  <append theme="//ul[@id='portal-personaltools']"

           content="//div[@id='metanav']/ul/*" />

  <drop theme="//div[@id='portal-breadcrumbs']" />

  <copy theme="//table[@id='portal-columns']"

      content="//div[@id='content']" />

</rules>

We then swtich the Deliverance Paste configuration to use the new rules.


$ cat /etc/paste.ini

...

[filter:deliverance]

paste.filter_app_factory = deliverance.wsgimiddleware:make_filter

theme_uri = http://secoora.org/

rule_uri = file:///%(here)s/trac_rules.xml

Now, we see the fully-themed site. Notice that:

  • The "tabs" in the Plone theme are now the "global" navigation links from the Trac application.
  • The "personal tools" in the theme now contains the "main" and "meta" nav links from Trac.
  • The search form is now the Trac version
  • the Plone "breadcrumbs" are gone.

posted at: 00:00 | permalink