Prerequisites

If you are not familiar with XDV or Deliverance please consider reading the wonderful introduction to these technologies by Alexander Limi. If you are going to use XDV to style more than just Plone then this tutorial will of course give you the basics. Though after reading it you might need to read Chapter 12 in Alexander's tutorial, written by Anne Bowtell in more detail.

This tutorial will guide you through applying a static HTML/CSS theme to your Plone (and only Plone) site using collective.xdv.

Static theme

For the practical part I assume you have a static theme done. This means you have created/bought/downloaded a set of static HTML, CSS etc. files that have no relation to Zope/Plone at the moment. You should be able to test your visual theme in a browser without Plone or Zope running.

In this tutorial we use xdvtheme.xdvrocks package as a case study to see the real implementation. You might want to download it and check its static/ folder to get the static theme that we are going to convert to a real Plone theme.

Buildout

As with any Plone project, no matter whether it uses XDV/Deliverance or not, we start with buildout. We will not dive into the details of creating one in this tutorial and assume you have a buildout-driven set up with a Plone site running. There is a wonderful tutorial by Martin Aspeli on taming buildout.

After the buildout is set up you want to add collective.xdv and it’s dependencies to the mix right away. In order to do this add:

[buildout]
…
extends =
    …
    http://good-py.appspot.com/release/collective.xdv/1.0    
…    
eggs =
    …
    collective.xdv [Zope2.10]

You might want to use 'extends-cache' option in your [buildout] section to make all resources from 'extends=' download to the local folder for further offline usage

If you are trying to install collective.xdv for Plone 4 (Zope 2.12), you can drop the [Zope2.10] part. If you are still on a lower version of Plone with Zope > 2.12 this will make sure you have additional functionality ported from Zope 2.12 that collective.xdv requires.

This should be enough if you’re not on Mac OS. This OS has issues with the lxml binary egg that make installation of collective.xdv on OS X quite problematic. So, if you’re on Mac OS your buildout.cfg should be extended with more information, in addition to the above, like:

[buildout]
…	
parts =
    lxml
    …
…    
[versions]
lxml = 2.2.2
zc.buildout =
…
[lxml]
recipe = z3c.recipe.staticlxml
egg = lxml

zc.buildout = might be necessary on Mac OS because building staticlxml on Mac OS most probably will require a version of zc.buildout newer than the one you get when creating a buildout. This line says that we need the most recent version of zc.buildout.

After re-running ./bin/buildout for your instance and starting it, you should be able to add a Plone site in ZMI with an “XDV Transforms” profile. Doing this will install the “Configuration registry” profile as well to your site. This tells us that collective.xdv is installed and is available for Plone.

At this stage you might also want to add your favorite development tools to the buildout. I always add omelette and plone.reload. You might want to add other tools you like.

Theme package

Any web application needs to know where your static files are. XDV is not an exception. In pure XDV you can tell your web server to fetch your files. In the case of collective.xdv, when you don’t use such server, a standard Plone theme is still the best way of letting a Plone site know that there are files in your theme. Yes, magic doesn’t really happen here - you still need to create at least a basic Plone theme package in order to make your images, stylesheets etc. available for your site. Moreover you really want to register your stylesheets and javascripts with portal_css and portal_javascripts respectively to use all the advantages of these like caching, merging and so on.

There is only one case so far when you can avoid creating a Plone theme using collective.xdv - when all you have is HTML. No images, no stylesheets. But we don’t any longer live in times of pure HTML without styles and images. So you can’t avoid registering your resources.

Generation of an actual theme package is beyond the scope of this tutorial as well. As already mentioned, for this talk’s purpose we will use a ready-generated theme called ‘xdvtheme.xdvrocks’. So, we assume you have managed to either read “Plone 3 Theming” book by Veda Williams or read her “How to Create a Plone 3 Theme Product on the Filesystem” tutorial on plone.org and you have an installable theme package in your buildout.

Our example theme's structure

At this point we have 3 main parts to work with:

• static visual theme;
• Plone theme package;
• buildout with both collective.xdv and your theme installed.