A few months ago at the Plone West Coast Sprint we started to work on a few new themes for Plone using XDV and came upon a road block:  How do you replace attributes within elements in XDV?

We wanted to replace the href tag in the logo of our theme:

<div id="logo">
  <a href="#">
     <img src="logo.png" alt="" title="Plone Theme" height="57" width="252" /></a>
</div>

with the href tag Plone dynamically generates in “portal-logo”:

<a id="portal-logo" accesskey="1" href="http://yourplonesite.com">
  <img src="http://yourplonesite.com/logo.jpg"
       alt="" title="Plone" height="57" width="252" /></a>

Should be pretty simple, right?  Just use the <replace> rule in our rules.xml file and specify the href attribute as follows:

<replace content="//*[@id="portal-logo"]/@href" theme="//*[@id="logo"]/a"/>

WRONG. For some reason, you need to use the <prepend> rule:

<prepend content="//*[@id="portal-logo"]/@href" theme="//*[@id="logo"]/a"/>

Normally, <prepend> copies specified elements from Plone as the very first child of an element in the theme. What we found is that this is apparently only true with elements. For some reason, when the selecting attributes, XDV alters the behavior of <prepend> and it acts like <replace>.

Here’s what the output of the theme should look like with the correct XDV rule applied:

<div id="logo">
  <a href="http://yourplonesite.com">
  <img src="logo.png" alt="" title="Plone Theme" height="57" width="252" /></a>
</div>

Creating a Plone 3 theme product on the file system can be notoriously daunting for beginners. A lot of documentation exists, but it is somewhat fragmented and can be confusing. I’ve been designing and skinning themes for Plone for quite sometime now and thought it would be nice to have a quick guide on how to create Plone 3 theme products on the file system.

There are essentially 3 things that you need to do which involve:

1. Moving viewlets
2. Modifying viewlets
3. Adding theme files

To start, you should first create your theme through the web in the ZMI and place all of the files in the /custom folder. Once your design is finalized, you can then move everything into your product on the file system. I like to use FSDump to dump files from the ZMI into the file system.

Through the web

1. Moving viewlets

Plone’s default layout is composed of viewlets such as the globalnav (top navigation) that are controlled by viewlet managers. These viewlets can be re-arranged by re-ordering the viewlets through the web by appending @@manage-viewlets to the end of your site URL: http://[your_plone_site]/@@manage-viewlets.

For a quick reference on what each viewlet is, check out Where is What in Plone 3.

2. Modifying viewlets

To modify the templates for each viewlet, you’ll need to go into the ZMI to /portal_view_customizations.

3. Adding theme files

Files such as images and CSS should be placed in the /custom folder within the ZMI

The file system

Once your design is finalized, you need to transfer all of the files and layout changes from the web to the file system to create a Plone 3 theme product.

You should use Paster to generate the initial framework and files for your Plone 3 theme product on the file system. For more information on how to use Paster, check out How to Create a Plone 3 Theme Product on the Filesystem.

1. Moving viewlets

Re-ordering viewlets through the web is quite easy using the @@manage-viewlets option. However, when creating a product on the file system, you’ll need to re-order these by calling specific rules within profiles/default/viewlets.xml, which is created by Paster.

Let’s say you moved the personal_bar to the top of the layout. You need to locate the viewlet manager that contains the viewlet using @@manage-viewlets.

By default, plone.personal_bar is managed by the plone.portaltop viewlet manager. A rule needs to be applied that re-orders the plone.personal_bar viewlet within the plone.portaltop viewlet manager.

Here is the rule within viewlets.xml:

...

 <order manager="plone.portaltop" skinname="[YOUR_PLONE_THEME]"
     based-on="Plone Default">
     <viewlet name="plone.personal_bar" insert-before="*"/>
 </order>

...

This rule says to place plone.personal_bar before all other viewlets that are managed by the plone.portaltop viewlet manager.

For more detailed information on moving viewlets, check out Move Viewlets Between Viewlet Managers.

2. Modifying viewlets

Any viewlets that you customized in /portal_view_customizations through the ZMI goes into the browser/ folder of your theme that was created by Paster.

Let’s say you customized the footer and global_sections. You’ll need to add the footer.pt and sections.pt templates in the browser/ folder and then reference them in browser/configure.zcml:

...

<browser:viewlet
    name="plone.footer"
    for="*"
    manager="plone.app.layout.viewlets.interfaces.IPortalFooter"
    layer=".interfaces.IThemeSpecific"
    template="footer.pt"
    permission="zope.Public"
/>

<browser:viewlet
    name="plone.global_sections"
    for="*"
    manager="plone.app.layout.viewlets.interfaces.IPortalHeader"
    class=”plone.app.layout.viewlets.common.GlobalSectionsViewlet”
    layer=".interfaces.IThemeSpecific"
    template="sections.pt"
    permission="zope2.View"
/>

...

One important thing to note is the class=”plone.app.layout.viewlets.common.GlobalSectionsViewlet” attribute in global_sections.

global_sections creates content dynamically and therefore references a special class. If you forget to include it, you’ll get an error. The footer on the other hand is only static text by default, so it doesn’t need the class attribute.

The manager=” “ attribute can also be found in @@manage-viewlets.

3. Adding theme files

You’ll need to place your theme files such as images and CSS in the skins/ folder, which is broken up into three sections:

skins/plonetheme_[your_product_name]_custom_images
skins/plonetheme_[your_product_name]_custom_templates
skins/plonetheme_[your_product_name]_styles

Any custom CSS files also need to be be registered within portal_css. To do this, you’ll need to reference them in profiles/default/cssregistry.xml. Paster should have created them for you.

Note, you have two options for your image and CSS files. You can either place them in the skins/ folder or in the browser/ folder. However, if you’ll be using any custom DTML calls in your CSS such as &dtml-portal_url; to generate your URL dynamically, you’ll need to keep them in the skins/ folder. Only static CSS files can go into the browser/ folder.

As best practice, you should also create an uninstall profile. If you don’t, when your theme is uninstalled it may not reset your Plone site back to its default layout.

Now that you have your product, install it!