Quick Start

An introduction to rules based theming with collective.xdv

1. Activating xdv

We have added xdv to our setup, it’s time to activate it in our Plone site.

Make sure Plone was (re)started, and log in as an administrator. Go to Site Setup, and make sure it contains a new control panel called "Theme Transform". If you can't see it, double check that the setup instructions were followed, and that you got no errors in the previous setup procedure.

The Theme Transform control panel has a number of settings which we'll make use of in a minute â but first we will create a simple HTML file and some transform rules to get us started.

Adding the HTML and rule files

Let's create a dedicated directory in your instance where you can keep your theme files:

Navigate to your buildout's instance directory
Create a directory called "themes"

Note: Never put anything in the parts, eggs or develop-eggs directories, as Buildout considers these private, and may potentially wipe them when updating your setup.

Inside the themes/ directory, create the following two files using your text editor:

theme.html:

<html>
<head>
  <title>xdv example</title>
</head>
<body>

  <h1>The simplest possible example of xdv transforms</h1>
  <p id="my-content-area">This body text will be replaced.</p>

</body>
</html>

rules.xml:

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

    <!-- Copy over the contents of the page body -->
    <replace content='//*[@id="content"]'    
               theme='//*[@id="my-content-area"]' />

</rules>

Believe it or not, that's a complete â although very basic â Plone theme using xdv!

We now have an HTML file which forms the base of our design, as well as a rules file that does the transform. All we have left to do is tell Plone about the the paths for the theme and rule files, and enable the transform.

Enabling the theme transform

Let's go back to the "Theme Transform" Plone control panel:

The settings you need to care about right now are:

Enabled: Turns the xdv theme transformation on or off. Select "yes".
Domains: Which domains get the theme transforms applied. One thing to note here is that 127.0.0.1 will never have a theme applied as a safety net, so you can always get back to your site even if an error while developing your theme transform makes it unusable. There is a default value of "localhost:8080" here, adjust if your setup is different â but usually the default value is fine.

The next two values are where it gets interesting:

Theme template: A file path pointing to the theme file. This is just a static HTML file. Add themes/theme.html here. It's relative to your instance directory, no need for the full path.
Rules file: The filesystem path to the rules XML file. Add theme/rules.xml here.

Ignore the rest of the form values for now, and press Save.

Testing that everything works

Now, let's go to the front page of your Plone site and see what happened:

Go to http://localhost:8080/Plone
Admire your beautiful, unstyled HTML page with the content from Plone inserted into it, it should look something like this:

Not particularly visually exciting, is it? But what you have just set up is a very, very powerful way to theme Plone sites, that makes it possible to use any pre-existing design with a Plone back-end. The reason this is exciting is that you're using your own HTML and CSS, not modifying Plone's HTML and CSS.

Let's take a step back and explain how it all fits together.

2. How it works

A high-level overview of what is going on in xdv (and Deliverance).

The way xdv works is simple, but since it might take a little adjustment of the mental model you're used to if you have done theming in Plone (or any other system), it's worth an explanation:

The main difference is that you're not touching the templates and HTML from Plone itself at all. Instead, you create the layout and design you want in standalone HTML and CSS files â and then map parts of the content that comes out of Plone into your existing HTML.

This means that you can create as complex (or simple!) designs as you want, and let Plone supply the content.

This also means that you can write your own from-scratch HTML and CSS, but also map various Plone elements to wherever you want in your own design. Plone knows nothing about what happens "on the way out", it just renders a page as it usually does.

A more visual way to look at it, here you can see how the Plone output is mapped into a totally different template and design:

This makes for a much more robust approach to theming, because as long as Plone keeps its HTML classes and IDs the same from one version to the next, your theme will automatically work even in a new version of Plone. And if it has changed, it's a relatively simple operation to update the theme â just locate the new name, and replace it in the rule file.

Let's take a closer look at the rule file.

3. The rule file

Central to the way content makes its way from your Plone site into your theme is the rule file.

Let's look at your simple rule file again:

rules.xml:

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

    <!-- Copy over the contents of the page body -->
    <replace content='//*[@id="content"]'    
               theme='//*[@id="my-content-area"]' />

</rules>

Ignoring the preamble <rules> and the comment, there's one single instruction here:

<replace content='//*[@id="content"]'    
           theme='//*[@id="my-content-area"]' />

So what does it do?

It looks at the Plone side of things ("content"), and locates the part of the HTML that has id="content".
It then replaces the part of your theme's HTML that has id="my-content-area" with the content it got from Plone.

The syntax (inside the content and theme attributes) can be a bit intimidating â luckily we have great tools to make it very easy to get this right. The syntax is called XPath, and is a standard for addressing nodes in the DOM, and it's also directly supported in Firebug. A full treatment of how Firebug works is out of scope for this tutorial, but if you have done any web design in the past, you have probably used it. If not, head over to the Firebug web site to learn more â they have documentation and screencasts showing you how to use it.

I will show you a screenshot of the part we're interested in, however â when you're looking at the Plone source code using Firebug, locate the content area as shown below, and right-click the node:

As you can see, there's a way to copy any HTML node, and get its XPath expression. When you paste what's now on your clipboard, you will see:

//*[@id="content"]

â¦and that's the XPath expression that uniquely identifies that part of the page! You probably recognize this from our original rules.xml file. That's the node you're looking for in the Plone source, and you use the same approach to find the node you want to replace in your theme.html.

You don't have to teach yourself XPath â just arm yourself with Firebug, and make use of its built-in support for these expressions.

As a sidenote, Deliverance has implemented support for CSS-like syntax â that is, #content instead of //*[@id="content"] â which is certainly easier to remember. The XPath-based syntax works equally well in both xdv and Deliverance, though.

Let's go over the available rules next.