Skinning Portals

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 blue might define its layers as blue, basic_css, general. This means that name lookup for something like standard_html_header looks first in blue, then basic_css, and then general when the skin blue is active.

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 default view, 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 portal_skins object, 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.

Images

This folder only contains non-icon images that are used in the default skins.

content

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.

control

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.

custom

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.

generic

The generic look and feel of the site. This is where you'll find things like the default standard_html_header and actions_box DTML methods, as well as the DTML Methods used for the reconfigure portal page. The default style sheet setup (used in the skin basic) also lives here.

no_css

Used by the No CSS skin, this folder contains a file system properties object that disables the style sheet normally used in the skins.

nouvelle

Used by the Nouvelle skin, this folder contains a nouvelle_stylesheet, and a filesystem properties object that supplies the values used in nouvelle_stylesheet.

topic

If you have CMF Topic installed, you should have a topic folder 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 Find tab in Zope can be very helpful. From the portal_skins tool, do a find for the item you want to customize, such as standard_html_header.
• Read standard_html_header and standard_html_footer enough 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 Customize 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 portal_skins/custom/news_box. This is where you can safely start to customize your own site, independant of whatever changes occur in the default stylings of the CMF.

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 them.

This is done on the Properties tab of the portal_skins tool. 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 actions_box is encountered, it's first looked for in custom, then topic, then 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.