We are actively using Deliverance at Zest Software to theme a default Plone site with a completely new skin. With Deliverance you run a ‘transformation’ server in front of your website like a proxy, but as an added bonus (or more as its intended purpose) you select parts of pages that the Plone site serves and insert these snippets like the content, main navigation and support menu’s into placeholders from a static html template with css and images on the file system.
Deliverance is being experimented with and put to production use by many organisations/people already . There are quite some blog posts and notes on the web, but Documentation and howto’s are still below the level of more mature (read: older) projects. The official deliverance 0.3 documentation gives a thorough overview of commands and transformation, but doesn’t present much real world usage or a full ‘howto’. This is not surprising since deliverance is so general in nature (fetch, transform/merge and deliver). Your individual documentation needs really depend on the sources from which you want to merge.
Installing with buildout
We are using buildout to develop all our Plone Sites. In the Plone Collective there’s an example buildout ‘deliverancedemo’ that sets up a Plone site and deliverance server for you.
There’s a howto in the works for this example buildout, based on excellent presentations given by Nate Aune. At the Plone Symposium 2009 sprint in Sorrento I’ve helped a bit with the tutorial and got my first live experience with Deliverance. The tutorial is still a work in progress. This blog post is mainly a collection of things I’ve run into so far, not a structured “do this, do that”.
One of deliverance’s requirements is python lxml, which in turn needs the libxml2 and libxslt libraries. Especially on Mac OS X these libraries can cause a lot of headaches, hence the z3c.recipe.staticlxml recipe to compile them static and not use the OS X system libraries.
One caveat here is that the recipe depends on zc.recipe.cmmi to compile the libraries but fails to create a ‘downloads’ directory in your main buildout. So create the downloads dir or make sure it’s in your buildouts svn repository.
Once you have the buildout running you can start the Plone site with bin/instance, and deliverance with “bin/deliverance-proxy rules.xml”
Default transforms
Deliverance does some default actions without you specifiying them in the rules.xml . This bit us while experimenting when we wanted to override which javascript/css was copied from the Plone site into the theme. You can suppress these default actions using the suppress-standard=”1″ attribute on a rule container so that you can specify your own.
Switching themes
Our deliverance project at work needs a slightly different theme for the homepage and second level pages. In the rules.xml you set the default theme to use with:
<theme href="/static/index.html" />
Between the ruleset as the default template to use for merging your content into. Rules can be specified for certain classes only.
<theme href="/static/index.html" />
<match path="regex:^/$"/>
<rule class="homepage>
<theme href="/static/homepage.html"/>
</rule>
This will use /static/index.html as the default page, but for the exact path “/” switch to static/homepage.html . Note that you can use hints like ‘regexp:’ or ‘exact:’ in any rule attribute that does string matching. Without this ‘regexp’ the path attribute in the match action would have matched any request since the default for path attributes is prefix matching.
Feeding javascript/css into the theme
Putting content from the plone site in to a static theme is rather straighforward, excitement starts when you also want to provide Plone’s editing functionality in the deliverance served site.
Plone uses quite some css and javascript for the content editing. A standard Plone site will not include ‘authoring.css’ for anonymous users but add this into the head with an @import when a user is logged in. Rules for this are set in the css_registry tool in the Plone site.
Ideally you would not want to use any css or javascript from the Plone site, but to support the editing styles you then have to select and copy everything necessary from the Plone styles in your static template. And anonymous visitors would still receive all the unnecessary authoring css.
Deliverance has some fancy CSS3 selector action that let you check on attributes in tags in the content and copy them for the theme. So could use
<prepend content="link[href *= 'authoring']" theme='children:/html/head' />
to copy a link tag with an href attribute to something with ‘authoring’ in the head section. But this will only work if you set the rendering type of the css resource in the css_registry to ‘link’. By default it is set to import, but you cannot select this @import with the help of CSS3 selectors.
Plone also cleverly merges css resources registered in the css_registry into single files with a new name including a hash, for example ‘authoring-cachekey0936.css’. This file then contains the authoring.css and every css below this file in the registry if it has marked as mergeable and the same rendering type. If you want to include ONLY authoring.css with Deliverance you will also have to turn off ‘merging’.
To make this easier we have still created a Plone theme for the site, even though Deliverance is sitting in front doing the main themeing. The plone theme doesn’t do much theming, but settings like these are easy to configure on the filesystem using Generic Setup in your theme’s profiles/default/cssregistry.xml
Where’s the code?
Once we’re done with the initial version of project we are working on now, the buildout and theme will be released on the Plone collective to serve as another example. The more examples, the merrier.
Other resources:
As stated there are a lot of individual blog posts online, and the official documentation site obviously to begin with. Two gems I found:
Macadames Blog : Tips on {SERVER_NAME} in your rules, apache virtualhost config and integration with PyQuery.
Ian Bickings’ PloneConf 2008 Deliverance presentation notes. These are buried in an svn sandbox but provide some very cool real world use cases with solutions and rule examples.
