Plone3 Project Walkthrough

The Project Buildout

On the SixFeetUp server

Set up a trac project and associated subversion repository

sudo trac_svn_project casaproject
Password:
building svn project for casaproject ...
building trac project for casaproject ...
Creating and Initializing Project
 Installing default wiki pages
 /usr/local/share/trac/wiki-default/CamelCase => CamelCase
 /usr/local/share/trac/wiki-default/InterMapTxt => InterMapTxt
 /usr/local/share/trac/wiki-default/InterTrac => InterTrac
 /usr/local/share/trac/wiki-default/InterWiki => InterWiki
...
...
...

Edit the [project] section of the configuration file just created for your project

sudo emacs /var/trac/casaproject/conf/trac.ini

You can just change the 'descr' and 'name' attributes:

[project]
descr = Project for Washington CASA
# icon = <set in global trac.ini>
name = casaproject

Your project will now be visible in the list of projects at http://trac.npowerseattle.org/

On your local machine

Run paster to create a new buildout, which you will be able to use whenever your or someone else needs to work on this particular project:

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

Variables:
  egg:      casaproject
  package:  casaproject
  project:  casaproject
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
...
...
...

Before making any changes to the new buildout, we'll want to check the new structure into subversion. However, we don't want the var/ directory included, so just delete that for now:

$ cd casaproject/
$ ls
README.txt      bootstrap.py    buildout.cfg    products        src	var
$ rm -rf var

Everything that's left can be checked into a new directory in subversion called 'builldouts':

$ svn import . svn+ssh://svn.npowerseattle.org/var/svn/casaproject/buildouts/main -m "initial import" 
Password: 
Password: 
Password: 
Adding         products
Adding         products/README.txt
Adding         bootstrap.py
Adding         buildout.cfg
Adding         src
Adding         src/README.txt
Adding         README.txt

Now you delete the existing buildout and check out a working copy:

$ svn co svn+ssh://svn.npowerseattle.org/var/svn/casaproject/buildouts/main casaproject
Password: 
Password: 
A    casaproject/products
A    casaproject/products/README.txt
A    casaproject/bootstrap.py
A    casaproject/buildout.cfg
A    casaproject/src
A    casaproject/src/README.txt
A    casaproject/README.txt
Checked out revision 1.

Make required changes to your buildout.cfg, then run bootstrap.py and bin/buildout:

$ mate buildout.cfg 
$ python2.4 bootstrap.py 
Creating directory '/Users/jesses/zope2/casaproject/bin'.
Creating directory '/Users/jesses/zope2/casaproject/parts'.
Creating directory '/Users/jesses/zope2/casaproject/develop-eggs'.
Generated script '/Users/jesses/zope2/casaproject/bin/buildout'.
$ bin/buildout -v
Installing 'plone.recipe.plone'.
Picked: plone.recipe.plone = 3.0.6
Getting required 'plone.recipe.distros'
  required by plone.recipe.plone 3.0.6.
...
...
...

You may want to tell subversion to ignore the things it shouldn't be concerned with using the 'svn ignore' property:

$ svn propset svn:ignore '
> eggs
> develop-eggs 
> bin
> var
> parts
> .installed.cfg' .
property 'svn:ignore' set on '.'
$ svn st
 M     .
M      buildout.cfg

Now you can commit your change to buildout.cfg, as well as the svn property you just set:

$ svn commit -m "basic buildout configuration"

The Policy and Theme Products

 On the SixFeetUp server, create basic repository structure for your policy and theme products:

$ svn mkdir file:///var/svn/casaproject/casa.policy -m "create basic structure"
Committed revision 3.
$ svn mkdir file:///var/svn/casaproject/casa.policy/trunk -m "create basic structure"
Committed revision 4.
$ svn mkdir file:///var/svn/casaproject/casa.policy/tags -m "create basic structure"
Committed revision 5.
$ svn mkdir file:///var/svn/casaproject/casa.policy/branches -m "create basic structure"
Committed revision 6.
$ svn mkdir file:///var/svn/casaproject/casa.theme -m "create basic structure" 
Committed revision 7.
$ svn mkdir file:///var/svn/casaproject/casa.theme/trunk -m "create basic structure"
Committed revision 8.
$ svn mkdir file:///var/svn/casaproject/casa.theme/tags -m "create basic structure"
Committed revision 9.
$ svn mkdir file:///var/svn/casaproject/casa.theme/branches -m "create basic structure"
Committed revision 10.

(there's probably a more streamlined way to to this!)

Policy Product

On your local machine, move into the src/ directory and create a policy product with paster:

$ cd src
$ paster create -t plone casa.policy
Selected and implied templates:
 ZopeSkel#basic_namespace  A project with a namespace package
 ZopeSkel#plone            A Plone project
  
Variables:
  egg:      casa.policy
  package:  casapolicy
  project:  casa.policy
Enter namespace_package (Namespace package (like plone)) ['plone']: casa
Enter package (The package contained namespace package (like example)) ['example']: policy
Enter zope2product (Are you creating a Zope 2 Product?) [False]: True
...
...
...

Remove the egg-info directory (is will be recreated for you later) and import the bare product into subversion:

$ rm -rf casa.policy.egg-info
$ svn import . svn+ssh://svn.npowerseattle.org/var/svn/casaproject/casa.policy/trunk/ -m "initial import"

Then remove the non-versioned copy of the product:

$ cd ..
$ rm -rf casa.policy

Theme Product

Repeat the  process for the theme product, but using the plone3_theme paster recipe:

np1055:~/zope2/casaproject/src jesses$ paster create -t plone3_theme casa.theme
Selected and implied templates:
  ZopeSkel#basic_namespace  A project with a namespace package
  ZopeSkel#plone            A Plone project
  ZopeSkel#plone3_theme     A Theme for Plone 3.0

Variables:
  egg:      casa.theme
  package:  casatheme
  project:  casa.theme
Enter namespace_package (Namespace package (like plonetheme)) ['plonetheme']: casa
Enter package (The package contained namespace package (like example)) ['example']: theme
Enter skinname (The skin selection to be added to 'portal_skins' (like 'My Theme')) ['']: CASA Theme
...
...
...

Again, remove the egg-info directory (is will be recreated for you later), import the bare product into subversion, and remove the non-versioned product:

$ rm -rf casa.theme.egg-info
$ svn import . svn+ssh://svn.npowerseattle.org/var/svn/casaproject/casa.theme/trunk/ -m "initial import"
$ cd .. 
$ rm -rf casa.theme

At this point both products exist independently in subversion, and can be checked out in the usual way. However, they are not associated with the buildout, and we want the buildout to automatically grab everything required to work on the project.  This can be done by setting up the two products we just created as external svn dependencies of the buildout's subversion configuration.  Here's what to do:

Create a file inside the src/ directory called EXTERNALS.txt

Model the contents on the following lines, replacing your product information as appropriate:

#
# applied by: svn propset svn:externals -F ./EXTERNALS.txt .
#
casa.policy svn+ssh://svn.npowerseattle.org/var/svn/casaproject/casa.policy/trunk/
casa.theme svn+ssh://svn.npowerseattle.org/var/svn/casaproject/casa.theme/trunk/

We're also going to add the NPower Seattle template product here, since it's an egg, but not available on pypi, so the complete file will look more like this:

#
# applied by: svn propset svn:externals -F ./EXTERNALS.txt .
#
casa.policy svn+ssh://svn.npowerseattle.org/var/svn/casaproject/casa.policy/trunk/
casa.theme svn+ssh://svn.npowerseattle.org/var/svn/casaproject/casa.theme/trunk/
nps.sitetemplate svn+ssh://svn.npowerseattle.org/var/svn/nps.sitetemplate/trunk

The external dependency is set with the command listed in the comment at the top of the file. From inside the root of the src/ directory, run the following:

$ svn propset svn:externals -F ./EXTERNALS.txt .
property 'svn:externals' set on '.'

The EXTERNALS.txt file should also be added to the repository:

$ svn add EXTERNALS.txt
A         EXTERNALS.txt

Now commit the EXTERNALS.txt file and the configuration change to the repository:

$ svn commit -m "set external dependencies"
Password: 
Sending        src

Committed revision 13.

 
Now back up to the root of the buildout and run svn up. These three products will be pulled into src/ for you.

Adding your src eggs to the buildout

You need to make your buildout environment aware of the eggs in your src directory. This is done in buildout.cfg by adding the egg names to the 'eggs' section of the [buildout] part, and by adding the path to them in the 'develop' section:

# Add additional eggs here
# elementtree is required by Plone
eggs =
    elementtree
    Products.DocFinderTab
    Products.Clouseau
    Products.PloneFormGen
    Products.slideshowfolder
    Products.Ploneboard
    casa.policy
    casa.theme
    nps.sitetemplate
    
    
# Reference any eggs you are developing here, one per line
# e.g.: develop = src/my.package
develop =
    src/casa.policy
    src/casa.theme
    src/nps.sitetemplate

You will also need to register at least your policy product in the zcml section of the [instance] part:

# If you want to register ZCML slugs for any packages, list them here.
# e.g. zcml = my.package my.other.package
zcml = 
    casa.policy

In order for your products to be available to your zope instance, buildout must be run again from the root directory (the 'N' and 'o' options can be used to speed this up):

$ bin/buildout -vNo
Develop: '/Users/jesses/zopes/casaproject/src/nps.sitetemplate'
Develop: '/Users/jesses/zopes/casaproject/src/casa.policy'
Develop: '/Users/jesses/zopes/casaproject/src/casa.theme'
...

Verifying Your Setup

To verify that all is as it should be, rerun buildout with these settings, then start up zope in the foreground:

$ bin/instance fg

Go to the management screen for your new instance:

Go to the Control Panel:

Browse the the Product Management screen:

Your policy product should appear in the list!

 

You're ready to start working in earnest!