Updating a Traditional Plone Theme to Diazo for Plone 5

If you have a traditional-style Plone theme that will continue to be in use for Plone 5 and beyond, I recommend updating it to use Diazo. This involves a few steps:

Add a folder for your static content
Move all custom CSS, JS, and images into the static folder
Use Plone Default as the base theme
Write an index.html and rules.xml
Remove all skins overrides
Reduce number of z3c.jbot overrides
Move custom skins templates into view templates

A nice thing about these steps is that they don't all need to be done at the same time. They can be done gradually if you are short on time.

Add a folder for your static content

This folder is basically a browser resource, which plone.app.theming converts into a theme.

<plone:static 
    directory="static"
    type="theme"
    name="mytheme" />

Include a manifest.cfg in the directory for information about the theme that will display in the Theming control panel.

Move all custom CSS, JS, and images into the static folder

Move any CSS, JS, and images from your skins folders into the new static folder. They can be put into subdirectories to keep the file structure clean. The CSS and JS files can (and should) remain in the resource registries, the entries will need to be updated to include the new path, for example: ++theme++mytheme/main.css. If doing this from cssregistry.xml, remove the entries with the old path using remove=“true”. Paths to images from the CSS will need to be updated as well, and these can use relative paths as long as the applyPrefix is set to True in the CSS registry.

Use Plone Default as the base theme

Chances are, your theme is currently based on Sunburst. This should continue to work in Plone 5 initially, but eventually portal_skins will be removed completely (currently it is deprecated). By switching to Plone Default as the base, you can copy all styles from Sunburst and add them to your static folder. Entries in the CSS Registry will need to be updated by removing the files you copied, and re-adding them with the static path.

Write an index.html and rules.xml

These files will live directly inside the static folder. If you want to keep your theme looking the same, you can go to your site, View Source, copy all the code and put it in your index.html. Strip out any extra bits you don’t need. Then write your rules to map the dynamic content from Plone to this static html.

Remove all skins overrides, and reduce number of z3c.jbot overrides

portal_skins is being deprecated, and many of the skins templates are being moved into views, which means your customizations will no longer work in Plone 5. Now that you have a Diazo theme in place, see if your customizations can instead be done with a Diazo rule, so that you can remove the override completely. If you need to keep the override, use z3c.jbot instead of skins. When you upgrade to Plone 5, you will just need to change the name of the override to point to the original file’s new location. Try to do as much as you can with Diazo, to keep the number of overrides at a minimum. This will make upgrading easier.

Move custom skins templates into view templates

Let’s say you have a custom template for your homepage in skins. Move that template to the browser folder in your theme, and put this in the configure.zcml:

<browser:page
    for="*"
    name="homepage"
    template="homepageview.pt"
    permission="zope2.View" />

The template will now be accessible in the site at /@@homepage (path is based on the name you set). You will need to remove or update any code that assigns the template to the page. You can just specify the template as the href in a Diazo rule:

<replace
    css:theme="#content"
    css:content="#home"
    href="/@@homepage"/>

There will still need to be adjustments once you upgrade to Plone 5. The steps in this outline are just my recommendations from my theming experience and investigation into Plone 5. I would love to get some opinions and suggestions from developers that have been actively working on Plone 5.

Blog