Plone 3 Products Development Cookbook

Chapter 1. Getting Started

In this chapter, we will cover the following recipes:

Installing Python on Linux
Installing Plone on Linux
Installing Plone on Windows
Checking out code from a Version Control System
Creating a Plone site

Introduction

Plone is probably the best Python CMS (Content Management System). This means that it’s a piece of software that provides all the necessary tools for people to publish content.

Why do we say that Plone is the CMS? For several reasons:

It's easy to use
It's available in more than 40 languages
It has granular security
It's regularly updated
It's Open Source
It has almost everything we need and, if it doesn't, we can add that specific need

These two last are, no doubt, its most important features: Plone is extendible, because it’s also a framework, and that is what we’ll mostly cover in this book—the components that are part of the framework and how to use them to build our extensions.

Note

Find out more about Plone features at: http://plone.org/about.

In Plone, the extension facility is provided via the installation of products. Think of them as plugins, add-ons, extensions, or whatever name you want. In Plone literature, they are called products, though.

Note

While most Plone add-ons are technically Python packages, we will use the term products throughout this book because it is still very commonly used in Zope and Plone sphere.

As a matter of fact, Plone itself is a whole set of products, and some of its current basic features were born initially as additional characteristics, like Archetypes (more of this in the Chapter 3). With a little luck and a lot of work, one of your products may be included in a future release.

Note

You can find a variety of available Open Source community-developed products at http://plone.org/products.

In this chapter, we are going to install Plone (in both Linux and Windows). Plone is not an isolated software application, it needs Zope and other associated products to be installed as well. To understand this process and all these components, let’s define a not-too-comprehensive, but sufficient glossary:

Term	Definition
Python module	A file containing Python definitions and statements.
Python package	A set of Python modules.
Python egg	A way of distributing Python packages. It is very interesting because it provides not only the programming code but also metadata like the version number, dependencies, and license terms.
Buildout	An environment or system created with a configuration file that is used by a special Python package, named zc.buildout, to execute a set or parts in a repeatable way so that it can be run on different computers or operating systems.
Buildout Recipe	A Python package, used by `zc.buildout`, that performs a particular action, like compiling the source code of an application, downloading and extracting a `tar.gz` file, executing some shell commands, and so on.
Zope installation	The set of Python packages, templates, and other files needed to execute a Zope server.
Zope instance	A particular Zope server installation, each of which might have its own configuration set of add-on Python packages and database.

In the following sections, we’ll mainly look at a method named buildout for a proper Zope instance set up. However, we won’t cover all of its possibilities. Throughout the whole book, after adding products to the project we are developing, we will add recipes or parameters to the buildout file, which we will create in this chapter.

Installing Python on Linux

Plone 3 runs only on the old Python 2.4 version. Unfortunately, almost no modern Linux distribution (or distro) ships with or supports that version. To fill this gap, we can use a special buildout to install an isolated Python environment called virtualenv.

Even for the most modern Plone 4, which runs on Python 2.6, this method can also be applied, as we did find problems with Python 2.6, shipped with Fedora 11 and 12.

Note

The idea of using virtualenv is to have a Python installation independent from the operating system's: no matter which version of Python is native in the OS, your Plone site will still work, as it will be never modified again unless you do it explicitly.

This first buildout, not the one that we’ll use to install Plone, is a good place to start to understand its parts and the way it works.

Getting ready

To set up virtualenv, we need any version of Python installed first. So just run your own distro package manager to get it, if it is not installed yet.

Note

The following example installs Python 2.4.6 (the latest 2.4.x available at the time of writing) as a virtualenv. By changing the version number, you can apply the same method to create a Python 2.6 virtualenv. You can also get a copy of these two procedures in the source code that accompanies this book.

In the following procedure, we will compile and make Python, so we will need various packages installed in our system first. For Debian or Ubuntu, run this as root to get all the required dependencies:

# aptitude install gcc g++ libbz2-dev zlib1g-dev libreadline5-dev libssl-dev

In Fedora, run this command instead:

# yum install python-devel gcc gcc-c++ bzip2-devel gzip-devel zlib-devel readline-devel openssl-devel

Create a base folder for your Python 2.4 installation. We prefer ~/libexec/python2.4.

$ mkdir -p ~/libexec/python2.4
$ cd ~/libexec/python2.4

Then get the bootstrap Python script. This script installs the zc.buildout package inside the same buildout environment so that we won’t need any other external command.

$ wget http://svn.zope.org/*checkout*/zc.buildout/trunk/bootstrap/bootstrap.py

Note

Note that the *checkout* piece in the URL above is correct. It has no special meaning.

Enter the following buildout.cfg file to create virtualenv:

[buildout] 
parts = 
    python 
    virtualenv 
    make-virtualenv 

# Add additional egg download sources here. 
# dist.plone.org contains archives 
# of Plone packages. 
find-links = 
    http://dist.plone.org 
    http://download.zope.org/ppix/ 
    http://download.zope.org/distribution/ 
    http://effbot.org/downloads 

[python] 
recipe = zc.recipe.cmmi 
url = http://www.python.org/ftp/python/2.4.6/Python-2.4.6.tgz 
executable = ${buildout:directory}/parts/python/bin/python2.4 
extra_options= 
    --enable-unicode=ucs4 
    --with-threads 
    --with-readline 
    --enable-ipv6 

[virtualenv] 
recipe = zc.recipe.egg 
eggs = 
   virtualenv 

[make-virtualenv] 
recipe = iw.recipe.cmd 
on_install=true 
cmds = ${python:location}/bin/python
${buildout:directory}/bin/virtualenv --clear .

The above buildout configuration file has three parts, which have their own recipe parameter. Let’s go through each of them:

The [python] part uses the zc.recipe.cmmi recipe, which downloads Python source code and compiles it. The cmmi suffix stands for Compile Make and Make Install.
The [virtualenv] part uses the zc.recipe.egg recipe, which installs the virtualenv Python egg and creates the executable bin/virtualenv file.
The [make-virtualenv] part uses the iw.recipe.cmd recipe, which can execute arbitrary shell commands. In this case, it runs the installation of a virtualenv to create an isolated Python 2.4 environment in your system.

As you must have noticed, there are other lines of code besides the part definitions and their recipes. These lines are parameters required by every recipe, like url for the zc.recipe.cmmi recipe or cmds for iw.recipe.cmd.

Note

Note that you can reference to variables defined in the buildout by writing ${part:parameter} as used in the last line: ${buildout:directory}.

You can correctly guess that there are many different recipes, each with their special parameter configuration and variables. For instance, there are recipes to install Varnish (a proxy cache server) and MySQL.

Note

For a list of available recipes, you can visit http://pypi.python.org/pypi?:action=browse&show=all&c=512.

How to do it...

So far we have just created a configuration file to create a Python 2.4 environment, but we haven’t got it yet. So let’s move on.

Run the bootstrap process:
```
       $ python bootstrap.py
```
You should get an output like this:
Start the buildout process with this command:
```
       $ ./bin/buildout
```
Congratulations! You have successfully installed a clean Python 2.4 environment on your computer.
Now you have two different choices in how to use it:
Specifying its path:
```
~/libexec/python2.4/bin/python <script>
```
or by activating it to include it in your PATH environment variable:
```
source ~/libexec/python2.4/bin/activate
```
You’ll notice that this will change your prompt, as shown in the following screenshot:
Once activated, you can return to your original Python version by running:
```
(python2.4) $ deactivate
```
Note
In the screenshot above, you can see that there are actually three different Python versions installed. The system default version is 2.6.2, and there is also a 2.6.4 and a 2.4.6 available in separate virtual environments.

How it works…

By running the bootstrap process in Step 1, we download the zc.buildout package. This creates the required directory structure and generates an executable buildout file, which will read and process buildout.cfg.

In Step 2, the buildout process downloads the Python 2.4 source code, compiles it, and then it creates the virtualenv.

Installing Plone on Linux

Now that we have a valid Python version, we can install Plone.

Note

There is an alternate and very handy method to install Plone on Linux (and Mac and Windows) called Unified Installer. It is a bundle that installs not only Zope and Plone, but also Python and other necessary packages. If you want to try it, go to http://plone.org/download and download the version of your choice.

Getting ready

ZopeSkel is a Python package that provides development templates for Zope and Plone. It will help us at several different stages of our projects. We will use it here to create a buildout environment. First, we must be sure we have it properly installed:

Activate your just installed Python 2.4 (or whatever version you have installed) virtualenv:
```
$ source ~/libexec/python2.4/bin/activate
```
Install ZopeSkel:
```
(python2.4)$ easy_install-2.4 ZopeSkel
```
If you already have it, check for the latest version by running:
```
(python2.4)$ easy_install-2.4 -U ZopeSkel
```

How to do it…

Create a buildout with paster: Once you have the correct ZopeSkel version installed for your Python environment, run the following command to create a Zope/Plone buildout:
```
(python2.4)$ paster create -t plone3_buildout
```
Note
Starting with ZopeSkel 2.15, when creating buildout environments with paster, you will see a warning message informing you that Unified Installer is the best option for installations and paster is just for experts. Although Unified Installer is great and incredibly useful, we think Plone developers should know how to create a Plone environment from scratch and this is the way to do it.

Run the bootstrap process:

(python2.4) $ cd pox
(python2.4) $ python bootstrap.py

Edit the buildout.cfg file and locate the eggs parameter in the main [buildout] section and add PIL (Python Imaging Library) as a package to be downloaded and installed during buildout.
```
[buildout]
...
eggs = 
    PIL
....
```
Buildout your Zope instance: This last step is to run the buildout process.
```
(python2.4) $ ./bin/buildout
```

How it works…

Executing Step 1 will start a wizard to help with the creation of the buildout.cfg, we need. For each of the following options, provide these values:

Option	Value
Enter project name	pox, after Plone and OpenX, the fictitious project we are tackling in this book. Here you can choose whatever name you want and `paster` will create a directory with that name.
Expert Mode?	With the `plone3_buildout` template, no matter which mode you choose (`easy/expert/all`), you’ll be prompted for the following options.
Plone Version	A valid released version of Plone. Although we have run `paster` with the `plone3_buildout` template, we can enter Plone 4 version numbers. Don’t forget to choose 3.x versions for Python 2.4 and 4.x versions for Python 2.6.
Zope2 Install Path	If you want to share this instance Zope installation with another existing one, enter its path. If not, just leave it blank.
Plone Products Directory	Again, if you already have a previous installation with the list of Plone products you want to use, enter its path. If you want a fresh installation, leave it blank.
Initial Zope Username	The desired Zope administrator user.
Initial User Password	Choose one. Don’t leave it blank, as you won’t be able to log in.
HTTP Port	Pick a free port in your development machine.
Debug Mode	off
Verbose Security	off

A new folder named pox (the project name we used in the first option) with a basic directory structure and two very important files—bootstrap.py and buildout.cfg— will have been created.

In Step 2, we run the bootstrap process to complete the directory structure and generate the executable buildout file.

Let’s see what buildout.cfg looks like after Step 3, where we added PIL in the eggs parameter:

[buildout]
parts =
    zope2
    productdistros
    instance
    zopepy

This is a four-part buildout. Each part will be run consecutively.

extends = http://dist.plone.org/release/3.3.4/versions.cfg
versions = versions

Egg version numbers will be fixed (or pinned) to the ones listed in the URL above. Note that the URL is set according to the release number you have chosen when you ran the paster command before.

find-links =
    http://dist.plone.org/release/3.3.4
    http://dist.plone.org/thirdparty

Downloaded and installed eggs should be fetched from these package index servers.

# Add additional eggs here
eggs =
    PIL

# Reference any eggs you are developing here, one per line
# e.g.: develop = src/my.package
develop =

We will start using the eggs and develop parameters in the next chapter as we begin adding packages to our Zope instance. Meanwhile, we will need Python Imaging Library (PIL).

[zope2]
# For more information on this step and configuration options: 
# http://pypi.python.org/pypi/plone.recipe.zope2install
recipe = plone.recipe.zope2install
fake-zope-eggs = true
url = ${versions:zope2-url}

A recipe for Zope 2 installation:

[productdistros]
recipe = plone.recipe.distros
urls =
nested-packages =
version-suffix-packages =

A special recipe to download and install old-style Zope products (not released as eggs):

[instance]
recipe = plone.recipe.zope2instance
zope2-location = ${zope2:location}
user = admin:admin
http-address = 8080
#debug-mode = on
#verbose-security = on
eggs =
    Plone
    ${buildout:eggs}

# If you want to register ZCML slugs for any packages, 
# list them here.
# e.g. zcml = my.package my.other.package
zcml =

products =
    ${buildout:directory}/products
    ${productdistros:location}

These are several configuration settings for the Zope instance that will be created during the buildout process.

[zopepy]
recipe = zc.recipe.egg
eggs = ${instance:eggs}
interpreter = zopepy
extra-paths = ${zope2:location}/lib/python
scripts = zopepy

zopepy is a Python interpreter with a sys.path variable full of the downloaded eggs and packages available at the instance's /lib/python folder. This is particularly useful to check if every package is available as expected.

The last step will take longer to execute than the previous steps, as it will download all the eggs listed in the buildout.cfg file above and all their dependencies (at the time of writing, Plone 3.3.4 has 74 direct dependencies).

This buildout executes the four parts explicitly mentioned in the parts definition at the top of the file:

[zope2]: Its plone.recipe.zope2install recipe downloads and installs the Zope 2 version mentioned in ${versions:zope2-url}. You can find this parameter at http://dist.plone.org/release/3.3.4/versions.cfg, the URL of the extends parameter.
[productdistros]: It executes with its plone.recipe.distros recipe. In our example, we don’t have any urls listed, so it won’t process anything here.
Note
Note that there are very few old-style Zope products that are really worth installing in a modern instance. Being old-style means being unmaintained, so use them carefully.
[instance]: It uses a plone.recipe.zope2instance recipe to install a Zope instance. We can see here most of the options we set when we ran the paster command before.
[zopepy]: Using zc.recipe.egg will create a Python interpreter named zopepy with all the eggs found in the instance section (check ${instance:eggs}) in the sys.path variable.

Installing Plone on Windows

As with Linux and Mac, there is also a Windows unified installer (based on the buildout method described above) available, which provides the easiest way to install Plone in a Windows environment.

Download the latest Plone release from http://plone.org/download (3.3.4 at the time of writing) and run it.

This installation process is an easy four-step wizard that will guide you through:

A welcome screen, as shown in the screenshot.
The choice for the destination path for Plone (c:\Program Files\Plone, by default).
The configuration of the Zope instance administrator account (read: username and password).
A confirmation screen.

As a way of learning the buildout approach, which we introduced in the last two recipes, you are encouraged to go through the buildout.cfg file created in the chosen destination folder.

Although this method is really straightforward, if you plan to use several buildouts, Windows installer is unlikely to be the best solution, as it will reinstall the whole bundle, including the Python interpreter, every single time you create a new buildout.

As we have covered for Linux, we will see here the manual installation method to create a Zope instance on a Windows system.

How to do it…

Install the required Python version: If you are planning to create a Plone 4.x site, you will need Python 2.6. If not, Python 2.4 is required. Download the Windows Python installer from http://www.python.org/download/windows and run the installer.
By adding Python directory to the PATH environment variable, we can reuse the Python installation for other development buildouts. We are assuming here that you have installed Python 2.4 in the c:\Python24 folder; change the paths according to your directory choices.
- Go to the Windows Control Panel
- Open System options. You can get here by pressing the Windows logo key + Pause.
- Click on the Advanced tab in Windows XP or Advanced system settings in Windows Vista.
- Then click on the Environment variables button.
- Find the PATH variable and add c:\Python24;c:\Python24\Scripts.
Install the PyWin32 extension: We also need Python Win32 extensions. Download the correct file for your Python version at http://sourceforge.net/projects/pywin32/files and run the downloaded installer.
Install Python Imaging Library (PIL): download it from http://effbot.org/downloads. Again, pick the relevant installer for your Python version. At the time of writing, PIL-1.1.7.win32-py2.4.exe is the choice for Python 2.4.
Install a C compiler to build Zope: The easiest solution is to install MinGW, obtainable from http://sourceforge.net/projects/mingw/files/Automated%20MinGW%20Installer, and run the installer.
Note
We chose c:\MinGW as the installation folder. If you choose a different one, please adjust the next steps.
After the installation is finished, copy cc1.exe and collect2.exe from the c:\MinGW\libexec\gcc\mingw32\3.4.5 folder to c:\MinGW\bin.
Now add c:\MinGW\bin to the system PATH environment variable the same way we did with the Python PATH.
Fix the Python compiler problem: Given that the Python-installed version has been compiled on a different machine (we installed the binaries and they are usually compiled with Visual Studio), in order to prevent problems during other packages’ compilation, we must tell our environment to use the just-configured MinGW compiler.
To do this, create or update the distutils.cfg file in c:\Python24\Lib\distutils (adjust the path to your Python installation directory) with this content:
```
[build]
compiler=mingw32
```
Create a buildout with paster: As with Linux, we can use ZopeSkel templates to create new buildouts. If you have any doubt about the following commands, refer to the instructions in the Installing Plone on Linux section.
First download the EasySetup installation file from http://peak.telecommunity.com/dist/ez_setup.py and run
```
python ez_setup.py
```
Now you can use easy_install to install ZopeSkel, and then create the buildout:
```
easy_install ZopeSkel
paster create -t plone3_buildout
cd pox
python bootstrap.py
bin\buildout.exe
```

Creating a Plone site

We have no Plone site to play with yet (if you used the unified installer method, you should already have one though). A Plone site lives in the Zope Object Database (ZODB) and can be created by starting the instance and going through the Zope Management Interface (ZMI) (instructions for this a bit later). However, there is a better method to create a Plone site using the buildout automation process.

How to do it…

Edit buildout.cfg and add [plonesite] in the main parts parameter:

[buildout]
parts =
    zope2
    productdistros
    instance
    zopepy
    plonesite
...

And then add this new section at the bottom of the file:

[plonesite]
recipe = collective.recipe.plonesite
site-id = plone
instance = instance

Note

The new recipe, collective.recipe.plonesite, can be used to create or update Plone sites. We’ll learn more about it in the following chapters.

Now we’re ready to rebuild and start the instance.

./bin/buildout
./bin/instance fg

Finally, on browsing to http://localhost:8080/plone, you’ll see a Plone site.

How it works…

The new [plonesite] part makes the buildout process run the collective.recipe.plonesite recipe. With the correct parameters (site-id, instance, and some other ones that you might need), it will create or update a Plone site inside the Zope instance.

A particularly useful parameter is products, which automatically installs a list of products when buildout is run. We will use it in Opening an online Python shell on Plone using Clouseau.

For more information about this recipe and its options visit http://pypi.python.org/pypi/collective.recipe.plonesite.

There’s more…

As we said earlier, you can also create as many Plone sites as you need through the Web, that is to say, from the ZMI at the Zope root. This could be especially handy during development.

By going to http://localhost:8080/manage, you will be asked to authenticate yourself. Use the admin user you defined in the buildout.cfg file.

Depending on your Plone version, you will use different methods to create a Plone site:

Up to version 3.x of Plone, pick the Plone Site option from the combo-box at the top-right corner, and then click on the Add button (or just leave the combo-box). Then fill the short form and submit your changes. A new Plone site will be created with the ID you have specified.

With Plone 4.x, there is a new Add Plone Site button at the top-right corner, above the combo-box we have just mentioned.

As mentioned at the beginning of this chapter, we’ll incorporate more configuration options to our buildout.cfg as we create products in the project. So keep an eye open or just go to the Index of the book and look for “buildout” to go straight to them.