Document Actions

Customising Plone's Appearance

Customising Plone's Appearance - Plone 2 (written by: Ben Calder)

Introduction

Having recently started experimenting with Plone 2, the first thing I wanted to do was apply the skin I created for Plone 1 to my test site (see the guide to customising Plone1). Inevitably I found that some elements wouldn't work, and of course there have been a few changes to how things behave in Plone 2! I've stuck with my policy of keeping as many of the changes in the external filestore as possible... This means it's still a simple process to apply it to sites on other servers by simply pasting a folder containing all the custom elements into the plone_styles folder (see step 1 below) and making a small change in the ZMI... Alternatively it's possible to turn your skin into a product (see references at the end).

I have to add a quick disclaimer here: I'm no Plone/web 'expert' (I'm learning it all as I go along) and whilst I've found that these instructions do work...' there may be a better way...' (there usually is ;)

Basic Setup

Create a new folder in C:\...\Plone\Data\Products\CMFPlone\skins\plone_styles\
As yet there aren't any custom skins released with Plone 2 so you'll have to start from scratch with an empty folder.
After doing a refresh - in the ZMI go to /Plone/portal_skins and click on the properties tab.
This is where you'll find the first change from Plone 1 (though maybe this is a chnage in Zope?) - the skin layers are listed much more clearly. To add a new skin give it a name, then copy the layers from Plone Default and paste them into the layers for your new skin. Find the reference to plone_styles and change it to the path of your custom skin folder - i.e. plone_styles/CustomSkinFolder. Click the add button.
One other change you may need to make here depends on what you intend to customise... You'll notice that the layers are "in order of precedence". So if you want to make changes to templates or portlets and store these in your custom skin folder you're going to need to move the path to your skin above plone_templates and plone_portlets. This can be achieved by simply cutting and pasting the path within the layers listing.

Nb - I'm not aware of any problems with this approach and, as yet, haven't found any - but that doesn't mean there aren't any...
You can still use the Plone refresh tab in the ZMI, alternatively if you're running Plone on Windoze you could just use the services tool from the control panel and restart Zope from there...

Nb. Changes to images - ie the logo etc may not show up in the browser unless you force a full refresh. Try Ctrl-F5 or emptying the cache and doing a normal refresh...

Custom Style Sheets (CSS)

Copy the ploneCustom.css.dtml from the plone_styles folder into your custom skin folder. You can customise elements within the default plone.css.dtml (and apparently ploneColumns.css.dtml) by including them within this custom file - elements will be acquired from the custom file first. You can also define custom classes should you want to include these in custom templates. (Changes to this can be seen through a ZMI/Plone/Refresh.)

base_properties.props

This is another change in Plone 2. The old stylesheet_properties.props is now deprecated and has been replaced by the far simpler base_properties.props. So if you want to customise anything from colour schemes to fonts you'll need to copy this file from plone_styles into your custom skin folder. it also makes it simpler to have a different filename for your logo, and more importantly a different file extension (see logoName)...

This works in just the same way as the old stylesheet_properties in that it is referenced by the Plone CSS files - in fact if you open ploneColumns.css.dtm you'll see that there's a handy reference on how to use it and also to what each element does, which will save me going into detail here :)

In brief any element in the Plone CSS files that has a prefix of &dtml- and then a name (for example: &dtml-backgroundColor ) is a reference to the value in base_properties. This means that you can make changes to all these CSS values by changing them once only in base_properties...

It is also possible to add new element's to base_properties and refer to them in a custom css file using the &dtml- prefix.

(You may have to do a forced refresh (Ctrl-F5) or empty your cache to see the result of changes to this file.)

Custom Templates, Portlets etc...

As before making changes to templates or portlets can be achieved by copying the template or portlet .pt file you wish to customise into your custom skin folder (and making sure that your custom skin folder is placed above plone_templates in the layers listed for your skin in the ZMI) and editing it there. You'll need to use HTML, TAL etc...

TAL (Template Attribute Language) is used to incorporate dynamic elements in your custom template. You'll find a good reference on this language in the Zope book:

http://www.zope.org/Documentation/Books/ZopeBook/current/ZPT.stx

http://www.zope.org/Documentation/Books/ZopeBook/current/AdvZPT.stx

You may also need to use Python. Again the Zope book has a good reference:

http://zope.org/Documentation/Books/ZopeBook/2_6Edition/ScriptingZope.stx

Custom 'Headers'

This is another major change for Plone 2. Previously the header.pt file controlled not only the appearance of the site header but also elements crucial to the functionality of Plone. Unfortunately this meant that anyone making changes to their header would have to implement these each time any major changes were made to the default header to incorporate any changes in functionality. This is no longer a problem :).

The trick I've used is to create a custom version of main_template.pt. You'll see that this defines the layout of the page as a whole, including elements used in the header. I've commented out some of these elements (e.g. the logo and breadcrumbs) and also added a <div> with a reference to a custom macro as follows:

<div metal:use-macro="here/ucl_skin/macros/ucl_header">
Custom Header for UCL...
</div>

I've then created a macro in my custom skin folder, saved as ucl_skin.pt, which defines the macro 'ucl_header' and includes the html and TAL elements (including the logo and breadcrumbs I previously commented out) I needed to create my custom header:

<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en-US" lang="en-US"
i18n:domain="plone">
  <body>
    <div metal:define-macro="ucl_header">

      

    </div>

  </body>
</html>

Whilst there may be future changes to main_template.pt, it's going to be a simple matter to add in the <div> referencing my macro and commenting out any elements I don't require, or that I include in the macro. Of course if you're going for a pure CSS layout you wouldn't even need to comment things out... but I'm not quite there yet ;)

My note in the Plone 1 customisation guide about custom templates in the ZMI overiding these external templates will still apply if 'custom' is higher in the layer order of predence than your custom skin folder.

Graphics

No changes here:

You can easily change any of the graphics that are used on your site. Find the graphic you want to change in C:\...\Plone\Data\Products\CMFPlone\skins\plone_images. Create your image in a graphic editing program and save it into your custom skin folder giving it exactly the same name as the version in the plone_images folder.

Any extra graphics you add to a customised template within a custom skin should also be stored in the custom skin folder.

Graphics you want to make available in several custom skins (but where you only want one instance of the file) should be saved in C:\...\Plone\Data\Products\CMFPlone\skins\plone_images.

'Static' pages

No changes here either:

You can create 'static' pages (those that don't display within the Plone site navigation) by adding these into the custom skin folder. Create a standard HTML file and give it a .pt extension. To link to these pages from within a custom template you don't need any complicated paths - just put in href="/filename" in your link.

Static pages you want to make available in several custom skins (but where you only want one instance of the file) can be saved in C:\...\Plone\Data\Products\CMFPlone\skins\plone_forms.

Troubleshooting

If any of the above fail to make a difference to your site there are a few things you should check:

Is your browser using a page element stored in its cache? Try doing a forced refresh (Ctrl-F5 in IE) or emptying its cache before refreshing.
Check the layer order of precedence for your skin in Plone/portal_skins/properties tab. Make sure your skin isn't being overidden...
If 'custom' still has a higher priority in the layers check for custom versions of your files in the ZMI - in Plone/portal_skins/custom.
Check filenames - make sure filenames aren't mistyped or capitalised.