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 |
---|---|
A file containing Python definitions and statements. | |
A set of Python modules. | |
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. | |
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. | |
A Python package, used by | |
The set of Python packages, templates, and other files needed to execute a Zope server. | |
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.
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.
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
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 thezc.recipe.cmmi
recipe, which downloads Python source code and compiles it. Thecmmi
suffix stands for Compile Make and Make Install.The
[virtualenv]
part uses thezc.recipe.egg
recipe, which installs the virtualenv Python egg and creates the executablebin/virtualenv
file.The
[make-virtualenv]
part uses theiw.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.
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
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.
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.
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
Create a buildout with
paster
: Once you have the correctZopeSkel
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 withpaster
, you will see a warning message informing you that Unified Installer is the best option for installations andpaster
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 theeggs
parameter in the main[buildout]
section and addPIL
(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
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 |
---|---|
pox, after Plone and OpenX, the fictitious project we are tackling in this book. Here you can choose whatever name you want and | |
With the | |
A valid released version of Plone. Although we have run | |
If you want to share this instance Zope installation with another existing one, enter its path. If not, just leave it blank. | |
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. | |
The desired Zope administrator user. | |
Choose one. Don’t leave it blank, as you won’t be able to log in. | |
Pick a free port in your development machine. | |
off | |
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]
: Itsplone.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 theextends
parameter.[productdistros]
: It executes with itsplone.recipe.distros
recipe. In our example, we don’t have anyurls
listed, so it won’t process anything here.[instance]
: It uses aplone.recipe.zope2instance
recipe to install a Zope instance. We can see here most of the options we set when we ran thepaster
command before.[zopepy]
: Usingzc.recipe.egg
will create a Pythoninterpreter
namedzopepy
with all theeggs
found in theinstance
section (check${instance:eggs}
) in thesys.path
variable.
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.
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 thec:\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 addc:\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
andcollect2.exe
from thec:\MinGW\libexec\gcc\mingw32\3.4.5
folder toc:\MinGW\bin
.Now add
c:\MinGW\bin
to the systemPATH
environment variable the same way we did with the PythonPATH
.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 inc:\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 installZopeSkel
, and then create the buildout:easy_install ZopeSkel paster create -t plone3_buildout cd pox python bootstrap.py bin\buildout.exe
Developing without a Version Control System (VCS) is strongly discouraged: you may not want to use VCS while simply following the recipes in this book. However, any project, large or small, should use a VCS wherever possible. In the next chapter, we will start developing a package, so we’ll adjust our buildout with a handy extension to support the development of products: mr.developer.
Edit buildout.cfg
and add the following lines:
[buildout]
...
extensions = mr.developer
sources = sources
[sources]
# repository information here
# format <name> = <kind> <url>
# my.package = svn http://example.com/svn/my.package/trunk
By adding the mr.developer
extension, we can define a new [sources]
section with settings to automatically checkout our projects—at buildout time—from whatever version control system we use. This will facilitate the repetitive task of updating every package we develop.
Supported kinds of repositories are:
svn, for subversion: http://subversion.tigris.org/
hg, for mercurial: http://mercurial.selenic.com/wiki/
git, at http://git-scm.com/./
More information about mr.developer
is available at http://pypi.python.org/pypi/mr.developer.
If you are interested in any of the above VCS, read more about them at:
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.
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.
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.
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.