This page contains info for using Deliverance theming proxy with Plone.

What is Deliverance

Deliverance moves items from your Plone site into placeholders in your theme, without touching the Plone site or the theme.

Deliverance is a universal tool to theme HTML, applying a consistent style to applications and static files regardless of how they are implemented and with what technology.

Deliverance extracts pieces of content from your Plone site generated output and puts those into named placeholders in the theme's resulting template.

This is accomplished without touching the Plone site or the theme that is used within the Plone itself.

Some of the benefits:

  • A designer can create a Plone theme without any specific knowledge of Plone's specific technology
  • A single theme can apply to multiple backend web applications regardless of what platform they were developed for

Full Documentation on Deliverance

You can read all about Deliverance in more detail but it is not necessary to follow this tutorial.

Read Deliverance Documentation.

About this tutorial

This tutorial was developed based on slides from the Plone Symposium East 2009 presentation "Deliverance: Plone Theming Without the Learning Curve".

Full slides are available.

Installation & Setup

In order to follow the steps in this tutorial you must setup and install Plone and Deliverance. This is easily done by using the tutorial buildout.

A python2.4 runtime is required in order to follow this tutorial. In order to follow the steps described in this tutorial checkout the pre build buildout file from

svn co tutorial

Enter the directory and run the buildout process:

cd tutorial

If you have problems with the buildout, in particular, compiling libxml2 on your Mac, please refer to the next section in this documentation.

Next let's run an install step that will create a Plone instance called 'Plone' that we'll use for testing:

$ ./bin/buildout install demosite

Installing lxml on Mac OSX

If you have problems with the buildout, in particular, compiling libxml2 on your Mac, please refer to this documentation.

If you get the error ImportError: Failure linking new module at startup (lxml).

This has only been witnessed on Mac OS X. It usually means that the build found some existing 'libxml2' or 'libxslt' instead of the one that's compiled by the buildout. It's unclear how this happens, but it can be resolved by manually setting the MacOS ``DYLD_LIBRARY_PATH``. For example, if your cwd is the ``buildout`` directory:

export DYLD_LIBRARY_PATH=`pwd`/parts/libxml2/lib:`pwd`/parts/libxlst/lib:$DYLD_LIBRARY_PATH

Then restart the servers.

You can also compile libxml and libxslt as part of the buildout, and then link lxml to these locally built parts. In your buildout.cfg file:

parts =

recipe = zc.recipe.cmmi
url =
extra_options = --without-python

recipe = zc.recipe.cmmi
url =
extra_options = --with-libxml-prefix=${libxml2:location}


recipe = zc.recipe.egg:custom
egg = lxml
include-dirs = ${libxml2:location}/include/libxml2
library-dirs = ${libxml2:location}/lib
rpath = ${libxml2:location}/lib
environment = lxml-environment

Starting Deliverance

The buildout has created Plone and Deliverance instances. To view the demo and follow the tutorial we need to start both.

To start plone after the successful buildout:

$> ./bin/instance start

View your Plone site at http://localhost:8080/Plone


Now that your Plone site is up and running, you can start the deliverance proxy server:

$> ./bin/deliverance-proxy rules.xml

Deliverance will be available on port 5000.

Check out the new visual appearance of your Plone site on: http://localhost:5000


As you can see the theme looks completely different from the Plone site. For every request you make to the Deliverance proxy, Deliverance requests the pages from the Plone site and inserts parts of the Plone page into the defined them, all based on the directions in the rules.xml.

If you want to follow along with the tutorial, then restart delivance like so:

$> ./bin/deliverance-proxy rules-tutorial.xml

Static theme

The theme used in this example is taken from the Open Source Web Design site ( )

We have modified it slightly to have explicit CSS identifiers for the main content text area, rather than a generic paragraph. While this was not necessary, it was preferable for the purposes of keeping this tutorial straightforward.

The theme files are located in static directory.

Simple start script


# Run in /srv/plone/yourbuildoutfolder as plone user
# Deliverance will run in port 9000
# 1. Login admin/x
# 2. Get debug output

# Deliverance Python files are added to PYTHONPATH
# and they are maintained under SVN version control
export PYTHONPATH=src/plonetheme.yoursite/deliverance
# Start virtualenv tuned for deliverance
source deliverance-install/py25/bin/activate
deliverance-proxy src/plonetheme.yoursite/deliverance/etc/deliverance.xml

Buildout restart snippet

For see above.


# Restart script
sudo -H -u yourdeliveranceuser kill `cat path/to/deliverance/var/`
sudo -H -u yourdeliveranceuser nohup bash &


Deliverance stores it's configuration in a .xml file. This file has to be parsed to the deliverance process - in the introduction it was passed as the first argument as rules.xml.

The rules.xml file consists of different sections:

  • server settings
  • proxy definition
  • the rules

Server settings

The server-settings section is used to define connection relevant settings like the IP address and the port used by deliverance.

  <dev-user username="guest" password="guest" />

Proxy definition

The proxy definition defines where deliverance retrieves it's content

<proxy path="/" class="plone">
  <dest href="http://localhost:8080/VirtualHostBase/http/localhost:5000/Plone/VirtualHostRoot/" />

(note: maybe small explanation about the class, it maps the rules to the path?)


Deliverance uses a rules file to govern the merging. We use CSS selectors to identify elements to act on.

Rules are verbs of common actions

  • <drop> - Removes elements from the theme or the content.
  • <replace> - Replaces something in the theme with elements from the content.
  • <prepend> - Prepends content to an element in the theme.
  • <append> - Appends content to an element in the theme.

Rules tell Deliverance how to map the content into the theme.

<rule class="plone">
  <theme href="/static/index.html" />
  <replace content='/html/head/title' theme='/html/head/title' />

In this tutorial we will add several rules to integrate our sample theme with Plone.

Logo & Navigation Tabs

Style the Logo and Navigation parts.

Page Contents

Let's incorporate the Page heading, description and body text into the result.

Replacing the Page Heading

Find the element in the Plone site's HTML output that represents the page heading, and use the children: keyword with it, so it is: children:#parent-fieldname-title

We use the Deliverance children selection type which applies only to the children of the element selected, since we just want the text of the heading (we do not want the selector itself).

Screenshot related to children:#parent-fieldname-title in the Plone's HTML:


Now we need to find the corresponding element in the theme: children:div#leftbar h1 This is the *"hello!"* heading in the theme which we want to replace with the actual page heading.

Screenshot related to children:div#leftbar h1 in the Theme's HTML:


The rule we must use to replace the placeholder page heading with the page heading coming from Plone is:

<replace content="children:#parent-fieldname-title" theme="children:div#leftbar h1" />

Screenshot related to the result of the above rule:


Copy the Plone description field

Put the document description in the first paragraph of the page text.

This is the *"Your source for all things wireless"* string. The element in the Plone site that represents the description is:#parent-fieldname-description

Screenshot reference for the above:


Screenshot reference for the Theme below:


Please note there was originally no #description in the theme. We have modified it to make it simpler so no XPath references are needed in this tutorial.

In this case we want to replace the contents of the theme's #description:

<replace content='children:#parent-fieldname-description' theme='children:#description' />

The "after" screenshot is below:


Replacing the body text

Find the element that represents the body text in our Plone site, it is #parent-fieldname-text, but for our rule we will use: children: #parent-fieldname-text


The corresponding placeholder in the theme is the block of text starting with *"Lorem ipsum dolor..."*: #bodytext

<replace content="children:#parent-fieldname-text" theme="#bodytext" />

Our astute reader will note that we do not use the children: selection in the theme. This is because the theme author has chosen to use a <p> tag as the #bodytext section. Because the Plone content includes <p> tags itself we choose to replace the entire tag in the theme.

The "after" screenshot is shown below - the second paragraph (below description) that starts with *"Lorem Ipsum..."*


Next Steps

This tutorial is being developed by the Plone community. Help us finish this and learn more about Deliverance and Plone at the same time.

The following more advanced topics are under development:

  • Using XPath
  • Working with non-page views
  • Enabling Login and Portlets
  • Enabling Plone's editing interface in the themed site
  • Enable theme per section