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

In part 2 of my series on Plone 4 (see part 1 here), I’m looking into changes in theme development and all of the necessary steps to quickly get setup for building a cool theme. I’ve got some themes in mind, but before I commit to that, let’s get right into how to get going with Plone 4 themes.

RTFM – Get the Docs

So the first step really pays off here – RTFM…or just google “Plone theme limi”. The place to go on the Plone site is here. Also I would definitely encourage you to look at how installations of Plone and Plone products have changed with version 3 and 4.

Some Things Never Change – ZMI Matters

For starters with Plone 4 the ZMI interface has not changed a whole lot. That’s good and bad (all my old catalog indexing and archetype schema updaters are still there 🙁 ) I guess, but for themes at least it means there’s still the checkboxes to turn on and off CSS debugging in the ZMI.

I started running thru the theme reference…well I’m a questioning kind of guy. It starts off talking about searching for ploneCustom.css instead of just telling you where to navigate…and then just pick the one with the red asterix. Why? I suspect that’s the active one…but where is it? I found it in portal_skins/classic_styles – so that’s solved. Remember I switched to the classic plone look in the main admin system.

From there on the theme reference is pretty darn good. So I have Firefox 3.6.x with Firebug installed XRay. I’m going to try and use IntelliJ’s IDEA for development (we’ll see how that goes) – there’s a plugin for python development – JetBrains also has a very nice looking python IDE in a late beta, but for now I’ll stick with the basics. I first messed around a bit in the ZMI making sure that I can make CSS changes in there  – that seems to work ok. If you are following along in the theme tutorial you ‘ll really need to use Firebug to properly see differences in the CSS naming. For example h1.documentHeading is now ht.documentFirstheading I think. Basic point I guess is that you can still edit CSS directly in the ZMI just like in Plone 3 once you get familiar with the CSS tags. One thing to note in Plone 4 “baseproperties” is gone.

What I see as a good way to explore the Plone CSS concept is to turn on Firebug, make sure you have CSS debugging on, and turn on debug in your zope config by editing the zope.conf file in usr/local/Plone/zinstance/parts/instance/etc,  and then you can inspect various elements. The ones you want to change you can then put into the ploneCustom.css file. Another thing I did was to open up a separate window in Firefox and then turn on xray – then print that to PDF so you have the IDs there for reference.

Grabbing and Installing a Theme

Things have changed a bunch with installing stuff in Plone. The recommended way is the new “egg” method and buildout which sounds quite a bit like maven. Before I start messing with my own theme it seems that an easy way to see what is happening is to grab one from the plone.org site and get it working. There are 4-5 Plone 4 compatible themes up there. I’m going to grab plonetheme.labs from Menttes using the buildout concept. In theory this should be simple – just add “plonetheme.labs” to my egg list in the buildout.cfg file, kill the zope server, run ./buildout (from the zinstance directory), then restart the Plone instance and I should have a new theme.

Modifying a Theme and Rolling Your Own

WOW! – It worked! Well that’s pretty cool…now let’s check out what happened and where stuff is on the filesystem. I see a few things on the file system. In the buildout-cachedownloadsdist folder there’s a tar file of the theme and in the buildout-cacheeggs plonetheme.labs-1.1b1-py2.6.egg I see an extracted version of the theme. So the question is – can I now take one of these and directly modify these files or do I need to code stuff somewhere else? But hang on a second – this plonelabs skin folder structure is really different from the sunburst one. At this point the reference guide is not so useful since it is now a Plone 3 only reference in this section.

I’m going to switch back to sunburst – this comes with Plone. I assume that this is the best reference for how it should be done. I poked around inside these folders in the buildout-cache space and yes this is the folder space that Plone is loading into the web browser. I edited the main_template.pt file in sunburst/skins/sunburst_templates and the changes show up on my site. There it is to the left- fancy!

I pointed InteliJ IDEA at this folder  (after installing the python plugin), used the wizard for creating a new project from scratch, chose the Python Module aspect, and created a new project right there.You need to add the python and plone libs to the path of IDEA, but then you need some way to get the IDE to know about the plone libraries and templates. Not sure that is possible. For the time being I think I’ll just use gedit, although JetBrains does have an interesting Python environment in beta.

Using the Sunburst theme as a model, I’ve determined that:

• The code files for the theme are all in the skins directory
• configure.zcml looks like the main configuration file. – there are a couple of these
• The main CSS file is public.css – directly editing this file will change up the CSS across the site.
• base_properties.props does exist in this theme, but I’m not sure if it is really used.
• There are some python classes and scripts. In general the theme looks quite a bit more complex than in Plone 3.

I can edit the /sunburst_templates and the changes show up on site. There it is to the left- fancy! I don’t think editing things in the buildout-cache space is what you are supposed to do. After reading a bit, I figured out that you can place a copy of the theme in the “src” directory and then add the proper entries to the buildout.cfg file and plone will pick up your theme.  Prior to doing this however you need to go through all the files and change out the theme’s “sunburst” references for something else (I used mySunburst). I added:
eggs =
Plone
PIL==1.1.6
plonetheme.mySunburst
to the eggs section of my buildout.cfg and:
develop = src/mySunburst
to the development eggs section. After re-running buildout my new skin shows up in the site setup screen. This is when I made a fatal mistake – I never backed up my instance. D’oh – I tried to install the theme and kaboom! I just get an error that the default document in missing. I’m screwed at this point.  I tried a few things to fix it, but no luck. Time to re-install (later learned how to fix it without reinstalling). This time however I’m going to make things easier on myself and do a non-root install so that I don’t have to spend so much time “sudo” and “chmod”-ing all the time. To install as non-root simply run the installer as the account you want and Plone will be installed in that user’s home directory.

Backing up Plone 4

So now that I’ve learned that a backup is important (or really remembered this from the distant past…and of course the readme.txt that very clearly told me to take a backup before I started messing around), I’m going to follow the instructions right in the readme.txt for how to do this. Well – that’s not going to work out. I can see that the guts of the repozo backup recipes  are installed and seem to be ok, but the main repozo wrapper that should be in the bin is missing. I google’d and searched around the plone site. I found one hit that said the wrapper is not working in Plone 4 right now. That means the best alternative is to .gz the entire instance.

Back to the Theme

Now that I have my backup created I can see what’s wrong with my theme. First I’ll put the required mods back into my buildout.cfg, take down the server, copy my theme into src, run buildout, and startup plone in debug mode. I did also grab a complete .gz of everything in my plone directory – call me paranoid. For some reason I can see that after my skin is installed, the templates, images, and styles in the folders are not getting installed – thus rendering my Plone site DOA, but I did figure out that if I go into ZMI and set the default skin back (your site/portal_skins” and select the properties tab. Then scroll all the way down and there’s a select box to set the default style.) to the original, then everything will be ok again. I’ll have to do some more exploring into this and what’s wrong. I suspect a path in a config file is messed up. I also suspect that there is some easier way to generate a Plone 4 theme using paster or some other nifty trick. For now though I’ll figure out my path issues and then do some research on that while I search around for an easier way.

Later that day…a quick update. Well I’m not sure exactly what I did, but I fixed it…path issues I think and perhaps some case sensitive stuff. I’ll make sure that things are reproducible and post a Pt3 that details my working skin. I’ve created 4-5 Plone sites and I’ll make sure I can repeatedly install my skin on them with no issues.