Adding a Module/Product
Inevitably, once you've started up Plone for the first time, you'll want to add a module or two to try things out.
This is where you get familiar with buildout (whether you like it or not).
In the root of your Plone instance you'll find a file - buildout.cfg.
If you've used the Windows installer this will be in the directory where you told the installer to install Plone (either c:\Program Files\Plone or c:\Plone). If you're on Mac or Linux it'll be where-ever you installed Plone, but one directory down, usually in zinstance.
This file is used to provide all the options you need to build a Plone installation, every time you want to add a module (known in Plone/Zope circles as a Product or an Egg) you should rebuild your Plone installation to incorporate the module properly - it takes a minute or so only to do this. Not much happens, it'll download the module/Product/Egg from the internet and then add a few lines to various configuration files.
First Attempt - adding PloneFormGen
As a start, try adding the killer app PloneFormGen to your Plone installation.
1. Edit buildout.cfg
Open buildout.cfg in a text editor (on Windows it probably has to be Wordpad or something like Scite). Scroll down a little way until you find the section called Eggs and a bit called "Optional functionality". Keep going and you should find:
If you're not accustomed to hashes, these indicate that the text on that line is a comment and will be ignored by a computer program reading the file. In this case delete the hash:
2. Run Buildout
Now do two things:
- save the buildout.cfg file
- stop your Plone/Zope instance, if it's running (ctrl + c).
and then, using a terminal window, navigate to the directory in which your buildout.cfg file is situated. On Windows, the procedure is:
Start > run > cmd
cd Plone (or where-ever you installed it)
Now run the buildout program itself and watch it go and get PloneFormGen (and some other stuff it needs) and set everything up for you.
Finally, start your Plone/Zope instance, then log in to your site and use Site Setup > Addons to install PloneFormGen on your particular Plone site.
Installing other, officially released, modules / products
If a module/Product/Egg has been officially released, then you need to follow the same sort of procedure as for PloneFormGen above. Most modules are listed on http://www.plone.org/downloads - always have a look at the readme and other instructions and bear in mind that you might be looking at a trial release (a beta) which might not work properly.
- Find out the name of the module/Product/Egg, it'll usually be something like collective.[name of module] or Products.[name of module].
- Enter this into the list of eggs in buildout.cfg
- And one additional step (which you only need to do if the module doesn't have the prefix "Products."). Scroll down a little further in buildout.cfg and add the same name under the section ZCML.
Follow the procedure above to run buildout (Save, Stop - ctrl + c, Run - bin/buildout, Start - bin/instance fg).
Installing unreleased modules/products
Usually unreleased modules or products are things you're working on yourself, or that you've noticed in a public code repository somewhere and would like to try out. In this case there are a couple of extra steps to add to the procedure above.
First put the code (it'll be a directory named Products.[name of module] or something similar) in the src directory of your Plone/Zope instance.
Then edit the buildout.cfg file as the instructions above - editing the Eggs and ZCML sections as appropriate. BUT scroll down to a third section as well Development Eggs. Here, add your product name but preface it with src/. Here's the entry for our MSD theme product:
Now do the Run Buildout procedure again
When things go wrong
It's easy enough to backtrack. Just remove the bits you've just added to buildout.cfg, run buildout and start again. If you make sure you start Plone/Zope straight after running buildout, you can easily double-check to see that you haven't broken anything.
Don't forget that after you've run buildout and started Plone/Zope you usually need to log in to your site as a manager, to install the product on the site itself.