(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 https://svn.plone.org/svn/collective/plonetheme.guria/trunk using the following command:

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:

This theme was created by me, for use by a charity group in India, called Guria (http://www.guriaindia.org), 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 (sixfeetup.com). 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 http://plone.org/documentation/how-to/adding-portlet-managers and http://plone.org/documentation/manual/theme-reference/elements/viewletmanager/override.

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
plonetheme.guria
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
Variables:
egg: plonetheme.guria
package: plonethemeguria
project: plonetheme.guria
Enter namespace_package (Namespace package (like plonetheme))
[‘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?)
[False]:
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.
plone.org’]: [email protected]
Enter keywords (Space-separated keywords/tags) [‘web zope plone
theme’]:
Enter url (URL of homepage) [‘http://svn.plone.org/svn/collective/’]:
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
[snip]

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

[buildout]
…
develop =
src/plonetheme.guria
…
[instance]
eggs =
plonetheme.guria
…
zcml =
plonetheme.guria
…

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 http://pypi.python.org/pypi/buildout.eggtractor, 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:

<configure

i18n_domain=”plonetheme.guria”>
<genericsetup:registerProfile
name=”default”
title=”Guria Theme for the Plone Theming Book”
directory=”profiles/default”
description=’Extension profile for the “Guria Theme for the
Plone Theming Book” Plone theme.’
provides=”Products.GenericSetup.interfaces.EXTENSION”
/>
</configure>

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:

<configure

i18n_domain=”plonetheme.guria”>
<!– File System Directory Views registration –>
<cmf:registerDirectory
name=”guria_images”/>
<cmf:registerDirectory
name=”guria_templates”/>
<cmf:registerDirectory
name=”guria_styles”/>
</configure>

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”
cookie_persistence=”False”
default_skin=” Guria Theme for the Plone Theming Book “>

<object name=”guria_images”
meta_type=”Filesystem Directory View”
directory=”plonetheme.guria:skins/guria_images”/>
<object name=”guria_templates”
meta_type=”Filesystem Directory View”
directory=”plonetheme.guria:skins/guria_templates”/>
<object name=”guria_styles”
meta_type=”Filesystem Directory View”
directory=”plonetheme.guria:skins/guria_styles”/>

<skin-path name=” Guria Theme for the Plone Theming Book ” based-
on=”Plone Default”>
<layer name=”guria_images”
insert-after=”custom”/>
<layer name=”guria_templates”
insert-after=”guria_images”/>
<layer name=”guria_styles”
insert-after=”guria_templates”/>
</skin-path>
</object>

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 –>
<browser:resourceDirectory
name=”plonetheme.guria.images”
directory=”images”
layer=”.interfaces.IThemeSpecific”
/>
<!– Resource directory for stylesheets –>
<browser:resourceDirectory
name=”plonetheme.guria.stylesheets”
directory=”stylesheets”
layer=”.interfaces.IThemeSpecific”
/>

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=””
id=”++resource++plonetheme.guria.stylesheets/main.css”
media=”screen” rel=”stylesheet” rendering=”import”
cacheable=”True” compression=”safe” cookable=”True”
enabled=”1″ expression=””/>

And replaced it with the following:

<stylesheet title=””
id=”guria.css”
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 🙂 */
/* DELETE THIS LINE AND PUT YOUR CUSTOM STUFF HERE */

/* </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.