# Chapter 2: Using Zope

This chapter gets you up and running with Zope. It guides you through installing and running Zope. This chapter covers the most important Zope concepts. By the end of this chapter you should be able to use Zope to create and manage simple yet powerful web applications.

## Downloading Zope

The first steps to using Zope are to download and install it. Zope is available for free from the Zope.org web site. The most recent stable version is always available from the Download section of Zope.org.

Zope is currently available as a binary for Windows, Linux and Solaris. This means that you can just download and install it without having to compile any programs. For other platforms you must download the source and compile Zope. Zope can be compiled and run on almost any Unix-like operating system. As a general rule of thumb, if Python is available for your operating system and you have a C compiler, then you can probably use Zope.

## Installing Zope

You will install Zope differently depending on your platform. If you are running a recent version of Linux, you may already have Zope installed. You can get Zope in both binary and source forms. There are also several different binary formats available.

### Installing Zope for Windows

Zope for Windows comes as a self-installing .exe file. To install Zope, double click on the installer. The installer walks you through the installation process. Pick a name for your Zope installation and a directory to install it in. Click Next and create a new Zope user account. This account is called the initial user. This creates an account that you can use to log into Zope for the first time. You can change this user name and password later if you wish.

If you are using Windows NT or Windows 2000, you can choose to run Zope as a service. Running Zope as a service is a good idea for a public server. If you are just running Zope for personal use don't bother running it as a service. Keep in mind that if you are running Windows 95, Windows 98, or Windows ME (Millenium Edition), you cannot run Zope as a service.

If you decide to uninstall Zope later you can use the Unwise.exe program in your Zope directory.

### Downloading Linux and Solaris Binaries

Download the binary for your platform and extract the tarball:

            $ tar xvfz Zope-2.4.0-linux2-x86.tgz

In this example, you are downloading version 2.4.0. This may not be the most recent version of Zope when you read this, so be sure and get the latest stable version of Zope for your platform.

This will unpack Zope into a new directory. Enter the Zope directory and run the Zope installer script:

            $ cd Zope-2.4.0-linux2-x86
            $ ./install

The installer will print information as it installs Zope. Among other things, it will create a initial user account. You can change the initial user name and password later with the zpasswd.py script (see Chapter 7, "Users and Security").

The installer will configure Zope to run as your UNIX userid. If you prefer to run Zope as another userid, you can use the `-u` command line switch and specify the user you want to configure Zope to run as. There are many books out there with more information on userids and UNIX administration in general you should check out if you want to do anything fancy. For now things will work fine if you just install Zope to runs as your userid by not specifying any extra command line options.

For more information on installing Zope see the installation instructions in doc/INSTALL.txt and find out more about the installer script by running it with the `-h` help switch:

            $ ./install -h

### Getting Zope in RPM and deb format

Zope Corporation doesn't make Zope available in RPM format, but other people do. Jeff Rush regularly packages Zope as RPMs. For more information check out his web page (http://www.taupro.com/Downloads/Zope/). Zope is also available in the Debian Linux deb package format. You can find Zope deb packages at the Debian web site site. Generally the latest Zope releases are found in the unstable distribution.

### Compiling Zope from Source Code

If binaries aren't available for your platform, then chances are you can compile Zope from the source. To do this, install Python from the sources for your platform and make sure you have a C compiler. You can get Python from the Python.org web site. Although we try and use the most recent Python for Zope, often the latest Python version is more recent than the version we "officially" support for Zope. For information on which version of Python you need to compile Zope with, see the release notes on the Web page for each version. Zope 2.4 requires Python 2.1. Zope 2.3 and earlier versions used Python 1.5.2.

Download the Zope source distribution and extract the tarball:

            $ tar xvfz Zope-2.4.0-src.tgz

This unpacks Zope into a new directory. Enter the Zope directory and run the Zope installer script:

            $ cd Zope-2.4.0-src
            $ python wo_pcgi.py

The installer compiles Zope and sets up your installation. The installer prints information as it runs, including the initial user name and password. It's important to write down that information so you can log into Zope. For more information see the installation instructions in the file doc/INSTALL.txt. You can change the initial user account later with the zpasswd.py script (see Chapter 7, "Users and Security").

## Starting Zope

Depending on your platform, you run Zope with different commands. Whatever your platform, you can either run Zope manually, or automatically. When running Zope manually, you simply tell Zope when to start and when to stop. When running Zope automatically, Zope will start and stop when your computer starts and stops.

### Starting Zope On Windows

The installer creates a Zope directory with a batch file called start.bat. Double click the start.bat icon. This will open a window that includes logging information. On this window you find out what port Zope is listening on. You can now log into Zope with a web browser.

If you are running Zope as a service, you can start and stop Zope via the Services control panel. Zope will write events to the event log so that you can keep track of when your service starts and stops. If you run Zope as a service you must know what port Zope is running on, since you will not have direct access to its detailed logging information.

Zope comes with its own web server. When you start Zope, its web server starts. If you wish you can connect Zope to your existing web server such as IIS, but this is beyond the scope of this book. The Zope Administrator's Guide covers this kind of material.

### Starting Zope on UNIX

Run the start script:

            $ ./start &

Zope will start running and will print logging information to the console. You should see information telling you what port Zope is listening on. You can now log into Zope with a web browser.

Zope comes with its own web server. When you start Zope, its web server starts. If you wish you can connect Zope to your existing web server such as Apache, but this is beyond the scope of this book. The Zope Administrator's Guide covers this kind of material.

The start script can also be edited to start Zope with many different options. How to customize your Zope startup is also described in the Administrator's Guide.

## Logging In

To log into Zope you need a web browser. Zope's interface is written entirely in HTML, therefore any browser that understands modern HTML works. Mozilla, and any 3.0+ version of Microsoft Internet Explorer or Netscape Navigator will do.

To log into the management interface point your web browser to Zope's management URL. The management URL for Zope is Zope's base URL with /manage appended. Assuming you have Zope installed on your local machine serving on the default port 8080, the management URL is:

          http://localhost:8080/manage

This URL usually works, but you may need to login to a different machine than the one we show you here. To find out exactly which URL to use, look at the logging information Zope prints as it starts up. For example:

          ------
          2000-08-07T23:00:53 INFO(0) ZServer Medusa (V1.18) started at Mon Aug  7 16:00:53 2000
                  Hostname: peanut
                  Port:8080

          ------
          2000-08-07T23:00:53 INFO(0) ZServer FTP server started at Mon Aug  7 16:00:53 2000
                  Authorizer:None
                  Hostname: peanut
                  Port: 8021
          ------
          2000-08-07T23:00:53 INFO(0) ZServer Monitor Server (V1.9) started on port 8099

The first log entry indicates Zope is running on a machine named peanut and that the web server is listening on port 8080. This means that the management URL is http://peanut:8080/manage. Later in the book we'll look at the other servers referred to in the logging information.

After you enter Zope's management URL in your browser, your browser will prompt you to log into Zope by providing a user name and password. Type in the initial user name and password created during the install process. If you don't know the initial user name and password, then shut Zope down by closing its window, and change the initial user password with the zpasswd.py script and restart Zope. See Chapter 7, "Users and Security" for more information about configuring the initial user account.

## Controlling Zope with Management Interface

After you successfully login you see a web page of the Zope management interface, as shown in Figure 2-1.

Figure 2-1 The Zope management interface.

The Zope management interface lets you control Zope within your web browser.

## Using the Navigator

The Zope management interface is broken into three frames. With the left frame you navigate around Zope much like you would navigate around a file system with a file manager like Windows Explorer. This frame is called the Navigator, and is shown in the left frame of Figure 2-1. In this frame you see the root folder and all of its subfolders. The root folder is in the upper left corner of the tree. The root folder is the "top" of Zope. Everything in Zope lives inside the root folder.

Some of the folders have plus marks to the left of them. These plus marks let you expand the folders to see the sub-folders that are inside.

Above the folder tree Zope shows you login information in a frame. In this screen shot you can see that you are currently logged in as "manager". When you log in to Zope you will use the initial user account and you will see the name of this account in place of "manager".

To manage a folder, click on it and it will appear in the right-hand frame of the browser window. This frame is called the workspace.

## Using The Workspace

The right-hand frame of the management interface shows the object you are currently managing. When you first log into Zope the current object is the root folder, as shown in the right frame of Figure 2-1. The workspace gives you information about the current object, and lets you change it.

Across the top of the screen are a number of tabs. The currently selected tab is highlighted in a lighter color. Each tab takes you to a different view of the current object. Each view lets you perform a different management function on that object.

In Figure 2-1, you are looking at the Contents view of the root folder object.

At the top of the workspace, just below the tabs, is a description of the current object's type and URL. On the left is an icon representing the current object's type, and to the right of that is the object's URL.

In Figure 2-1 "Folder at /" tells you that the current object is a folder and that its URL is `/`. Note that this URL is the object's URL relative to Zope's base URL. So if the URL or your Zope site was http://mysite.example.com:8080, then the URL of the "Folder at /myFolder" would be http://mysite.example.com:8080/myFolder.

As you explore different Zope objects, you find that the URLs (as displayed in the management screen), can be used to navigate between objects.

For example, if you are managing a folder at /Zoo/Reptiles/Snakes you can return to the folder at /Zoo by clicking on the word Zoo in the folder's URL.

In the frame at the top of the management interface, your current login name is displayed, along with a pull-down box that lets you select:

Preferences
  Here, you can set default preferences for your Zope session, you can even set to hide the top frame.
Logout
  Selecting this menu item will log you out of Zope.
Quick Start Links
  These are quick links out to Zope documentation and community resources.

## Understanding Users in Zope

Zope is a multi-user system. You've already seen how you can log into Zope via the management interface with the initial user name and password. Zope supports other kinds of users:

Emergency User
  The emergency user is rarely used in Zope. This account is used for creating other user accounts and fixing things if you accidently lock yourself out.

  The emergency user is both very powerful and very weak. It is not restricted by most security controls. However, the emergency user can only create one type of object: Users. Using the Emergency User to repair your Zope system in the case of accidental lock-out is discussed in the Administrator's Guide.

Manager
  The Manager is the Zope workhorse. You will need to log in with the Manager account to do most of the work involved with building Zope web sites. The initial user is a Manager, and you can create as many Manager accounts as you need.
Others
  You can create your own kind of users that fit into groups, or are responsible for carrying out a role that you define. This is explained more in Chapter 7, "Users and Security", which discusses Zope security and users.

## Creating Users

Managers can create Zope users in a unique kind of folder called a User Folder.

User folder icons look like folders with a person on them. User folders always have the name acl_users, as shown in Figure 2-1.

Click on the acl_users folder in the root folder to enter it. User folders contain User objects. You can create new users and edit existing users. Click the Add button to create a new user, as shown in Figure 2-2.

Figure 2-2 Adding a new user.

Fill out the form to create a new user. In the Name field put your chosen user name. Choose a password and enter it in the Password and (Confirm) fields. Leave the Domains field blank. This an advanced feature and is discussed in Chapter 7, "Users and Security". Select the Manager role from the Roles select list. Then click the Add button.

Congratulations, you've just created a manager account. Zope will show you this new manager account inside the user folder. Later you can change or delete this user if you wish.

## Changing Logins

To change your login select Logout from the top frame of the management interface. You will be prompted to login again. To change logins, enter a new user name and password.

To logout select Logout from the top frame of the management interface and cancel the new login. You should see a message telling you that you are logged out. If you try to access the Zope management interface after you are logged out, you'll be prompted to log in again. You can also logout of Zope by quitting your web browser.

## Creating Objects

The Zope management interface represents everything in terms of objects and folders. When you build web applications with Zope, you spend most of your time creating and managing objects in folders. For example, to make a new manager account you create a user object in a user folder.

Return to the root folder by clicking on the top left folder in the Navigator frame.

To add a new object to the current folder select an object from the pull-down menu in the right frame labeled "Select type to add...". This pull-down menu is called the product add list.

For example, to create a folder, select Folder from the product add list. At this point, you'll be taken to an add form that collects information about the new folder, as shown in Figure 2-3.

Figure 2-3 Folder add form.

Type "zoo" in the Id field, and "Zope Zoo" in the Title field. Then click the Add button.

Zope will create a new folder in the current folder. You can verify this by noting that there is now a new folder named zoo inside the root folder.

Click on zoo to enter it. Notice that the URL of the folder is based on the folder's id. You can create more folders inside your new folder if you wish. For example, create a folder inside the zoo folder with an id of arctic. Go to the zoo folder and choose Folder from the pull-down menu. Then type in "arctic" for the folder id, and "Arctic Exhibit" for the title. Now click the Add button. You always create new objects in the same way:

1. Go to the folder where you want to add a new object.
2. Choose the type of object you want to add from the pull-down menu.
3. Fill out an add form and submit it.
4. Zope will create a new object in the current folder.

Notice that every Zope object has an id that you need to specify in the add form when you create the object. The id is how Zope names objects. Objects also use their ids for their URLs.

Chapter 3, "Using Basic Zope Objects", covers all of the basic Zope objects and what they can do for you.

## Moving Objects

Most computer systems let you move files around in directories with cut, copy and paste. The Zope management interface has a similar system that lets you move objects around in folders by cutting or copying them, and then pasting them to a new location.

To experiment with copy and paste, create a new folder in the root folder with an id of bears. Then select bears by checking the check box just to the left of the folder. Then click the Cut button. Cut removes the selected objects from the folder and places them on a clipboard. The object will not, however, disappear from its location until it is pasted somewhere else.

Now enter the zoo folder by clicking on it, and then enter the arctic folder by clicking on it. You could also have used the Navigator to get to the same place. Now, click the Paste button to paste cut object(s) into the current folder. You should see the bears folder appear in its new location. You can verify that the folder has been moved by going to the root folder and noting that bears is no longer there.

Copy works similarly to cut. When you paste copied objects, the original objects are not changed. Select the object(s) you want to copy and click the Copy button. Then navigate to another folder and click the Paste button.

You can cut and copy folders that contain other objects and move many objects at one time with a single cut and paste. For example, go to the zoo folder and copy the arctic folder. Now paste it into the zoo folder. You will now have two folders inside the zoo folder, arctic and copy of arctic. If you paste an object into the same folder where you copied it, Zope will change the id of the pasted object. This is a necessary step, as you cannot have two objects with the same id in the same folder.

To rename the copy of arctic folder, select the folder by checking the check box to the left of the folder. Then click the Rename button. This will take you to the rename form as shown in Figure 2-4.

Figure 2-4 Renaming an Object

Type in a new id "mountains" and click OK. Zope ids can consist of letters, numbers, spaces, dashes underscores and periods, and are case-sensitive. Here are some legal Zope ids: index.html, 42, and Snake-Pit.

Now your zoo folder contains an arctic and a mountains folder. Each of these folders contains a bears folder. This is because when we made a copy of the arctic folder it also copied the bears folder that it contained.

If you want to delete an object, select it and then click the Delete button. Unlike cut objects, deleted objects are not placed on the clipboard and cannot be pasted. In the next section we'll see how we can retrieve deleted objects.

Zope will not let you cut, delete, or rename a few particular objects in the root folder. These objects include Control_Panel, standard_html_header, standard_html_footer, and standard_error_message. These important objects are necessary for Zope's operation. Also, these operations don't work in some cases. For instance, you can't paste a user object into a regular folder.

If you are having problems with copy and paste, make sure that you have enabled cookies in your browser. Zope uses cookies to keep track of the objects that you cut and copy.

## Undoing Mistakes

Any action in Zope that causes objects to change can be undone, via the Undo tab. You can recover from mistakes by undoing them.

Select the zoo folder that we created earlier and click Delete. The folder disappears. You can get it back by undoing the delete action.

Click the Undo tab, as shown in Figure 2-5.

Figure 2-5 The Undo view.

Select the first transaction labeled /manage_delObjects, and click the Undo button.

This action tells Zope to undo the last transaction. You can verify that the task has been completed by making sure that the Zoo folder has returned.

## Undo Details and Gotchas

Undo works on the object database that Zope uses to store all Zope objects. Changes to the object database happen in transactions. You can think of a transaction as any change you make to Zope, such as creating a folder or pasting a bunch of objects to a new place. Each transaction describes all of the changes that happen in the course of performing the action.

You cannot undo a transaction that a later transaction depends upon. For example, if you paste an object into a folder and then delete an object in the same folder you might wonder whether or not you can undo the earlier paste. Both transactions change the same folder so you can not simply undo the earlier transaction. The solution is to undo both transactions. You can undo more than one transaction at a time by selecting multiple transactions on the Undo tab and then clicking Undo.

Another problem to be aware of is that you cannot undo an undo. Therefore if you add a folder and then undo that particular action, you cannot get the new folder back by undoing the undo.

One last note on undo. Only changes to objects stored in Zope's object database can be undone. If you have integrated data in a relational database server such as Oracle or MySQL (as discussed in Chapter 12, "Relational Database Connectivity") changes to data stored there cannot be undone.

## Administering and Monitoring Zope

The Control Panel is an object in the root folder that controls various aspects of Zope's operation.

Click on the Control_Panel object in the root folder, as shown in Figure 2-6.

Figure 2-6 The Control Panel

To shutdown Zope, click the Shutdown button. Shutting down Zope will cause the server to stop handling requests and completely exit from memory. You will have to manually start Zope to continue using it. Only shutdown Zope if you are finished using it, and have the ability to access the server on which Zope is running, so that you can manually restart it later.

If you are running Zope on UNIX under daemon control or as a service on Windows, you can restart Zope from the control panel folder. Clicking the Restart button will shut down Zope and then immediately start up a new instance of the Zope server. It may take Zope a few seconds to come back up and start handling requests.

On the control panel you will also see several links at the bottom of the screen, one of which is Database Managment, which controls Zope's object database.

Transactions don't go away until you pack the Zope database. This means that you can undo all transactions except ones that have been removed by packing the database. When you choose to pack the database you can specify which transactions to remove so that you can for example only remove transactions older than a week.

## Using the Help System

Zope has a built in help system. Every management screen has a help button in the upper right-hand corner. This button launches another browser window and takes you to the Zope Help System.

Go to the root folder. Click the Help button, and you should see what is shown in Figure 2-7.

Figure 2-7 The Help System.

The help system has an organization similiar to the two primary panes of the Zope management interface, it has one frame for navigation and one for displaying the current topic.

Whenever you click the help button from the Zope management screen, the right frame of the help system displays the help topic for the current management screen. In this case, you see information about the Contents view of a folder.

## Browsing and Searching Help

Normally you use the help system to get help on a specific topic. However, you can browse through all of the help content if you are curious, or simply want to find out about things besides the management screen you are currently viewing.

The help system lets you browse all of the help topics in the Contents tab of the left-hand help frame, as shown in Figure 2-7. You can expand and collapse help topics. To view a help topic in the right frame, click on it.

All help on the Zope management screens is located in the Zope help folder. Inside you'll find many help topics. You'll also find a help folder called API Reference. This folder contains help on scripting Zope, which is explained further in Chapter 9, "Advanced Zope Scripting".

When you install third-party components they also include help that you can browse. Each installed component has its own help folder.

Search the help system by clicking on the Search tab and entering one or more search terms. For example, to find all of the help topics that mention folders, type "folder" into the search form.

## Starting with the Zope Tutorial

Zope comes with a built-in tutorial. The tutorial guides you through all the basics of creating and managing Zope objects. To launch the tutorial, add a Zope Tutorial to the current folder by selecting Zope Tutorial from the Product add list. Give it an id which is unique in the current folder, such as tutorial. The tutorial comes with several examples that you can change and copy for your own use.

If you start the tutorial and want to stop using it before you have completed all the lessons, you can later return to the tutorial. Just go to the help system and find the lesson you'd like to continue with by browsing the Zope Tutorial help folder. There is no need to re-install the tutorial.

If you are having problems with the tutorial, make sure to enable cookies in your browser. The tutorial uses cookies to keep track of where your example objects are. Also, if you enable Javascript in your browser, the tutorial will make sure that the Zope management interface stays in sync with your tutorial lesson.

Now that you have Zope running, it's time to explore the system more thoroughly. You've seen how to manage Zope through the web and have learned a little about Zope objects. In the next chapter you'll meet many different Zope objects and find out how to build simple applications with them.