ZopeSkel Archetypes HOWTO

So you want a quick overview of what ZopeSkel can do for you, as a Plone developer? Look no further. This document will get you up and running.

This was originally posted as part of the 2008 DC Plone Sprint page on Open Plans.

All of these instructions work very well inside of a virtualenv environment.

I’ve got separate instructions for Windows Wubbers and Linux Lusers:

Choose your OS

Unix (tested in Ubuntu, should work across Unixes)
Windows (tested in XP, should work in Vista)

Getting Started (Unix)

Dev Environment

This is Ubuntu-specific. The basic idea here is you need the build tools, subversion, python 2.4.x, and the python dev packages so you can run buildout and compile Zope.

$ sudo aptitude install build-essential python-dev python2.4 python2.4-dev subversion

Easy Install (setuptools)

If you don’t already have easy_install installed, you’ll need to do this before you can start using ZopeSkel.

$ cd /tmp
$ wget http://pypi.python.org/packages/2.4/s/setuptools/setuptools-0.6c9-py2.4.egg#md5=260a2be2e5388d66bdaee06abec6342a
$ sudo sh setuptools-0.6c9-py2.4.egg

This is different than the way I used to do it, via ez_setup.py. see http://pypi.python.org/pypi/setuptools/

ZopeSkel

$ sudo easy_install -U ZopeSkel
- or -
[ from trunk ]
$ cd ~
$ svn co http://svn.plone.org/svn/collective/ZopeSkel/trunk ZopeSkel-dev
$ cd ZopeSkel-dev
$ sudo python2.4 setup.py develop

Check for ZopeSkel

This is how you know ZopeSkel has been installed. This also shows you the currently available templates.

$ paster create --list-templates
Available templates:
  archetype:          A Plone project that uses Archetypes
  basic_namespace:    A project with a namespace package
  basic_package:      A basic setuptools-enabled package
  basic_zope:         A Zope project
  kss_plugin:         A KSS plugin template
  nested_namespace:   A project with two nested namespaces.
  paste_deploy:       A web application deployed through paste.deploy
  plone:              A Plone project
  plone2.5_buildout:  A buildout for Plone 2.5 projects
  plone2.5_theme:     A Theme for Plone 2.5
  plone2_theme:       A Theme Product for Plone 2.1 & Plone 2.5
  plone3_buildout:    A buildout for Plone 3 projects
  plone3_portlet:     A Plone 3 portlet
  plone3_theme:       A Theme for Plone 3.0
  plone_app:          A Plone App project
  plone_hosting:      Plone hosting: buildout with ZEO and any Plone version
  plone_pas:          A Plone PAS project
  recipe:             A recipe project for zc.buildout
  silva_buildout:     A buildout for Silva projects

Buildout Skeleton

We’ll start actually using ZopeSkel here to get a buildout skeleton in place. We’ll then create an archetypes-based product and install it into the buildout.

$ paster create -t plone3_buildout mybuildout
Selected and implied templates:
  ZopeSkel#plone3_buildout  A buildout for Plone 3 projects

Variables:
  egg:      mybuildout
  package:  mybuildout
  project:  mybuildout
Enter zope2_install (Path to Zope 2 installation; leave blank to fetch one) ['']:
Enter plone_products_install (Path to directory containing Plone products; leave blank to fetch one) ['']:
Enter zope_user (Zope root admin user) ['admin']:
Enter zope_password (Zope root admin password) ['']: admin
Enter http_port (HTTP port) [8080]:
Enter debug_mode (Should debug mode be "on" or "off"?) ['off']: on
Enter verbose_security (Should verbose security be "on" or "off"?) ['off']: on

Archetypes Product

This will create a python egg structure with the usual directories, generic setup, etc.

$ cd mybuildout/src
$ paster create -t archetype my.product
Selected and implied templates:
  ZopeSkel#basic_namespace  A project with a namespace package
  ZopeSkel#plone            A Plone project
  ZopeSkel#archetype        A Plone project that uses Archetypes

Variables:
  egg:      my.product
  package:  myproduct
  project:  my.product
Enter title (The title of the project) ['Plone Example']: My Product
Enter namespace_package (Namespace package (like plone)) ['plone']: my
Enter package (The package contained namespace package (like example)) ['example']: product
Enter zope2product (Are you creating a Zope 2 Product?) [True]:
Enter version (Version) ['1.0']:
Enter description (One-line description of the package) ['']:
Enter long_description (Multi-line description (in reST)) ['']:
Enter author (Author name) ['Plone Foundation']:

Enter author_email (Author email) ['plone-developers@lists.sourceforge.net']:
Enter keywords (Space-separated keywords/tags) ['']:
Enter url (URL of homepage) ['http://svn.plone.org/svn/plone/plone.example']:
Enter license_name (License name) ['GPL']:
Enter zip_safe (True/False: if the package can be distributed as a .zip file) [False]:

Wire Up Product To Plone

For more information about what we’re doing here, see the zc.buildout pypi page.

The gist is that we’re telling the plone buildout about the archetypes egg that we just created above.

$ cd ../
$ vi buildout.cfg

Make changes:
[buildout]
...
develop =
    *src/my.product*
...
[instance]
eggs =
    ${buildout:eggs}
    ${plone:eggs}
    *my.product*
...
zcml =
    my.product

Save and exit.

Check for Local Commands

ZopeSkel implements a paster concept called “local commands”. Local commands allow you to tack on extra functionality to your templates, and only make that functionality avaiable when you’re in the context of the template.

ZopeSkel uses this concept to allow you to add all sorts of goodies to your archetype-based product, including content types, zope 3 browser views, portlets, viewlets, and more.

$ cd src/my.product
$ paster help
Usage: paster [paster_options] COMMAND [command_options]

Options:
  --version         show program's version number and exit
  --plugin=PLUGINS  Add a plugin to the list of commands (plugins are Egg
                    specs; will also require() the Egg)
  -h, --help        Show this help message

Commands:
  create       Create the file layout for a Python distribution
  help         Display help
  make-config  Install a package and create a fresh config file/directory
  points       Show information about entry points
  post         Run a request for the described application
  request      Run a request for the described application
  serve        Serve the described application
  setup-app    Setup an application, given a config file

ZopeSkel local commands:
  addcontent   Adds plone content types to your project

$ paster addcontent --list
Available templates:
    atschema:     A handy AT schema builder
    contenttype:  A content type skeleton
    portlet:      A Plone 3 portlet
    view:         A browser view skeleton
    zcmlmeta:     A ZCML meta directive skeleton

Content Type(s)

Now we’ll add some content types. The answers to the questions that ZopeSkel prompts you with are slightly different when you’re creating a folderish (container) type, compared to creating a non-folderish type.

If you want your container to restrict what types it can contain, you need to do that via the generic setup profile.

Container

$ paster addcontent contenttype
Enter contenttype_name (Content type name ) ['Example Type']: Date Book
Enter contenttype_description (Content type description ) ['Description of the Example Type']: A Simple Date Book
Enter folderish (True/False: Content type is Folderish ) [False]: True
Enter global_allow (True/False: Globally addable ) [True]:
Enter allow_discussion (True/False: Allow discussion ) [False]:

Non-Container

$ paster addcontent contenttype
Enter contenttype_name (Content type name ) ['Example Type']: Entry
Enter contenttype_description (Content type description ) ['Description of the Example Type']: A Date Book Entry
Enter folderish (True/False: Content type is Folderish ) [False]:
Enter global_allow (True/False: Globally addable ) [True]: False
Enter allow_discussion (True/False: Allow discussion ) [False]:

Repeat for each content type in your product.

Archetypes Schema

The paster addcontent local command was extended with a template called atschema. It’s purpose is to create the boilerplate code
you need to define the form fields (schema) for your content types.

$ paster addcontent atschema
Welcome to the ATSchema Builder. Field names/widgets can be specified in lowercase or upper case.
NOTE: No need to add 'widget' or 'field' to the names. atschema does the work for you!
See
    http://plone.org/documentation/manual/archetypes-developer-manual/fields/fields-reference/

and
    http://plone.org/documentation/manual/archetypes-developer-manual/fields/widgets-reference
for field and widget details
Enter content_class_filename (What is the module (file)name of your content class?) ['exampletype']: datebook
Enter field_name (What would you like to name this field?) ['newfield']: year
Enter field_type (What kind of field should I make for you?
Some examples: [boolean,computed,cmfobject,datetime,file,fixedpoint,float,image,integer,lines,reference,string,text]) ['string']: integer
Enter widget_type (What kind of widget do you want to use?) ['default']:
Enter field_label (What should be the label of this field (title)?) ['New Field']: Date Book Year
Enter field_desc (What should be the description of this field (help text)?) ['Field description']: Limit this date book to one specific year
Enter required (Is this field required?) ['False']:
Enter default (If you'd like a default type it here, otherwise leave it blank) ['']:

Repeat for each field in each of your content types. Title and Description are already included.

Bootstrap/Buildout

Now we’re ready to actually run the new code that we just generated. First we need to bootstrap the buildout and run the buildout script.

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

Start Zope

$ ./bin/instance fg

Eyeball Test

Open http://localhost:8080 in a browser. You should see the Zope welcome page
Click the Zope Management Interface link, enter admin/admin for username/password
Select “Plone Site” from the dropdown on the right.
Enter a useful id (plone). The rest of the fields don’t matter right now.
Click “Add Plone Site” button
Watch console for any errors during plone site setup
Click on the link to “plone (Site)”
Click on “portal_quickinstaller”
Check the box next to “My Product”
Click “Install”
Watch the console for errors
You should see “My Product” under “Installed Products”
Open http://localhost:8080/plone (it usually takes some time to load first time round)
Click the “Add New” link.
Look for Date Book in the list
Click on Date Book in the list
Fill out the form. We’ll use “My Date Book” for the title, “A Date Book” for the description, and 2008 for the year
Click save button

Getting Started (Windows)

Set up environment

Details (and download links) are located at http://plone.org/documentation/hot-to/using-buildout-on-windows.
We’re just following it up to the “Get your buildout” section.

Install python 2.4
Install PIL
Add C:\Python24\bin and C:\Python24\Scripts directories to your PATH variable
Install subversion
Install MinGW
Copy cc1.exe and collect2.exe from C:\MinGW\libexec\gcc\mingw32\3.4.5 to C:\MinGW\bin
Add C:\MinGW\bin to your PATH
Add the following to C:\Python24\Lib\distutils (you will probably have to create the file):
```
[build]
compiler=mingw32
```

Install setuptools (easy_install)

Download and install the python 2.4 setuptools .exe from pypi: http://pypi.python.org/pypi/setuptools/

Install ZopeSkel

Open a command prompt (hit Windows-r or go to Start -> Run)

C:\>easy_install -U ZopeSkel
- or -
[ from trunk ]
C:\>mkdir zopeskel
C:\>cd zopeskel
C:\zopeskel> svn co http://svn.plone.org/svn/collective/ZopeSkel/trunk ZopeSkel-dev
C:\zopeskel> cd ZopeSkel-dev
C:\zopeskel\ZopeSkel-dev> python setup.py develop
C:\zopeskel\ZopeSkel-dev> cd ..\

Check for ZopeSkel

This is how you know ZopeSkel has been installed. This also shows you the currently available templates.

C:\zopeskel> paster create --list-templates
Available templates:
  archetype:          A Plone project that uses Archetypes
  basic_namespace:    A project with a namespace package
  basic_package:      A basic setuptools-enabled package
  basic_zope:         A Zope project
  kss_plugin:         A KSS plugin template
  nested_namespace:   A project with two nested namespaces.
  paste_deploy:       A web application deployed through paste.deploy
  plone:              A Plone project
  plone2.5_buildout:  A buildout for Plone 2.5 projects
  plone2.5_theme:     A Theme for Plone 2.5
  plone2_theme:       A Theme Product for Plone 2.1 & Plone 2.5
  plone3_buildout:    A buildout for Plone 3 projects
  plone3_portlet:     A Plone 3 portlet
  plone3_theme:       A Theme for Plone 3.0
  plone_app:          A Plone App project
  plone_hosting:      Plone hosting: buildout with ZEO and any Plone version
  plone_pas:          A Plone PAS project
  recipe:             A recipe project for zc.buildout
  silva_buildout:     A buildout for Silva projects

Buildout Skeleton

We’ll start actually using ZopeSkel here to get a buildout skeleton in place. We’ll then create an archetypes-based product and install it into the buildout.

C:\zopeskel> paster create -t plone3_buildout mybuildout
Selected and implied templates:
  ZopeSkel#plone3_buildout  A buildout for Plone 3 projects

Variables:
  egg:      mybuildout
  package:  mybuildout
  project:  mybuildout
Enter zope2_install (Path to Zope 2 installation; leave blank to fetch one) ['']:
Enter plone_products_install (Path to directory containing Plone products; leave blank to fetch one) ['']:
Enter zope_user (Zope root admin user) ['admin']:
Enter zope_password (Zope root admin password) ['']: admin
Enter http_port (HTTP port) [8080]:
Enter debug_mode (Should debug mode be "on" or "off"?) ['off']: on
Enter verbose_security (Should verbose security be "on" or "off"?) ['off']: on

Archetypes Product

This will create a python egg structure with the usual directories, generic setup, etc.

C:\zopeskel> cd mybuildout\src
C:\zopeskel\mybuildout\src> paster create -t archetype my.product
Selected and implied templates:
  ZopeSkel#basic_namespace  A project with a namespace package
  ZopeSkel#plone            A Plone project
  ZopeSkel#archetype        A Plone project that uses Archetypes

Variables:
  egg:      my.product
  package:  myproduct
  project:  my.product
Enter title (The title of the project) ['Plone Example']: My Product
Enter namespace_package (Namespace package (like plone)) ['plone']: my
Enter package (The package contained namespace package (like example)) ['example']: product
Enter zope2product (Are you creating a Zope 2 Product?) [True]:
Enter version (Version) ['1.0']:
Enter description (One-line description of the package) ['']:
Enter long_description (Multi-line description (in reST)) ['']:
Enter author (Author name) ['Plone Foundation']:
Enter author_email (Author email) ['plone-developers@lists.sourceforge.net']:
Enter keywords (Space-separated keywords/tags) ['']:
Enter url (URL of homepage) ['http://svn.plone.org/svn/plone/plone.example']:
Enter license_name (License name) ['GPL']:
Enter zip_safe (True/False: if the package can be distributed as a .zip file) [False]:

Wire Up Product To Plone

For more information about what we’re doing here, see the zc.buildout pypi page.

The gist is that we’re telling the plone buildout about the archetypes egg that we just created above.

C:\zopeskel\mybuildout\src> cd ..\
C:\zopeskel\mybuildout> write buildout.cfg

Make changes:

[buildout]
...
develop =
    *src/my.product*
...
[instance]
eggs =
    ${buildout:eggs}
    ${plone:eggs}
    *my.product*
...
zcml =
    my.product

Save and exit.

Check for Local Commands

ZopeSkel uses this concept to allow you to add all sorts of goodies to your archetype-based product, including content types, zope 3 browser views, portlets, viewlets, and more.

C:\zopeskel\mybuildout> cd src\my.product
C:\zopeskel\mybuildout\src\my.product> paster help
Usage: paster [paster_options] COMMAND [command_options]

Options:
  --version         show program's version number and exit
  --plugin=PLUGINS  Add a plugin to the list of commands (plugins are Egg
                    specs; will also require() the Egg)
  -h, --help        Show this help message

Commands:
  create       Create the file layout for a Python distribution
  help         Display help
  make-config  Install a package and create a fresh config file/directory
  points       Show information about entry points
  post         Run a request for the described application
  request      Run a request for the described application
  serve        Serve the described application
  setup-app    Setup an application, given a config file

ZopeSkel local commands:
  addcontent   Adds plone content types to your project

C:\zopeskel\mybuildout\src\my.product> paster addcontent --list
Available templates:
    atschema:     A handy AT schema builder
    contenttype:  A content type skeleton
    portlet:      A Plone 3 portlet
    view:         A browser view skeleton
    zcmlmeta:     A ZCML meta directive skeleton

Content Type(s)

If you want your container to restrict what types it can contain, you need to do that via the generic setup profile.

Container

C:\zopeskel\mybuildout\src\my.product> paster addcontent contenttype
Enter contenttype_name (Content type name ) ['Example Type']: Date Book
Enter contenttype_description (Content type description ) ['Description of the Example Type']: A Simple Date Book
Enter folderish (True/False: Content type is Folderish ) [False]: True
Enter global_allow (True/False: Globally addable ) [True]:
Enter allow_discussion (True/False: Allow discussion ) [False]:

Non-Container

C:\zopeskel\mybuildout\src\my.product> paster addcontent contenttype
Enter contenttype_name (Content type name ) ['Example Type']: Entry
Enter contenttype_description (Content type description ) ['Description of the Example Type']: A Date Book Entry
Enter folderish (True/False: Content type is Folderish ) [False]:
Enter global_allow (True/False: Globally addable ) [True]: False
Enter allow_discussion (True/False: Allow discussion ) [False]:

Repeat for each content type in your product.

Archetypes Schema

The paster addcontent local command was extended with a template called atschema. It’s purpose is to create the boilerplate code
you need to define the form fields (schema) for your content types.

C:\zopeskel\mybuildout\src\my.product> paster addcontent atschema
Welcome to the ATSchema Builder. Field names/widgets can be specified in lowercase or upper case.
NOTE: No need to add 'widget' or 'field' to the names. atschema does the work for you!
See
    http://plone.org/documentation/manual/archetypes-developer-manual/fields/fields-reference/
and
    http://plone.org/documentation/manual/archetypes-developer-manual/fields/widgets-reference
for field and widget details
Enter content_class_filename (What is the module (file)name of your content class?) ['exampletype']: datebook

Enter field_name (What would you like to name this field?) ['newfield']: year
Enter field_type (What kind of field should I make for you?
Some examples: [boolean,computed,cmfobject,datetime,file,fixedpoint,float,image,integer,lines,reference,string,text]) ['string']: integer
Enter widget_type (What kind of widget do you want to use?) ['default']:
Enter field_label (What should be the label of this field (title)?) ['New Field']: Date Book Year
Enter field_desc (What should be the description of this field (help text)?) ['Field description']: Limit this date book to one specific year
Enter required (Is this field required?) ['False']:
Enter default (If you'd like a default type it here, otherwise leave it blank) ['']:

Repeat for each field in each of your content types. Title and Description are already included.

Bootstrap/Buildout

Now we’re ready to actually run the new code that we just generated. First we need to bootstrap the buildout and run the buildout script.

C:\zopeskel\mybuildout\src\my.product> cd ..\..\
C:\zopeskel\mybuildout> python bootstrap.py
C:\zopeskel\mybuildout> .\bin\buildout

Start Zope

C:\zopeskel\mybuildout> .\bin\instance fg

You may get asked to unblock the port, say yes :)

Eyeball Test

Open http://localhost:8080 in a browser. You should see the Zope welcome page
Click the Zope Management Interface link, enter admin/admin for username/password
Select “Plone Site” from the dropdown on the right.
Enter a useful id (plone). The rest of the fields don’t matter right now.
Click “Add Plone Site” button
Watch console for any errors during plone site setup
Click on the link to “plone (Site)”
Click on “portal_quickinstaller”
Check the box next to “My Product”
Click “Install”
Watch the console for errors
You should see “My Product” under “Installed Products”
Open http://localhost:8080/plone (it usually takes some time to load first time round)
Click the “Add New” link.
Look for Date Book in the list
Click on Date Book in the list
Fill out the form. We’ll use “My Date Book” for the title, “A Date Book” for the description, and 2008 for the year
Click save button

1 Comment

Plone Conference 2008: ZopeSkel Sprint Reportout « jjmojojjmojo: In Effect
December 9, 2008 at 3:51 pm

[...] ZopeSkel Archetypes HOWTO [...]

Reply

jjmojojjmojo: In Effect

ZopeSkel Archetypes HOWTO

Choose your OS

Getting Started (Unix)

Dev Environment

Easy Install (setuptools)

ZopeSkel

Check for ZopeSkel

Buildout Skeleton

Archetypes Product

Wire Up Product To Plone

Check for Local Commands

Content Type(s)

Container

Non-Container

Archetypes Schema

Bootstrap/Buildout

Start Zope

Eyeball Test

Getting Started (Windows)

Set up environment

Install setuptools (easy_install)

Install ZopeSkel

Check for ZopeSkel

Buildout Skeleton

Archetypes Product

Wire Up Product To Plone

Check for Local Commands

Content Type(s)

Container

Non-Container

Archetypes Schema

Bootstrap/Buildout

Start Zope

Eyeball Test

1 Comment

Leave a Reply

Pages

Recent Posts

Meta