Prerequisites¶

Setting up a Dexterity project

Preparing a development environment¶

First, get a working Plone installation. If you don't already have one, the easiest way to do so is to use one of Plone's installers. Note that for development purposes, you may use a standalone (non-ZEO), non-root install.

Second, add our standard development tools. If you've used one of our installers, developer tool configurations are in a separate file, develop.cfg. Once your site is running, you may activate the development configuration by using the command:

bin/buildout -c develop.cfg

rather than simply running bin/buildout. The develop.cfg config file extends the existing buildout.cfg.

If you've created yor own buildout.cfg file rather than using one of the installers, you'll need to add an equivalent development configuration. The easiest way to do so is to pick up a copy from the Unified Installer's github repository.

The key tools that you'll need, both supplied by develop.cfg, are:

A ZopeSkel configuration to supply a package skeleton builder; and
A test runner.

Note

If you are using Plone earlier than 4.3, you'll need to add zopeskel.dexterity to the eggs list for the zopeskel part. This supplies the Dexterity skeleton.

Creating a package¶

Setting up a package to house your content types

Note

We're going to build a package named example.conference. You may find a completed version of it in the Collective repository.

Typically, our content types will live in a separate package to our theme and other customisations.

To create a new package, we can start with ZopeSkel and the dexterity template.

Note

Nothing that we're doing actually requires ZopeSkel or the zopeskel.dexterity skeleton package. It's just a quick way of getting started.

We run the following from the src/ directory

$ ../bin/zopeskel dexterity example.conference

You may accept all the default suggestions. This will create a directory named example.conference inside ./src.

Now, take a look at the setup.py file in your new package. Edit the author, author_email and description fields as you wish. Note a couple of parts of the generated setup.py file:

                        install_requires=[
    ...
    'plone.app.dexterity [grok]',
    ...
],
...
entry_points="""
# -*- Entry points: -*-
[z3c.autoinclude.plugin]
target = plone
""",

                      

The addition of plone.app.dexterity [grok] to our install requirements assures that we'll have dexterity loaded with the grok extra. Our example code won't work without it. The specification of plone as a z3c.autoinclude.plugin entry point ensures that we won't need to separately specify our zcml in buildout.

Now, let's take a look at configure.zcml in the examples/conference directory of our project. Again, we want to note a few parts:

                        <configure ...>

  <includeDependencies package="." />

  <grok:grok package="." />

  <browser:resourceDirectory
    name="example.conference"
    directory="resources" />

  <genericsetup:registerProfile
      name="default"
      title="Example Dexterity Product"
      directory="profiles/default"
      description="Extension profile for Example Dexterity Product"
      provides="Products.GenericSetup.interfaces.EXTENSION"
      />

</configure>

                      

Here, with the includeDependencies tag we automatically include the ZCML configuration for all packages listed under install_requires in setup.py. 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.

The browser.resourceDirectory command creates a directory for static resources that we want to make available through the web.

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

When you've got your project tuned up, return to your buildout/instance directory and edit buildout.cfg to add example.conference to your eggs list and src/example.conference to your develop sources list:

                        eggs =
    Plone
    ...
    example.conference

...
develop =
    ...
    src/example.conference

                      

Run bin/buildout -c develop.cfg to add your new product to the configuration. (Or, just bin/buildout if you don't have a separate develop.cfg.)

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

We are now ready to start adding types.