Creating a Dexterity Based Plone Add-on (Plone 4.3.x on Ubuntu)

These are the steps to creating a Dexterity based add-on in Plone on the Plone 4.3.x platform. Consider this the "Hello World" example. From here you could move on to something like the Todo application tutorial http://tutorialtodoapp.readthedocs.org/.

update: If you need to started quickly, try out Plone in the cloud with Nitrous.io.

Background

A lot has changed in a year. With services like Digital Ocean it is now feasible to deploy a Plone site on a $5 per month server. The documentation for Plone development has been mostly consolidated at the developer.plone.org website, Dexterity is now firmly the recommended approach for new developers and the latest version of Plone ships without 'builtin' grok and relations support. The following tutorial takes these changes into consideration and walks through the process of setting up an add-on. This was tested on a $5 per month Digital Ocean droplet, but should work just as well on a free Nitrous.io box.

For this project we assume the use of the Unified Installer, which assumes the use of a Unix based platform. The example is based on an Ubuntu 12.04 platform.

Start by Installing Plone

Note: We used Ubuntu 12.04.

Install the following as the root user:

apt-get install python-distribute python-dev build-essential libssl-dev libxml2-dev libxslt1-dev libbz2-dev 

apt-get install libjpeg62-dev libreadline-gplv2-dev wv poppler-utils python-imaging

(For more information on installation read http://developer.plone.org/getstarted/installation.html#ubuntu-debian)

For this exercise I created a 'zope' user (you can have any user). As the 'zope' user I ran the following commands.

wget https://launchpad.net/plone/4.3/4.3/+download/Plone-4.3-UnifiedInstaller.tgz
tar xvfz Plone-4.3-UnifiedInstaller.tgz
cd Plone-4.3-UnifiedInstaller
./install zeo

The result was a Plone installation with a buildout directory at $HOME/Plone/zeocluster

Starting and Stopping a ZEO based Zope

(I thought I'd mention this here, so you don't have to go searching all over the place while following along). During development you'll need to occasionally start and stop Plone. The following commands will be very handy.  A quick way to get to the buildout directory is to run the following command:

cd $HOME/Plone/zeocluster

Run these commands from the $HOME/Plone/zeocluster directory:

To start the services:

bin/zeoserver start
bin/client1 start
bin/client2 start

To stop the services:

bin/client1 stop
bin/client2 stop
bin/zeoserver stop

Note: If you used the Plone in the Cloud, Nitrous.io approach then there is also the option of using the plone-start.sh, plone-restart.sh and plone-stop.sh commands.

By default they run on port 8080 for client1 and port 8081 for client2.

The clients can be run in foreground mode, which can be useful for debugging, for example:

bin/client1 fg

Enabling Development Mode, add grok and relations support

In the $HOME/Plone/zeocluster directory, edit 'buildout.cfg' and add 'plone.app.dexterity [relations, grok]' to the 'eggs =' entry in the [buildout] section]. I'm used a few more eggs in my buildout, but it will look similar to this:

eggs =
    Plone
    Pillow
    five.intid
    Products.PloneFormGen
    collective.loremipsum
    plone.app.dexterity [relations, grok]

I like the grok approach so, to ensure that my Plone site works with grok I added the line above, for good measure the line above also enables relations support.

To enable development mode use the '-c develop.cfg' option with buildout

cd $HOME/Plone/zeocluster 

bin/buildout -c develop.cfg  

After running that command, you should have all the tools needed to create your first dexterity based add-on.
warning: running bin/buildout (without the '-c develop.cfg' option) disables many of the development features.

Locate your buildout directory:

By default it will be one of the following locations:

$HOME/Plone/zeocluster
$HOME/Plone/zinstance
$HOME/workspace/zeocluster # if you used the Plone on Nitrous.io setup

Quick Test of your commands

From your buildout directory you should be able to run the the following commands

bin/zopeskel dexterity
bin/zopeskel plone
bin/zopeskel diazotheme

Creating your first Dexterity Add-on

By convention, during development, add-ons are placed in the 'src' directory. From the buildout directory go to the 'src' directory and generate the add-on:

cd src
../bin/zopeskel dexterity hello.world

Note: pay attention to the two preceding dots and the slash ../bin/zopeskel

You should see output similar to this. For my 'hello.world' add-on I entered the following:
Export Mode? easy
Version: 1.0a
Description: Hello World Product

Trying out the add-on

Return to your buildout directory to edit the develop.cfg file. Add the add-on to your buildout by editing the develop.cfg file in two places:

Tell your buildout that hello.world is a filesystem based source project by adding the following line under the [sources] section:

hello.world = fs hello.world

Add hello.world to your available packages (packages in the Python world are called ‘eggs’). This is achieved by in the [buildout] section by adding the new package to the eggs +=:

eggs +=
    Products.DocFinderTab
    plone.reload
    hello.world

Then re-run 'bin/buildout -c develop.cfg'

Start any one of the clients (see notes above on starting and stopping) and add a Plone site. Your new add-on will be available under 'Site Setup' of your site:

 That's what you need to know to get started.