Using the Zope Management Interface

When you log in to Zope, you are presented with the Zope Management Interface (ZMI). The ZMI is a management and development environment that allows you to control Zope, manipulate Zope objects, and develop web applications.

The Zope Management Interface represents a view into the Zope object hierarchy. Almost every link or button in the ZMI represents an action that is taken against an object. When you build web applications with Zope, you typically spend most of your time creating and managing objects.

Don't be frightened if you don't understand the word "object" just yet. For the purposes of this chapter, the definition of an "object" is any discrete item that is manageable through the Zope Management Interface. In fact, for the purposes of this chapter, you can safely mentally replace the word "object" with the word "thing" with no ill effect. If you get confused, however, you may want to review the Object Orientation chapter for more background on objects.

How The Zope Management Interface Relates to Objects

Unlike a webserver like Apache or Microsoft IIS, Zope does not "serve up" HTML files that it finds on your server's hard drive. The objects that Zope creates are not stored in files that have an ".html" extension on your server's hard drive. There is no file hierarchy on your server's computer that contains all of your Zope objects.

Instead, the objects that Zope creates are stored in a database known as the ZODB, which stands for (unsurprisingly) the "Zope Object DataBase". "Out of the box", the ZODB creates a file named "Data.fs" in which Zope stores its objects. The Zope Management Interface is the primary way that you interact with Zope objects that are stored in this database. Note that there are other methods of interacting with objects stored in the ZODB, including FTP and WebDAV, which are detailed in the chapter in this book entitled Managing Zope Using External Tools, but the ZMI is the primary management tool.

ZMI Frames

The ZMI uses three browser frames. The left frame is called the Navigator Frame, and using it you may expand and contract a view into the Zope object hierarchy much like you would expand and contract a view of files using a file tree widget like the one in Windows Explorer. The right frame is called the Workspace Frame, and it displays a particular view of the object you're currently managing. The top frame is called the Status Frame, and it displays the name of the user who you are currently logged in as well as a select list that allows you to perform various actions. We'll look more closely at these frames next.

The Navigator Frame

The left frame is the Navigator. In this frame you have a view into 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 "topmost" container of Zope objects. Almost everything meaningful in your Zope instance lives inside the root folder.

Figure 3-1 The Navigator Frame

Some of the folders in the Navigator are displayed with "plus mark" icons to their left. These icons let you expand the folders to see the sub-folders that are inside.

When you click on an object icon or name in the Navigator, the Workspace frame will refresh with a view of that object.

The Workspace Frame

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. The workspace gives you information about the current object, and lets you manage it.

Figure 3-2 The Workspace Frame

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.

When you first log in to Zope, 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.

At the top of the page, Folder at / tells you that the current object is a folder and that its path is "/". Note that this path is the object's place relative to Zope's "root" folder. The root folder's path is expressed as "/" , and since you are looking at the root when you first log in, the path displayed at the top of the workspace is simply "/".

Zope object paths are typically mirrored in the URLs that you use to access a Zope object. For instance, if the main URL of your Zope site was http://mysite.example.com:8080, then the URL of the root folder would be http://mysite.example.com:8080/ and the URL of Folder at /myFolder would be http://mysite.example.com:8080/myFolder.

As you explore different Zope objects, you find that the links displayed at the top of the workspace frame can be used to navigate between objects' management views. 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.

The Status Frame

In the "status 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

By selecting this menu item, you can set default preferences for your Zope management interface experience. You can choose to turn off the status frame. You can also choose whether or not you want the management interface to try to use style sheets. Additionally, you can change the default height and width of textareas displayed in the ZMI. This information is associated with your browser via a cookie. It is not associated in any way with your Zope user account.

Logout

Selecting this menu item will log you out of Zope. Due to the way that the HTTP "basic authentication" protocol works, this may not work properly on all browsers. If you experience problems logging out using this facility, try closing and reopening your browser to log out.

Quick Start Links

Selecting this menu item presents the "QuickStart" page which has links to Zope documentation and community resources.

Figure 3-3 The Status Frame

Creating Objects

The Zope Management Interface allows you to create new objects in your Zope instance. To add a new object, select an entry from the pull-down menu in the Workspace labeled "Select type to add...". This pull-down menu is called the add list.

The first kind of object you'll want to add in order to "try out" Zope is a "Folder". To create a Zope Folder object, navigate to the root folder and select Folder from the add list. At this point, you'll be taken to an add form that collects information about the new folder, as shown in the figure below.

Figure 3-4 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 object in the current folder named zoo. 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. The Workspace frame will switch to the contents view of zoo (which is currently an "empty" folder: it has no subobjects). Notice that the URL of the zoo 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. Enter 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.

When you use Zope, you create new objects by following these steps:

1. Enter to the folder where you want to add a new object.
2. Choose the type of object you want to add from the add list.
3. Fill out the resulting add form and submit it.
4. Zope will create a new object in the 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 as a part of their URL. The URL of any given Zope object is typically a URL consisting of the folders in which the object lives plus its name. For example, we created a folder named "zoo" in the root folder. Its URL consists of "http://your.server.name/zoo" (where "your.server.name" is your server's name).

Moving and Renaming 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.

NOTE: Zope move and rename options require that you have cookies enabled in your browser.

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 selects the selected objects from the folder and places them on Zope's "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. Now, click the Paste button to paste cut object(s) into the zoo 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 removed. 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 root folder copy the zoo folder. Now paste it into the root folder. You will now have two folders inside the root folder, zoo and copy_of_zoo. 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_zoo 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.

Figure 3-5 Renaming an Object

Type in a new id "zoo2" 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 root folder contains a zoo and a zoo2 folder. Each of these folders contains a bears folder. This is because when we made a copy of the zoo folder it also copied the bears folder that it contained. Copying an object also copies all of the objects it contains.

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 using Undo.

Zope will not let you cut, delete, or rename a few particular objects in the root folder. These objects include Control_Panel, browser_id_manager, and temp_folder. These objects are necessary for Zope's operation. It is possible to delete other root objects, such as index_html, session_data_manager, standard_html_header, standard_html_footer, standard_error_message, and standard_template.pt but it is not recommended unless you have a good reason to do so.

Transactions and Undoing Mistakes

All objects you create in Zope are stored in Zope's "object database". Unlike other web application servers, Zope doesn't store its objects in files on a filesystem. Instead, all Zope objects are stored by default in a single special file on the filesystem named Data.fs. This file is stored in the var directory of your Zope instance. Using an object database rather than using file system files allows operations to Zope objects to be transactional.

A transactional operation is one in which all changes to a set of objects are committed as a single "batch". In Zope, a single web request initiates a transaction. When the web request is finished, Zope commits the transaction unless there was an error during the processing of the request. If there was an error, Zope refrains from committing the transaction. Each transaction describes all of the changes that happen in the course of performing a web request.

Any action in Zope that causes a transaction can be undone, via the Undo tab. You can recover from mistakes by undoing the transaction that represents the mistake.

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 the figure below.

Figure 3-6 The Undo view.

Transactions are named after the Zope action (also known as a "method") that initiated them. In this case, the initiating action was one named "/manage_delObjects" (the action which deletes a Zope object).

Select the first transaction labeled /manage_delObjects, and click the Undo button at the bottom of the form, instructing Zope to undo the last transaction. You can verify that the task has been completed by visiting the root folder to make sure that the zoo folder has returned. You may need to refresh your browser window to see the effect if you just use the "Back" button to revisit the root folder. To see the effect in the Navigator pane, click the "Refresh" link within the pane.

You may undo an undo (or in other words, perform a "redo"). You can undo and redo as many times as you like. When you perform a "redo", Zope inserts a transaction into the undo log describing the redo.

The Undo tab is available on most Zope objects. When viewing the Undo tab of a particular object, the list of undoable transactions is filtered down to the transactions that have recently effected the current object and its subobjects.

Undo Details and Gotchas

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.

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 the chapter entitled "Relational Database Connectivity"), changes to data stored there cannot be undone.

Reviewing Change History

The Undo tab will provide you with enough information to know that a change has occurred. It, however, will not tell you much about the effect of the transaction on the objects that were changed during the transaction. "Presentation" and "logic" objects like DTML Methods, DTML Documents, Zope Page Templates, and Script (Python) objects support History for this purpose. If you know a transaction has affected one of these objects, you can go to that object's History View and look at the previous states of the object, as shown in the figure below.

Figure 3-7 The History View

The History view of an object supports comparison of revisions, allowing you to track their changes over time. You may select two revisions from an object's History and compare them to one another. To perform a comparison between two object revisions, select two revisions using the checkboxes next to the transaction identifiers, and click the Compare button.

The resulting comparison format is often called a diff. The diff format shows you the lines that have been added to the new document (via a plus), which lines have been subtracted from the old document (via a minus), and which lines have been replaced or changed (via an exclamation point).

Figure 3-8 Comparing Revisions Via The History View

To revert to an older object revision, click the checkbox next to the transaction identifier, then click the Copy to present button.

Importing and Exporting Objects

You can move objects from one Zope system to another using export and import. You can export all types of Zope objects to an export file. This file can then be imported into any other Zope system.

You can think of exporting an object as cloning a piece of your Zope system into a file that you can then move around from machine to machine. You can take this file and graft the clone onto any other Zope server.

Suppose you have a folder for home work that you want to export from your school Zope server, and take home with you to work on in your home Zope server. Create a folder in your root folder called "homeWork". After creating the folder, click the checkbox next to the homeWork folder you just created. Then click the Import/Export button. You should now be working in the Import/Export folder view, as shown in the figure below.

Figure 3-9 Exporting homeWork.zexp

There are two sections to this screen. The upper half is the export section and the lower half is the import section. To export an object from this screen, type the id of the object into the first form element, Export object id. In our case Zope already filled this field in for us, since we selected the homeWork folder on the last screen.

The next form option lets you choose between downloading the export file to your computer or leaving it on the server. If you check Download to local machine, and click the Export button, your web browser will prompt you to download the export file. If you check Save to file on server, then Zope will save the file on the same machine on which Zope is running, and you must fetch the file from that location yourself. The export file will be written to Zope's var directory on your server. By default, export files have the file extension .zexp.

In general it's handier to download the export file to your local machine. Sometimes it's more convenient to save the file to the server instead, for example if you are on a slow link and the export file is very large, or if you are just trying to move the exported object to another Zope instance on the same computer.

The final export form element is the XML format? checkbox. Checking this box exports the object in the eXtensible Markup Language (XML) format. Leaving this box unchecked exports the file in Zope's binary format. XML format exports are much larger but are (mostly) human-readable. For now, the only tool that understands this XML format is Zope itself, but in the future there may be other tools that can understand Zope's XML format. In general you should leave this box unchecked unless you're curious about what the XML export format looks like and want to examine it by hand.

While you're viewing the export form for homeWork, Ensure "download to local machine" is selected, "XML format?" is not selected, and click the Export button. Your browser will present a file save dialog. Save the file to a temporary location on your local computer (it will be named homeWork.zexp).

Now suppose that you've gone home and want to import the file into your home Zope server. First, you must copy the export file into Zope's import directory on your Zope server's filesystem. Here is an example of doing so. We are copying the homeWork.zexp file that's in a directory named /tmp on the local computer to a remote ("home") computer running Zope using the scp facility on Linux. We copy the .zexp file into our Zope directory's "import" directory. In this example, the Zope installation directory on the remote computer is named "/home/chrism/sandboxes/ZBExample":

      chrism@saints:/tmp$ ls -al homeWork.zexp       -rw-r--r--    1 chrism   chrism        182 Jul 13 15:44 homeWork.zexp      chrism@saints:/tmp$ scp homeWork.zexp saints.homeunix.com:/home/chrism/sandboxes/ZBExample/import      chrism@saints.homeunix.com's password:       homeWork.zexp        100% |*****************************|   182       00:00          chrism@saints:/tmp$ 

In the above example, the export file was copied from the local computer's /tmp directory to the remote computer's /home/chrism/sandboxes/ZBExample/import/homeWork.zexp file. Your local directory and your Zope's installation directory will be different. For purposes of this example, copy the export file you downloaded to your Zope installation's "import" directory using whatever facility you're most comfortable with (you needn't use scp).

Now, go back to your Zope's management interface. Create a Folder named import_example. Visit the newly-created import_example folder by clicking on it in the management interface. Then click on Import/Export button in the import_example folder and scroll to the bottom of the Workspace frame. Note that Zope gives you the option to either Take ownership of imported objects or Retain existing ownership information. Ownership will be discussed more in the chapter entitled "Users and Security". For now, just leave the Take ownership of imported objects option selected and, enter the name of the export file ('homeWork.zexp') in the Import file name form element and click Import.

Figure 3-10 Importing homeWork.zexp

After you've clicked import, you will have a new object in the import_example folder named homeWork. Note that Zope informs you of the success of the import in a status message.

Figure 3-11 Success Importing homeWork.zexp

There are a few caveats to importing and exporting. In order to successfully perform an import of a Zope export file, you need to make sure that the Zope into which you're importing has the same Products installed. If an import fails, it's likely that you don't have the same Products installed in your Zope as the Products installed in the Zope from whence the export file came. Our example above works because we are exporting an object which is very common and which comes with all Zopes (a Folder). Check with the distributor of the export file to see what Products are necessary for proper import if you have problems importing a given export file.

Note that you cannot import an object into a folder that has an existing object with the same id. Therefore, when you import an export file, you need to ensure it does not want to install an object that has the same name as an existing object in the folder in which you wish to import it. In our example above, in order to bring your homework back to school, you'll either need to import it into a folder that doesn't already have a homeWork folder in it, or you'll need to delete the existing homeWork folder before importing the new one.

Using Object Properties

Properties are ways of associating information with objects in Zope. Many Zope objects, including folders, support properties. Properties can label an object in order to identify its contents For example, many Zope content objects have a content type property. Another use for properties is to provide meta-data for an object such as its author, title, status, etc.

Properties can be more complex than strings; they can also be numbers, lists, or other data structures. All properties are managed via the Properties view. Click on the Properties tab of the "root" object and you will be taken to the properties management view, as seen in the figure below.

Figure 3-12 The Properties Management View

A property consists of a name, a value, and a type. A property's type defines what kind of value or values it can have.

In the figure above, you can see that the folder has a single string property: title. It has the value Zope. You may change any predefined property by changing its value in the Value box, clicking Save Changes afterwards. You may add additional properties to an object by entering a name, value, and type into the bottommost form on the Properties view.

Zope supports a number of property types. Each type is suited to a specific task. This list gives a brief overview of the kinds of properties you can create from the management interface:

string

A string is an arbitrary length sequence of characters. Strings are the most basic and useful type of property in Zope.

int

An int property is an integer, which can be any positive or negative number that is not a fraction. An int is guaranteed to be at least 32 bits long.

long

A long is like an integer that has no range limitation.

float

A float holds a floating point, or decimal number. Monetary values, for example, often use floats.

lines

A lines property is a sequence of strings.

tokens

A tokens property is a list of words separated by spaces.

text

A text property is just like a string property, except that Zope normalizes the line ending characters (different browsers use different line ending conventions).

selection

A selection property is special, it is used to render an HTML select input widget.

multiple selection

A multiple selection property is special, it is used to render an HTML multiple select form input widget.

Properties are very useful tools for tagging your Zope objects with little bits of "metadata". Properties are supported by most Zope objects, and are often referenced by "dynamic" Zope objects such as "scripts" and "methods" (which we have not yet discussed) for purposes of data display.

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 which exposes the Zope Help System.

To see the help system, go to the root folder and click the Help link at the top far right in the Workspace frame.

Figure 3-13 The Help System.

The help system has an organization similar 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. You can expand and collapse help topics. To view a help topic in the right frame, click on it in the left frame. By default, no topics are expanded.

Most help pertaining to Zope itself is located in the Zope Help folder. Click on the "plus sign" next to the word Zope Help in the Contents tab of the left frame. The frame will expand to show help topics (in an apparently random and somewhat unhelpful order, currently) and further expandable help categories including API Reference, DTML Reference, and ZPT Reference. These subcategories contain help on scripting Zope, which is explained further in the chapters named Dynamic Content With DTML, Using Zope Page Templates, and Advanced Zope Scripting.

When you install third-party Zope components they may also include help. Each installed component has its own help folder.

You may search for content in the help system by clicking on the Search tab in the left frame, entering one or more search terms. For example, to find all of the help topics that mention folders, type "folder" into the search form and click "Search". This will return a number of help topic links, hopefully most of which pertain to the word "folder".

Logging Out

You may select Logout from the Status Frame dropdown box to attempt to log out of Zope. Doing so will cause your browser to "pop up" an authentication dialog. Due to the way most web browsers work, in some cases you actually need to click on the "OK" button with an incorrect user name and password filled in to the authentication dialog to really become logged out of the management interface. If you do not do so, you may find that even after selecting "Logout", that you are still logged in. This is an intrinsic limitation of the HTTP Basic Authentication protocol which Zope's stock user folder employs. Alternately, you may close and reopen your browser to log out of Zope.