Creating, Installing and Tweaking your theme using Plone 3

(For more resources on Plone here.)

We will first inspect a few structural changes and install them, and then finally examine the various components and skin layer items that have been changed, one at a time. Where restarting Zope or rerunning your buildout would be required, this will be noted.

About the theme

This theme and its design are available for personal and professional use to anyone, and can be freely modified. You can (and should) download the files from using the following command:

svn co plonetheme.guria

Note the space between the words trunk and plonetheme.guria. This theme is intended for installation on Plone 3 web sites. The finished theme should look like the following, but we have work to do to make this happen:

Creating, Installing and Tweaking your theme using Plone 3

This theme was created by me, for use by a charity group in India, called Guria (, dedicated to ending human trafficking and prostitution. The finished site is currently in development, and is generously hosted free of charge by the talented folks at Six Feet Up ( Additionally, most of the code and lessons learned come courtesy of similar themes created by the staff at ONE/Northwest in Seattle, Washington.

The design for this theme was created with the assumption that most of the tasks would need to be present in this theme. In fact, the only task not covered here is the creation of a new viewlet manager. Creation of viewlet managers is discussed at and

Creating a theme product

I created a theme product named plonetheme.guria, using the command line syntax paster create –t plone3_theme, while we were located in the src/ directory of our buildout, as seen next:

[bash: /opt/mybuildout/src] paster create -t plone3_theme
Selected and implied templates:
ZopeSkel#basic_namespace A project with a namespace package
ZopeSkel#plone A Plone project
ZopeSkel#plone3_theme A Theme for Plone 3.0
egg: plonetheme.guria
package: plonethemeguria
project: plonetheme.guria
Enter namespace_package (Namespace package (like plonetheme))
Enter package (The package contained namespace package (like
example)) ['example']: guria
Enter skinname (The skin selection to be added to 'portal_skins'
(like 'My Theme')) ['']: Guria Theme for the Plone Theming Book
Enter skinbase (Name of the skin selection from which the new one
will be copied) ['Plone Default']:
Enter empty_styles (Override default public stylesheets with empty
ones?) [True]: False
Enter include_doc (Include in-line documentation in generated code?)
Enter zope2product (Are you creating a Zope 2 Product?) [True]:
Enter version (Version) ['0.1']:
Enter description (One-line description of the package) ['An
installable theme for Plone 3.0']:
Enter long_description (Multi-line description (in reST)) ['']:
Enter author (Author name) ['Plone Collective']: Veda Williams
Enter author_email (Author email) ['product-developers@lists.']:
Enter keywords (Space-separated keywords/tags) ['web zope plone
Enter url (URL of homepage) ['']:
Enter license_name (License name) ['GPL']:
Enter zip_safe (True/False: if the package can be distributed as a
.zip file) [False]:
Creating template basic_namespace
Creating directory ./plonetheme.guria

You may wish to generate a new Plone theme product yourself, so that you can compare and contrast the differences between the Guria theme and a vanilla Plone theme.

Notice that the full name of the theme is plonetheme.guria, and where an item shows as blank, it defaults to the example value in that step. In other words, the namespace package defaults to plonetheme, because there was no reason to change it. The skinname is set to a single lowercase word out of stylistic preference. It's important to also note that you should not use hyphens or spaces in your theme names, as they will not be recognized by your buildout.

We've chosen not to override Plone's default stylesheets, and instead, we want to build on top of Plone's default (and excellent!) stylesheets. I prefer this method mostly because the layout needed for Plone's Contents view and other complex structural pieces are already taken care of by Plone's base stylesheets. It's easier than trying to rebuild those from scratch every time, but this is merely a personal preference.

Following the creation of the theme, we register the theme product in our buildout.cfg, using the following syntax

develop =
eggs =
zcml =

If we were using the eggtractor egg, there would be no need to add these lines of code to our buildout.cfg; all we would need to do is rebuild our buildout and it would automatically recognize the new egg. eggtractor can be found at, and is documented thoroughly.

Assuming we are not using eggtractor, we must rebuild our buildout, as we have altered ZCML code and added a new egg:

[bash: /opt/mybuildout/src/] ./bin/buildout

This would be a good time to check your vanilla theme product into Subversion, so that you can track back to the original version, if needed. However, since this is an existing theme, there is no need to do so.

For the purposes of following along, it might be best if you do not yet install the theme. We want to make some changes first. However, we will point out some caveats along the way, in case you installed the theme prematurely.

Altering the theme product's structure

Several modifications have been made to the theme product's structure to shorten folder names and change the default behavior. Again, this is mostly a personal preference. Let's take a look at these changes and how they were achieved.

Renaming the theme

In our theme product, you will see a file named profiles.zcml, located at mybuildout/src/plonetheme.guria/plonetheme/guria/profiles.zcml. The code looks like this:

title="Guria Theme for the Plone Theming Book"
description='Extension profile for the "Guria Theme for the
Plone Theming Book" Plone theme.'

If you named your theme in a way that was less descriptive, you could alter the title. Naming your theme product properly is important, because you may have different types of products used for a given web site—for example, a policy product for content that might be used in tandem with your theme product. This text is what you see in the portal_quickinstaller at http://localhost:8080/mysite/portal_quickinstaller/manage_installProductsForm, where mysite is the name of your Plone site. You can also see this name if you install your theme product via Site Setup Add-on Products|, found at http://localhost:8080/mysite/prefs_install_products_form.

If you change your XML here, and your theme product is already installed, you'll need to start (or restart) your Zope instance, using:

[bash: /opt/mybuildout] ./bin/instance fg

Shortening folder names

Next, we look at the folder structure of our theme product. The standard Plone 3 theme produces folders with names like plonetheme_guria_custom_images, plonetheme_guria_custom_templates, and plonetheme_guria_styles. While there is nothing wrong with keeping this structure, it can be cumbersome to type or tab through (especially when checking items into Subversion). However, you might want to keep the existing folder names to help you distinguish which items of base Plone you modified. This can make migrations easier. If you choose this route, you probably want to create additional folders for non-base-Plone items. I personally prefer the shorter folder names and don't worry too much about the migration issues.

In the case of this theme product, I opted to make the folder names shorter. First, I altered the names of the folders in the skins/ folder to guria_images, guria_styles, and guria_templates.

Then, in the theme, go to mybuildout/plonetheme.guria/plonetheme/guria/skins.zcml. The code in this file is altered to appear as follows:

<!-- File System Directory Views registration -->

One more step is required here. In plonetheme.guria/plonetheme/guria/profiles/default/skins.xml, the code is changed to read as follows:

<?xml version="1.0"?>
<object name="portal_skins" allow_any="False"
default_skin=" Guria Theme for the Plone Theming Book ">

<object name="guria_images"
meta_type="Filesystem Directory View"
<object name="guria_templates"
meta_type="Filesystem Directory View"
<object name="guria_styles"
meta_type="Filesystem Directory View"

<skin-path name=" Guria Theme for the Plone Theming Book " based-
on="Plone Default">
<layer name="guria_images"
<layer name="guria_templates"
<layer name="guria_styles"

Basically, the steps are the following:


  1. Rename the folders on the filesystem.
  2. Modify the skins.zcml file to change the name of the filesystem directory view (what you see in the portal_skins/properties area of the ZMI).
  3. Modify the skins.xml file in the profiles/default folder to match. This alters the basic profile of your theme product.

If you wanted to add additional folders and filesystem directory views here (a scripts/ folder, for example), you'd just add code by following the conventions given to you in these files and then create additional folders.

Making changes to the ZCML file means that you would need to do a restart of your Zope instance.

If you installed your theme product before making the changes to the skin layer names, you might want to inspect the skin layers at http://localhost:8080/mysite/ portal_skins/manage_propertiesForm, to make sure that the correct skin layers are listed. You might even need to reimport the "skins tool" step via portal_setup at http://localhost:8080/mysite/portal_setup/manage_importSteps. Make sure you choose the correct profile first by choosing your theme product's name from the drop-down list at the top of the import page. The theme product's name is the same name as you find in your profiles.zcml file.

Adjusting how stylesheets and images are used

Next, we remove some of the default behavior given to us by the plone3_theme recipe. In a vanilla theme product, folders named images/ and stylesheets/ are inserted into the plonetheme.guria/plonetheme/guria/browser/ directory. Additionally, a file named main.css is included in the stylesheets/ directory.

I chose not to place the theme's images or stylesheets in the browser/ directory, as this is generally unnecessary for most themes. Advanced programmers may wish to expose these items to the browser layer, but this is generally a personal choice and carries with it additional consequences.

I deleted the folders mentioned above, as well as the i file. Then, I opened the file named configure.zcml, located at plonetheme.guria/plonetheme/guria/browser/, and removed all of the following boilerplate text:

<!-- Viewlets registration -->
<!-- Zope 3 browser resources -->
<!-- Resource directory for images -->
<!-- Resource directory for stylesheets -->

I then removed the highlighted code below fromI then removed the highlighted code below from plonetheme.guria/plonetheme/guria/profiles/default/cssregistry.xml::

<stylesheet title=""
media="screen" rel="stylesheet" rendering="import"
cacheable="True" compression="safe" cookable="True"
enabled="1" expression=""/>

And replaced it with the following:

<stylesheet title=""
media="screen" rel="stylesheet" rendering="import"
cacheable="True" compression="safe" cookable="True"
enabled="1" expression=""/>

This, in effect, tells our theme product that we will be using a stylesheet named guria.css (or more correctly, guria.css.dtml, as we'll see in a moment). This stylesheet does not yet exist, so we have to create it.

I wanted the option of making use of the DTML behavior provided by Plone, so that I could use certain base properties provided to us via the base_properties.props file (also located in our skins/guria_styles/ folder). DTML essentially allows us to use property-sheet variables and apply changes on a more global scale. The easiest way to create this new stylesheet is to go to your mybuildout/buildout-cache/eggs/Plone[some version number]/Products/CMFPlone/skins/plone_styles/ploneCustom.css and copy the contents of that file into a new stylesheet (named guria.css.dtml) in your theme's guria_styles/ folder (located in the skins/ directory at mybuildout/plonetheme.guria/plonetheme/guria/skins/guria_styles). The important bits of code you want are as follows:

/* <dtml-with base_properties> (do not remove this :) */
/* <dtml-call "REQUEST.set('portal_url', portal_url())"> (not this
either :) */

/* </dtml-with> */

Again, we would need to restart our Zope at this point, as we have modified our ZCML.

If we had already installed our theme product, we'd also have to import our cssregistry.xml file via portal_setup in the ZMI, to capture the new GenericSetup profile settings. However, we have not yet installed the product, so we do not need to worry about this.

(For more resources on Plone here.)

Installing the theme product

Now that we've looked a few of the changes we've made to distinguish our theme product from a default Plone theme, let's go ahead and install it. Some of you may already have installed your theme product, and that's okay.

Go to your Zope instance (for example, http://localhost:8080/manage_main), and choose Plone Site from the drop-down list on the top right. Or, you can go to this URL: http://localhost:8080/manage_addProduct/CMFPlone/addPloneSite.

You will then see the following screen. For the purposes of this article, we are calling our Plone site mysite. Make sure you add a description for your Plone site, as we'll need that later.

Creating, Installing and Tweaking your theme using Plone 3

There are three ways to install your theme product:

  • You could optionally choose the theme product from the Extension Profiles list (as seen in the previous screenshot)
  • We could proceed to the portal_quickinstaller tool, located in the ZMI at http://localhost:8080/mysite/portal_quickinstaller/manage_installProductsForm

    Creating, Installing and Tweaking your theme using Plone 3

  • We could go to Site Setup Add-on Products| at http://localhost:8080/mysite/prefs_install_products_form

    Creating, Installing and Tweaking your theme using Plone 3

Let's select the extension profile named Guria Theme for the Plone Theming Book and click the Install button.

At this point, we should also put our site's portal_css in debug mode, so that we can see any CSS changes instantly. You should not leave a production site in debug mode, as it can negatively impact performance. You can reach the portal_css area at http://localhost:8080/mysite/portal_css/manage_cssForm. Simply select the Debug/development mode checkbox and press Save. The Save button may appear at the bottom of the page:

Creating, Installing and Tweaking your theme using Plone 3

Now, if you visit your site's home page, you should see the installed product as seen next, but we need to do a few things to make it look fully formed.

Creating, Installing and Tweaking your theme using Plone 3

Adjusting web site content to support the design

As we can see, the installed theme does not exactly match the look of the first screenshot of this article. Many CSS styles are in place, but the searchbox is in the wrong location, and there is a calendar portlet present. You may also notice that breadcrumbs are not present, as they are suppressed using CSS styles. Additionally, the center page content is not yet populated.

To make the site look more realistic, we need to adjust our viewlets, as well as add and suppress some content and portlets on the web site to support the design.

First, let's adjust the viewlets on the site by going to http://localhost:8081/mysite/@@manage-viewlets. We have to do this because the Guria theme does not use ordering to organize the viewlets. At the time that the theme was created, ordering was not functional, but should be now. Using the up arrow, next to the searchbox with the orange "Go" button, you can move the viewlet directly below the viewlet called ViewletManager: plone.portaltop (

Creating, Installing and Tweaking your theme using Plone 3

This should move the searchbox into the proper location.

Next, we want to add five new folders. To do so, use the Add menu located on the home page, and choose the Folder option. You should create some sub-navigation items (pages or folders are easiest) for at least one of these sections to see the styling of sub-navigation items. Make sure you publish each of these items.

Creating, Installing and Tweaking your theme using Plone 3

Once we have added a few folders, we need to adjust the settings of the navigation portlet. Click on the Manage portlets link on the bottom-right of the screen while on the home page, or go to http://localhost:8080/mysite/@@manage-portlets.

The navigation portlet has been added to the site by default. Click on the Navigation portlet link. You will see the following screen:

Creating, Installing and Tweaking your theme using Plone 3

Give the portlet a name and set the start level to 0. This will allow the navigation portlet to show on the home page. Choose Save, and then on the main @@manage-portlets screen, we want to remove the right-hand portlets. As you can see, these include review List, News, Events, and calendar:

Creating, Installing and Tweaking your theme using Plone 3

Click on the X next to each item to remove each portlet, then click on the Plone logo to return to the home page. You should see the left-hand navigation portlet and no portlets on the right-hand side of the page. This gives us what we need to finish building out our design.

The Guria theme was intended to use the homepage_view page template, as seen in the theme product's skins/guria_templates folder. This view requires the creation of a folder in the root of the site, called homepage, plus several pages (or collections) named slot1, slot2, and slot3. You can optionally create these too if you want to use this particular view.

The alternate view, homepage2_view, also located in the skins/guria_templates folder, requires the creation of a folder named homesection (slightly different from the homepage_view example, just to show the difference between the two views), plus the creation of several pages (not collections) named r1c1 and r1c2. Make sure these names are the shortnames, not just the title of the pages.


In this article, we have learned how to:

  • Create a custom theme product
  • Modify the file structure
  • Set up a Plone theme to use mostly skin layers for images and stylesheets
  • Install the theme product
  • Customize the content of your site to support the design

Further resources on this subject:





You've been reading an excerpt of:

Plone 3 Theming

Explore Title