[Repoze-checkins] r605 - www/trunk/blog.repoze.org/entries

[Tres Seaver]

Author: Tres Seaver <tseaver at palladion.com>
Date: Thu Dec  6 15:58:47 2007
New Revision: 605

Log:
Blog post on theming Trac with Deliverance.

Added:
   www/trunk/blog.repoze.org/entries/theming_trac_with_deliverance.txt   (contents, props changed)

Added: www/trunk/blog.repoze.org/entries/theming_trac_with_deliverance.txt
==============================================================================
--- (empty file)
+++ www/trunk/blog.repoze.org/entries/theming_trac_with_deliverance.txt	Thu Dec  6 15:58:47 2007
@@ -0,0 +1,156 @@
+Theming Trac with Deliverance
+#label general
+<p>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.</p>
+
+<p><img align="right" src="http://static.repoze.org/secorra-theme.png" />
+   Chris works for <a href="http://secoora.org/">SECOORA</a>, a regional
+   marine science collaboration, and needed a way to share branding
+   for the <a href="http://trac.edgewall.org">Trac</a> instances he
+   maintains for the various SECOORA software projects.</p>
+
+<h3>Installing Trac as a WSGI app</h3>
+
+<p>We first worked out how to make Trac installable under Paste.  Chris
+   figured out how to get Trac installed via <code>repoze.project</code>:</p>
+
+<pre>
+$ bin/repozeproject --path=/tmp/trac repoze.trac
+</pre>
+
+<h3>Paste configuration</h3>
+
+<p>The standard Paste configuration that <code>repoze.trac</code> sets up
+   looks like so:</p>
+
+<pre>
+$ cat etc/paste.ini
+[app:trac]
+paste.app_factory = repoze.trac:make_trac
+path = %(here)s/../var
+
+[pipeline:main]
+pipeline = egg:Paste#cgitb
+           demo
+</pre>
+
+<h3>Setting up the Trac Instance</h3>
+
+<p>Before starting the server, we need to initialize the Trac
+   instance:</p>
+
+<pre>
+$ bin/trac-admin var initenv
+...
+</pre>
+
+<p>And edit the Paste config to point at the new location:</p>
+
+<pre>
+$ vim etc/paste.ini
+...
+$ cat etc/paste.ini
+...
+[app:trac]
+paste.app_factory = repoze.trac:make_trac
+path = %(here)s/../var
+...
+</pre>
+
+<h3>Running Trac under Paste</h3>
+
+<p>Now we can start the server:</p>
+
+<pre>
+$ bin/paster serve etc/paste.ini
+</pre>
+
+<p>And view the Trac homepage.
+   <img align="right" src="http://static.repoze.org/trac-unthemed.png" /></p>
+
+<h3>Adding Deliverance to the Mix</h3>
+
+<p>First, install Deliverance:</p>
+
+<pre>
+$ bin/easy_install Deliverance
+...
+</pre>
+
+<p>Then add a minimal rules file defining how Deliverance will
+   merge the application into the theme:
+</p>
+
+<pre>
+$ 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>
+</pre>
+
+<p>And configure Deliverance into the pipeline, using those rules:</p>
+
+<pre>
+$ 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
+</pre>
+
+<p>View the themed site:
+   <img align="right" src="http://static.repoze.org/trac-minimal.png" /></p>
+
+<h3>Making Trac's Nav Fit into the Theme</h3>
+
+<p>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. </p>
+
+<pre>
+$ 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>
+
+$ 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
+</pre>
+
+<p>Now, we see the fully-themed site:
+   <img align="right" src="http://static.repoze.org/trac-themed.png" /></p>
+