Skinning CMF Sites (DRAFT)
About this document
This document is an overview of the concept of skinning, one of the new techniques used in the CMF to allow customization. This document assumes familiarity with Zope concepts such as DTML and the Zope Find tool.
About the skins tool
In the Zope CMF (Content Management Framework), a new concept has been introduced called Tools. These tools perform services for content objects, letting the content objects be all about the content they represent. One of these tools is the Skins Tool, portal_skins. The skins tool moves the site-specific behavior away from the objects in the system, allowing a high degree of customization without requiring changes be made to the core classes of objects being used.
The problems it solves
Many Zope classes written in Python have direct links to their management screens, which ties objects too closely with their views. Sometimes ZClasses can be used with Python classes as their base, putting all of the logic associated with an object in the base and all of the views as DTML methods in the ZClass. But this runs into distribution problems: typically, a CMF developer would customize the views in a ZClass for their site. But when a new CMF release was issued, their changes stood a good chance of being overwritten.
So the problems that needed to be solved were:
- Views of an object needed to be separated from the object.
- The default views should be easy to update and distribute in the core product without affecting CMF Users customizations.
- CMF Users shouldn't perform their customizations on the default set of views, but should have an easy way to customize and override.
- Allowing multiple skins to coexist. This gives quite a few benefits, including the ability to do internationalization of sites.
What's in the skins tool
So how does the Skins Tool solve these problems? There are a few things that come together to form a skin:
- A definition of layers
- A proper skin is a definition of layers.
- What those layers are
- That definition of layers is a list of
folderish objects containing DTML, Images, and Properties (or
folders defining properties). A skin named
bluemight define its layers as
blue, basic_css, general. This means that name lookup for something like
standard_html_headerlooks first in
basic_css, and then
generalwhen the skin
There are two types of places these names can come from by default:
- FileSystem based default -- This is how the distribution problem is solved. These are special objects that represent a view onto DTML, Properties, and Images that are stored on the file system in the CMF product. The important thing here is that they cannot be changed through the web. Updates to the CMF Product will replace these files, so it's important that they don't get changed. These show up as locked items, reflecting that the user cannot change them.
- Custom folders -- These are normal Zope folder objects that can contain normal DTML Methods and other objects. Updating the CMF product won't touch what's in these folders. And there's a special trick that the FileSystem based objects perform: they have a customize action that lets you copy the source of a FileSystem based object into any of the custom folders in the skins tool.
The rest of this document explains in greater detail how you use these facilities to start customizing your CMF site.
How to start skinning
Looking deeper at the skins tool
This section assumes that you've already set up a CMF Site instance and are in the Zope Management Interface (ZMI)
It's time to look deeper at the skins tool to learn a little more
about what's in it by default. Go to the
portal_skins object in
your CMF Site in the Zope Management Interface (ZMI). In the
contents, you should see about seven or eight
folders depending on your setup and the configuration of the CMF.
Most of the folders have little green locks on them. These are
Filesystem Directory View objects. They and their contents
cannot be changed through the ZMI. By default, there is one normal
Zope folder in the skins tool,
custom. This is where we'll start
making our customizations.
By clicking on the
Properties tab of the
you'll see how skins are actually configured. By default, there
are three skins: Basic, No CSS, and Nouvelle. A skin is made
by layering different folders in the skins tool together. In the
Layers column in the skin selections area of the properties page
are the comma separated lists of folders, in the order the lookup
happens in for that skin selection.
Looking at the default folders
There's a default base of FileSystem DirectoryView objects that are installed in the skins tool by default. This section covers what's inside.
- This folder only contains non-icon images that are used in the default skins.
- This folder contains skinned DTML Methods and icons for the default set of Content objects (from the CMFDefault package). These are for things like Document, File, etc..., as well as some common DTML Methods for all content objects, such as metadata editing forms and forms that support the default workflow configuration.
- This folder contains DTML Methods acting as some common control scripts. Examples of this are folder_copy, a wrapper around the default copy method of Folders.
- A regular Zope folder to start doing customizations in. You can add other folders in the skins tool as well, but you'll likely start off here.
- The generic look and feel of the site. This is
where you'll find things like the default
actions_boxDTML methods, as well as the DTML Methods used for the
reconfigure portalpage. The default style sheet setup (used in the skin basic) also lives here.
- Used by the No CSS skin, this folder contains a file system properties object that disables the style sheet normally used in the skins.
- Used by the Nouvelle skin, this folder contains a
nouvelle_stylesheet, and a filesystem properties object that supplies the values used in
- If you have CMF Topic installed, you should have a
topicfolder as well. This contains Topic object specific views.
Hopefully the above can be used as a guide to help you find what you want or need to customize for your site. Some general rules I've used for locating content is:
- Use ZopeFind. The
Findtab in Zope can be very helpful. From the
portal_skinstool, do a find for the item you want to customize, such as
standard_html_footerenough to understand the different page components they're using. You may not need to customize either of these much at first. But you will need to know the named objects they're looking for.
- Get to know the general purposes of the default folders in the skins tool. Do some clicking around and look at the different DTML Methods. After a while, you start noticing some patterns and remembering which ones are complete pages and which are components to use in those pages.
Doing a simple customization
Let's do a relatively simple customization. If you're in a site
that doesn't have any news items yet, the default news box on the
Portal's front page says "No news is no news" by default. Let's
say we want to change that to say "There is nothing new under the
sun". The first step is finding the right thing to customize.
Since that news box isn't really bound to a particular content
object, it's safe to assume it's part of the
generic folder. If
you look in
portal_skins/generic, there are a couple of DTML
Methods with the name news in them. Select news_box and see what
comes up. Instead of the normal DTML Method edit form, you'll get
a grey box with the source code. Above the box is the
action form containing a pop-up list of folders available to
customize to. If you haven't added any new folders to the
portal_skins tool, the default (and only) option should be
custom. So, with
custom selected, click Customize. Now you
should be on a normal DTML Method editing form. If you look at the
path, you'll notice you're now in
This is where you can safely start to customize your own site,
independant of whatever changes occur in the default stylings of
In another browser window, go to the front page of your CMF Site
and verify that it says "No news is no news" in the news box
(again, this won't occur if you actually have news items). Then,
back in the
news_box edit window, change the part of the source
that says "No news is no news" to "There is nothing new under the
sun". Go back to your CMF front page and reload - it should now
say the new phrase in the news box.
Defining new skins
Making new skins is relatively easy. It's basically an expansion of what was described earlier in this document, and otherwise it's usage of fairly standard Zope techniques.
Making new folders in the skins tool
Doing all of your work in
custom can only get you so far,
although it may be enough. Chances are, you'll want to start
making new skins and organizing customizations. The skins tool is
completely open to this. You can make new folders in the
portal_skins tool, and they'll show up as target options in the
customize action on FileSystem objects.
I'm not going to go into any major examples here. There's a lot of
flexibility that can be excercised here. Some examples include
making a "Printable" skin - which typically involves stripping
sidebars and other site decorations from a page, or making skins
targeted at specific browser capabilities. For each of these, you
can start with one new folder in
portal_skins, such as
Printable or DHTML. Once you have these new folders, you can
start customizing into them.
Customizing into the new folders
This behavior is the same as was discussed in the earlier example -
visit a FileSystem based folder, select an object, and it's main
management screen will display the contents of the object and
present a list of folders you can customize it to. These folders
start from the
portal_skins tool and go down.
Defining and modifying skins
Remember that a skin is composed of layers, and those layers are
the folders in the
portal_skins tool. Just having the folders
there does not make a skin - you need to configure a skin to use
This is done on the Properties tab of the
On this page, there is a box titled Skin selections containing a
table of skin configurations. From this box, you can add and
delete skins as well as configure them.
Skins are configured to search through the identified layers from
right to left. By default, the file system views are the furthest
to the left and the custom views are closer to the right. In a
basic configuration that includes CMF Topic, you'll notice that
every skin configuration includes
custom, topic, content, generic,
control, Images. That means that when a name like
is encountered, it's first looked for in
content, and so on.
When you start making your own customization folders for skins, you can insert them into these lists, or define a new skin. When inserting, the best practice is to put your new folders at the beginning. When defining a new skin, it's best to copy the default list from an existing skin, such as Basic, and insert new layers.