Creating a package

Typically, our content types will live in a separate package to our theme and other customisations. In the previous section, we showed how our buildout refers to a package in the src/ directory, either placed there manually or checked out by mr.developer, called example.conference. You can find the latest version of this package in the Collective repository.

To create a new package, we can start with ZopeSkel and the plone template. See this how-to for more information on how to install ZopeSkel.

We run the following from the src/ directory:

$ paster create -t plone example.conference

If you are using this template, make sure that you specify a namespace (example) and package name (conference) that matches the egg name (example.conference) on the command line. Answer False when asked to create a Zope 2 product, and False again when asked if the product is zip-safe.

Next, we will normalise the code created by paster, mainly by removing things we don't need.

First, we edit setup.py to add plone.app.dexterity as a dependency and specify the package as a z3c.autoinclude plug-in. This ensures that we do not need to load its ZCML separately once the package is configured in buildout.cfg (this feature is enabled in Plone 3.3 and later). We will also add a dependency on collective.autopermission, which will help us define custom permissions later. 

We can remove the paster plugin entry point and paster_plugins line. We will not need these.

from setuptools import setup, find_packages
import os

version = '1.0a1'

setup(name='example.conference',
      version=version,
      description="Example accompanying http://plone.org/products/dexterity/documentation/manual/developers-manual/",
      long_description=open("README.txt").read() + "\n" +
                       open(os.path.join("docs", "HISTORY.txt")).read(),
      # Get more strings from http://www.python.org/pypi?%3Aaction=list_classifiers
      classifiers=[
        "Framework :: Plone",
        "Programming Language :: Python",
        "Topic :: Software Development :: Libraries :: Python Modules",
        ],
      keywords='plone dexterity example',
      author='Martin Aspeli',
      author_email='optilude@gmail.com',
      url='http://plone.org/products/dexterity',
      license='GPL',
      packages=find_packages(exclude=['ez_setup']),
      namespace_packages=['example'],
      include_package_data=True,
      zip_safe=False,
      install_requires=[
          'setuptools',
          'Plone',
          'plone.app.dexterity',
          'collective.autopermission',
      ],
      entry_points="""
      [z3c.autoinclude.plugin]
      target = plone
      """,
      )

Next, we edit configure.zcml and add the following:

<configure
    xmlns="http://namespaces.zope.org/zope"
    xmlns:grok="http://namespaces.zope.org/grok"
    xmlns:genericsetup="http://namespaces.zope.org/genericsetup"
    i18n_domain="example.conference">

    <!-- Include configuration for dependencies listed in setup.py -->
    <includeDependencies package="." />

    <!-- Grok the package to initialise schema interfaces and content classes -->
    <grok:grok package="." />

    <!-- Register an extension profile to make the product installable -->
    <genericsetup:registerProfile
        name="default"
        title="Conference management"
        description="A Dexterity demo"
        directory="profiles/default"
        provides="Products.GenericSetup.interfaces.EXTENSION"
        />
        
</configure>

Here, we first automatically include the ZCML configuration for all packages listed under install_requires in setup.py. This feature is part of z3c.autoinclude, which is included with Plone 3.3 and later. The alternative would be to manually add a line like <include package="plone.app.dexterity" /> for each dependency.

Next, we grok the package to construct and register schemata, views, forms and so on based on conventions used in the various files we will add throughout this tutorial.

Finally, we register a GenericSetup profile to make the type installable, which we will build up over the next several sections.

The profile requires a directory profiles/default. You should create the profiles directory in the same folder as configure.zcml, and default under that. In default, add a file called metadata.xml with the following contents:

<metadata>
    <version>1</version>
    <dependencies>
        <dependency>profile-plone.app.dexterity:default</dependency>
    </dependencies>
</metadata>

This gives the profile a version number (which is different to the package version set in setup.py) in case we need to define upgrade steps in the future, and declares that plone.app.dexterity should be installed when this package is installed. We can add other profiles to depend on in the same way if you need to.

With this in place, we should be able to go up to the buildout root and run:

$ python2.4 bootstrap.py
$ ./bin/buildout

The buildout should now configure Plone, Dexterity and the example.conference package.

We are now ready to start adding types.