Getting Initial Skeleton Product Ready
Demonstrates some best practices of setting up the initial product.
Required Stack Components
The example built by this writing is designed to run on the following stack:
- Python >= 2.4.3
- Zope >= 2.9.3
- Plone >= 2.5
- Five >= 1.4
The example described in this writing may work on different versions but is untested by the author so your mileage may vary.
Some Things To Note Before Starting
We will begin by working with a product by the name of ploneexample.formlib. The finished code for this example can be browsed using the collective svn browser or checked out from Subversion using at the collective svn repository.
The first thing the keen Plone application developer will notice is the unusual naming convention of the product. Traditionally Plone products use CamelCase as the convention for naming products with no additional periods (ie PloneExampleFormlib). But as one of the goals of this writing, best practices will be demonstrated where we try to be as pythonic as possible which means using all lowercase for package names.
The Importance Of Pythonic
Many of you may be asking yourself, "but why do we really care about keeping this pythonic?" The single biggest reason for keeping things pythonic is to keep things as simple and easy to understand for people who are already familiar with Python. When developing standard Zope 2 products and placing them into the Products directory of your Zope 2 instance, Zope magically places them within the Products namespace package (ie so the full package path of CMFPlone actually becomes Products.CMFPlone). Living in PYTHONPATH like any other package and being reusable in general is A Good Thing TM.
Also, by keeping products pythonic, we can now use generic Python tools such as easy_install and setuptools (both great package management components) to work with these products.
Creating The Product
For the initial creation of the product we will use a small component of the Python Paste project. The rest of this writing will assume the reader has installed Phillip J. Eby's setuptools and easy_install products. As well as the necessary paster component along with the ZopeSkel template package. For instructions on how to setup paster and ZopeSkel, please see Daniel Nouri's excellent article on ZopeSkel.
So lets get started:
$ paster create -t plone ploneexample.formlib
Selected and implied templates:
ZopeSkel#plone_core A Plone Core project
Variables:
package: ploneexampleformlib
project: ploneexample.formlib
Creating template plone_core
Enter namespace_package (Namespace package) ['plone']: ploneexample
Enter package (The package contained namespace package (like i18n)) ['']: formlib
Enter pythonproducts (Are you making a productsless Zope 2 Product?) [False]: True
Enter version (Version) ['0.1']:
Enter description (One-line description of the package) ['']: A Plone product for demonstrating zope.formlib usage
Enter long_description (Multi-line description (in reST)) ['']:
Enter author (Author name) ['Plone Foundation']: Rocky Burt
Enter author_email (Author email) ['plone-developers@lists.sourceforge.net']: rocky@serverzen.com
Enter keywords (Space-separated keywords/tags) ['']:
Enter url (URL of homepage) ['http://svn.plone.org/svn/plone/plone.i18n']: http://dev.plone.org/collective/browser/examples/ploneexample.formlib
Enter license_name (License name) ['GPL']:
Enter zip_safe (True/False: if the package can be distributed as a .zip file) [False]:
Recursing into +namespace_package+
Creating ./ploneexample.formlib/ploneexample/
Recursing into +package+
Creating ./ploneexample.formlib/ploneexample/formlib/
Copying HISTORY.txt_tmpl to ./ploneexample.formlib/ploneexample/formlib/HISTORY.txt
Copying LICENSE.GPL to ./ploneexample.formlib/ploneexample/formlib/LICENSE.GPL
Copying LICENSE.txt_tmpl to ./ploneexample.formlib/ploneexample/formlib/LICENSE.txt
Copying README.txt_tmpl to ./ploneexample.formlib/ploneexample/formlib/README.txt
Copying __init__.py_tmpl to ./ploneexample.formlib/ploneexample/formlib/__init__.py
Copying configure.zcml to ./ploneexample.formlib/ploneexample/formlib/configure.zcml
Copying version.txt_tmpl to ./ploneexample.formlib/ploneexample/formlib/version.txt
Copying __init__.py_tmpl to ./ploneexample.formlib/ploneexample/__init__.py
Copying setup.cfg to ./ploneexample.formlib/setup.cfg
Copying setup.py_tmpl to ./ploneexample.formlib/setup.py
Running /usr/bin/python2.4 setup.py egg_info
Setting Up Development
After this has completed running you should now have a ploneexample.formlib directory in your current working directory. For purposes of development we will now use setuptools to setup the ploneexample.formlib project on the PYTHONPATH in order to make it available to Zope. So make sure you make the ploneexample.formlib directory your current directory and do the following (remember to run this with sudo if you're in a UNIX environment and don't have permission to write to the system python site-packages directory):
$ python2.4 setup.py develop
This will yield some output similar to the following:
[snip output...] Installed /home/rocky/Documents/developing/projects/ploneexample.formlib Processing dependencies for ploneexample.formlib==0.1dev
Hooking Up The New Product Into Zope 2
Now that we have a fully runnable Zope 2 product we will proceed with hooking this up to an existing Zope 2 instance. Until Zope and CMF/Plone catch up (Zope 2.10 already includes the necessary changes) we will need to use the pythonproducts product to enable Zope 2 products to exist outside of the instance Products directory.
So be sure to download and install the pythonproducts product into your Zope 2 instance by following the install instructions provided by pythonproducts. For those in a hurry, setting up pythonproducts is as simple as downloading the pythonproducts tarball, extracting the contents into some temporary directory, and running pythonsetup.pyinstall--home$INSTANCE_HOME.
Now you need to tell your Zope 2 instance to "activate" the new ploneexample.formlib package as a Zope 2 product. You do this by going to the etc/package-includes directory in your Zope 2 instance and create a new file there called ploneexample.formlib-configure.zcml with its only contents being:
<include package="ploneexample.formlib" />
You should now test your Zope 2 instance to confirm that the new ploneexample.formlib product is available. You can do this by starting your Zope 2 instance as you normally would and going to the Products section of the Control Panel via the ZMI. Towards the bottom of the list you should see:
ploneexample.formlib (Installed product ploneexample.formlib)
Visit our