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.