Activating xdv

by Alexander Limi — last modified Feb 20, 2010 04:16 PM
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.