Newcomer
After having installed Zope 3, there is only so much you can do with it. However, there are a bunch of interesting third-party add-on packages, such as relational database adapters and a Wiki implementation. A Wiki consists of a collection of pages that can be edited by any party visiting the page. The pages are connected via Wiki links, which are references to other Wiki pages via name. This chapter demonstrates how to install these packages, especially the ones maintained in the Zope repository.
Installing third-party packages in Zope 3 is much more explicit and similar to doing so in Python than in Zope 2. You can put a Zope 3 add-on package anywhere in your Python path, as you can any other Python package. This means that you can use the distutils package to distribute your add-on.
However, after you install the package, the Zope 3 framework does not know about it, and no magical package detection is used to find available packages. The Zope 3 framework is configured using Zope Configuration Markup Language (ZCML). Zope-specific Python packages also use ZCML to register their components with Zope 3. Therefore, you have to register a package’s root ZCML file with the startup mechanism.
This chapter demonstrates how to install the Wiki application for Zope 3. If you are using the repository version of Zope 3, Wiki will already be installed, but the steps shown in this chapter are the same for all other packages.
Determining where to install a package can be a difficult challenge because packages can be located anywhere in the path hierarchy. For example, the Wiki application is a top-level Python package and the Jobboard Example lives in zope.app.demo.
You usually want to place third-party packages in the common Zope 3 directory structure because that makes it easier to find the packages later. After you have determined the Zope 3 package root, you are all set. For the repository distribution, the package root is Zope3/src, where Zope3 is the directory that you checked out from the repository (for example, svn://svn.zope.org/repos/main/Zope3/trunk). For distributions, the package root is Zope3/lib/python, where Zope3 is /usr/local/ZopeX3-VERSION by default or the directory specified using the -prefix option of configure. An alternative is to use the zope instance as package root--for example, Zope3-Instance/lib/python, where Zope3-Instance is the path to the Zope 3 instance directory you provided during the mkzopeinstance call. The remainder of the book assumes that you are working with the distribution.
To install the Wiki application, you have to go to the Zope3-Instance/lib/python directory, which should be available in a Zope 3 instance.
The next step in installing a new Zope package is to get the package. You generally just download a TAR or ZIP archive and unpack it in the directory. However, for the Wiki application, there is no archive, and you have to fetch the package from SVN.
If you have the SVN client installed on your computer, you can use the following command to do an anonymous checkout of the zwiki package from the Zope X3 3.0 branch:
Although SVN allows you to name the created directory any way you want to, it is necessary to name the directory zwiki, because imports in the package assume this name. When the command line returns, the package should be located at Zope3-Instance/lib/python/zwiki.
The next step in installing a new Zope package is to register the package’s new components with the Zope 3 framework. To do that, you have to place a file in the package-includes directory. In a repository hierarchy, this directory is found in Zope3. In the distribution installation, it is located in Zope3/etc. You should enter the package-includes directory now and add a file called zwiki-configure.zcml, which contains the following:
The package-includes directory is special in that all files ending with -meta.zcml will be executed when all meta directives are initiated. All files ending with -configure.zcml are evaluated after all other configuration is complete. However, there is no magic involved in finding this directory because the behavior is explicitly defined in Zope3/etc/site.zcml.
When you save the file, Zope will be able to execute the Wiki package’s configuration.
If Zope 3 is running, you should stop it at this point. Then you should start Zope 3 and read the messages it prints during startup. If it starts without any error messages, your package has been installed successfully.
Note that unlike Zope 2, Zope 3 has no way to show you which products have been successfully installed because there is no formal concept of a Zope 3 add-on. However, you can usually tell immediately whether an installation was successful by entering the ZMI. If the Wiki object is available as a new content type, you know the configuration was loaded correctly.
To add a sample Wiki instance via a web browser, you need to visit the Zope 3 web UI by entering the URL http://localhost:8080/. Then you need to click the top folder in the Navigation column (at the upper left of the UI).
To add a sample Wiki, you follow these steps:
You should now see a Wiki entry in the list of objects. To experiment with the object, you simply click Wiki.
As you can see, installing a Zope 3 add-on package is similar to adding an add-on in Python, with the addition that you have to point Zope 3 to the ZCML file of the package.