Why a new approach?

The current approach to theming (also known as "skinning") Plone sites (Plone 1.0 to 3.x) has been steadily evolving over a number of years, and is powerful, but somewhat complex. 

As with most software, the reason for this complexity is a side effect of the evolution of the product over time — adding more functionality and more flexibility to meet the needs of power users, while still retaining the same initial approach to the problem space.

For Plone, the current theming approach has served us well for the last 8 years, but we realized it was time to re-evaluate how theming was done, since it's such an integral part of setting up a Plone site.

The main goals for a new approach were:

• No requirement for the people doing the theming to know anything about Plone or Python.
• Use standard tools and libraries whenever they are available.
• Reduce the number of concepts you have to learn in order to get started.
• When requiring you to learn something new, let it be a standard solution that is useful even outside of the Plone world.
• Try to stay as close to the HTML and CSS mindset as possible, as the people doing theming are usually the same people that do the HTML code for the design.
• Make it possible to apply an existing HTML/CSS design to a Plone site while keeping the original markup instead of having to re-do the design in a way that makes Plone happy.
• Let the theme work standalone, without introducing any additional markup. It should look like a standard HTML page with CSS, JS and images.
  

About the future of theming in Plone

For the upcoming versions of Plone, we are 99% sure that we'll use a variant of what is described here. It will probably change slightly in how it integrates into the product, and what knobs are available to deploy a theme in a standard way — but the fundamental approach will be the same.

What we are offering you with the collective.xdv package is a way to make use of the likely future standard of theming, today. We'll keep this document updated as Plone progresses with newer versions, and if you're reading this documentation in a book or another printed version, always check http://plone.org/theming to view the latest version of this document. There will be a revision history attached, which will detail the latest changes to this document.

Is xdv ready for serious deployments?

Currently, the plone.org web site itself is using xdv for its theme — so it's battle-tested and ready for serious, high-traffic sites.

When people talk about this new approach to theming, they will often refer to the general approach as "Deliverance-based". The original Deliverance project was started by Paul Everitt a long time ago, and was further enhanced by Ian Bicking, who is its current maintainer.

Along the way, Deliverance got more powerful and expanded beyond the initial goals, and started handling cases that were not included in the original scope.

Long story short, a new implementation of the same basic approach was started, called "xdv". This is a stripped-down, pure XSLT implementation of the Deliverance concept, and can be compiled down and used directly inside a web server like Apache, IIS or nginx (pronounced "Engine X") as a standard XSLT transform, without any extra software running.

This does not mean that xdv is somehow better than the original Deliverance implementation, or that it makes it obsolete — they are different tools with slightly different goals, sharing the same basic approach. We'll get to an overview of which approach is appropriate for what cases in a moment.

The final piece of this puzzle is the add-on called collective.xdv, which takes xdv and packages it up to make it very convenient for use with Plone.

As a side note, the "collective" namespace is a common pattern in Plone add-ons, and denotes software that is managed collectively by the Plone community — and not necessarily by the Plone Foundation.

Why do you need to know all this? It's useful to keep in mind that you can carry across what you learn in using collective.xdv to the Deliverance project, should you need to do that at a later point. The basic syntax and approach is largely the same, although the details of the implementation can differ slightly.

At the moment, there are several ways to theme a Plone site. What are your options, and which is appropriate for a given case?

Comparison of the available approaches

Product package

Pros:

• The ultimate in flexibility and control
• More flexibility when it comes to theming select parts of a site or sub-sites
  

Cons:

• More complex, requires a passing familiarity wtih ZCML and Python
• Less upgrade-resistant, since templates change
• Shipping your own templates will get you out of sync with the main product
  

collective.xdv

Pros:

• Can be compiled down to XSLT transforms that run as part of the web server process, so you don't need a separate proxy or WSGI setup. This also means a slight performance advantage over Deliverance.
• Easy to bootstrap with Plone.

Cons:

• Uses XPath selectors instead of the more familiar CSS selectors (not as big a deal as you may fear, since we can use a plug-in called Firebug to make it create the XPath expressions for us, as we'll see later).

Deliverance

Pros compared to xdv:

• Standalone, can be used without Plone to theme other sites and systems, has a good WSGI story.
  
• Supports a more familiar CSS syntax in addition to XPath.
  

Cons compared to xdv:

• Less integrated with Plone, requires you to understand more of the ecosystem and setup.
• Uses its own non-standard (but CSS-like) syntax, can't be deployed inside a web server process.

Which one should I use?

A general rule-of-thumb to help you decide what approach to choose:

Use the add-on/product approach when…

You need extreme granularity of control, and are willing to learn some Python and ZCML to get what you want.

Use xdv when…

You'd like to keep the theme separate from the code, and want a reusable theme approach that can potentially be deployed as part of the web server process. You don't want to worry about most of the "plumbing", and are comfortable using best practices from the Plone community.

Use Deliverance when…

You have advanced theming needs, including the ability to apply the same theme to multiple frameworks/web apps in addition to Plone, and are willing to set up a proxy or WSGI pipeline to make it happen.

Of course, reality is always a bit more complicated — you can apply an xdv-based theme to non-Plone setups too, if you know what you're doing.

The important part to know is that you can move between xdv and Deliverance pretty easily, so starting out with collective.xdv is likely to be a great start, even if you end up using Deliverance later.

Before we get started, make sure you have the following software available:

• The latest version of Plone (Plone 3.3 or newer for the best experience)
  
• Latest version of Firefox (available for all platforms)
  
• The Firebug add-on for Firefox
• Your text editor of choice
• Access to the Terminal or command line on the system you are working on
• A network connection (to make sure Buildout can download its packages) — you can work around this by downloading the packages separately if you don't have a network connection, but it's outside of the scope of this tutorial. Consult the Buildout documentation if you need to do offline packages.

And again: if you're reading this in printed form, make sure you check the online version at http://plone.org/theming for the latest version recommendations, as versions and Buildout dependency URLs may change slightly over time.

Got everything set up? Great, let's get down to business.