Luckily, what goes in the rule file is very simple — there are only four types of rules, and you'll get the hang of them quickly. The rules are:

• replace
• append/prepend
• copy
• drop

Let's look at what they do, and show some real-world examples of how they are used.

<replace>

Replaces an element in the theme with content from the site.

Real-world examples:

A useful thing to do is to carry over the <title> and <base> tags from Plone, so the theme will have the right page titles and work correctly when you do operations on folders:

<replace content='/html/head/title' 
           theme='/html/head/title' />

<replace content='/html/head/base' 
           theme='/html/head/base' />

The XPath expressions are actually pretty straightforward when you know exactly where the elements are. You'll get used to the most common variations after using Firebug's "Copy XPath" a few times.

Also note how the entire specified tag is replaced, nothing from the theme file remains.

Another common example is making the content of a page from Plone appear in the theme:

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

<append> & <prepend>

Adds the content from the site to the theme, either before or after the specified element.

Real-world examples:

Adding the Plone-created CSS and JS in addition to the ones already in the theme:

<append content='/html/head/style' 
          theme='/html/head' />

<append content='/html/head/script' 
          theme='/html/head' />

Notice how we take the all the <script> and <style> tags from Plone, and append them after the current content of the head tag in the theme. This way, you can let Plone manage some of your CSS and JS if you want — useful for conditional includes.

Another examples is carrying over the id and class attributes on the body tag, since these are useful for styling on a per-page basis — and the visual editor uses them too:

<prepend content="/html/body/@class"
           theme="/html/body" />

<prepend content="/html/body/@id"
           theme="/html/body"  />

A final example that illustrates the <append> usage; imagine that we only have one sidebar, but have two columns in the Plone site that we both want to appear inside the sidebar:

<append content='//*[@id="portal-column-one"]/div'
          theme='//*[@id="sidebar"]' />

<append content='//*[@id="portal-column-two"]/div'
          theme='//*[@id="sidebar"]' />

This way, the second rule doesn't overwrite the first — it appends the second column, so both appear inside the id="sidebar" node.

<copy>

Copies HTML nodes from the Plone side of things and inserts it inside a tag on the theme side:

<copy content='//*[@id="portal-globalnav"]/li' 
        theme='//*[@id="main-nav"]' />

Notice how this one gets every <li> element inside the node with id="portal-globalnav" in Plone, and makes a copy inside the node that has id="main-nav" in the theme.

<drop>

Removes the specified element if it exists. This one is a bit different than the others, since it only has a content= value — since it only makes sense to drop an element from the Plone side.

Real-world example:

Getting rid of the icon inside the "user-name" node:

<drop content='//*[@id="user-name"]/img' />

Since there is no ID directly on this image, we just drop any <img> inside the "user-name" ID.

That's actually everything you need to know, now the next steps are up to you!