Plone 4 – Catching Up with an Old Friend Pt. 3

In this post I’ll detail how to take the default “sunburst” theme and use it as a base for creating your own theme in Plone 4. I’ll be assuming that you at least glanced through part 1 and part 2. I’m not sure yet what kind of theme I’ll be building, but the sunburst theme probably the best places to start.I’ll caveat this post saying that what I’m describing is what I managed to “hack out”,  but take it all with a grain of salt since I wouldn’t call myself a Plone expert – just a semi-irregular user that likes to hack around.

To start I took a complete copy of the theme from the “eggs” directory and exploded it in my instances “src” directory. I then painstakingly went thru ever file and folder (and all folder names) and replace “sunburst” with “mySunbusrt”. I’m sure there is some tool out there for plone that could automate this process, but I couldn’t find it. Not that big of a deal anyway.

After completing that you’ll need to edit your buildout.cfg file so that it will pickup the new skin. It is very important to understand the namespace/folder arrangement. Similar to Java, the “namespace” concept here is folder based and has to be in your code too (just like Java packages). So “plonetheme.mySunburst” is my theme’s namespace. In my  buildout.cfg file I then need to inlcude this in two places:

############################################
# Eggs
# ----
# Add an indented line to the eggs section for any Python
# eggs or packages you wish to include.
#
eggs =
 Plone
 PIL==1.1.6
 plonetheme.mySunburst

and in this section too:

############################################
# Development Eggs
# ----------------
# You can use paster to create "development eggs" to
# develop new products/themes. Put these in the src/
# directory.
# You will also need to add the egg names in the
# eggs section above, and may also need to add them
# to the zcml section.
#
# Provide the *paths* to the eggs you are developing here:
develop =
#    src/my.package
develop = src/mySunburst

Make those changes, stop your plone instance is you have it running, re-run buildout, and then start it back up. You should see your theme in the Add Products. Now ask yourself an important question: do you have a complete backup? If you don’t then really proceed with caution. Now try to install your theme. Did it work? You should see the Plone site and your theme now as the active theme. If you have any errors, you can check the logs and see what the problem is. What I found was that I had missed changing out a “sunburst” reference for a “mySunburst” reference somewhere.

Anatomy of the Theme

My investigation of the theme structure leads me to initially focus on understanding two key files: main_template.pt and public.css. The former is the main python template that defines the xHTML layout of the content and the latter is the main CSS file for computer based browsers (there’s a separate css for mobile browsers). To really understand main_template.pt you need to know about the templating and macro system that Plone uses – go check plone.org to learn about that. This script file includes things in pretty big chunks so it will be necessary to find and modify more than just this one template file.

The CSS structure is pretty well thought out, that’s where I started playing around – using Firebug to inspect elements and the editing the CSS in gedit. Adjusting the colors, menu sizes, fonts, and other basic elements is pretty simple. You can see in the screen shot that I’ve managed to make a bunch of changes rather quickly. If you have your instance in debug mode you can just reload the page to see the changes. Looks great, right?

If you look in the ZMI you can browse thru various templates in the /your_site/portal_skins/plone_templates folder, but many of the templates are not registered in here and you need to browse around on the file system. I found a ton of templates in the buildout-cach/ EGGS/plone.app.layout-2.0.2-py2.6.egg folder. Look in plone.app.layout.viewlets, but when I copy one of these to my skin and  change it I don’t see the changes. I’m not sure why. If I browse thru the ZMI and “customize” the template then I do see it. There must be some problem with how I’ve created my theme, but I can’t seem to figure it out.

Argh – well this is going nowhere fast – well this proves that complex technology is complex and you need to spend time learning or let others lead the way. I’m still positive about Plone and I’m, going to keep at it. I think its just to early for the casual guy to expect to jump in and instantly “get it”. No problem…I’m going to keep at it and I guess there will be a “pt 4”. To be continued…

Leave a Reply