Using Zope as an XML-RPC Server
January 12, 2000
To illustrate how to communicate with Zope via XML-RPC let's build a simple Zope client. The program will allow you to connect to Zope and edit documents. This example uses Python but you could use Perl or TCL or Java or any of a number languages which support XML-RPC. To run the following interactive examples you'll need my extended version Pythonware's Python XML-RPC module which includes support for basic authentication. Note: the completed client does not need this extended module.
Reading a Document
The first thing we'll want to do is to be able to retrieve the contents of a Zope document.
Connect to the Zope with your web browser and identify a document that you would like to work with. For this example I'll use a document located at http://localhost:8080/Test.
Now let's connect to this object via XML-RPC.
Fire up the Python interpreter and import the extended XML-RPC module.
D:\>python Python 1.5.2 (#0, Apr 13 1999, 10:51:12) [MSC 32 bit (Intel)] on win32 Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam >>> import xmlrpclib >>>
If you get an import error at this point you haven't correctly installed the extended Python XML-RPC module.
Next create a Server object which points at your Zope document. You'll need the URL of your document and a manager username and password for Zope. Recall that your document's URL is shown at the top of its Zope management screen.
>>> d=xmlrpclib.Server('http://localhost:8080/Test', ... xmlrpclib.BasicAuthTransport('myusername','mypassword'))
Note: you should substitute your Zope manager username and password in the above example.
Now you have a local Python object which is a proxy for your remote Zope document object. You can call methods on your proxy object and XML-RPC will take care of marshalling the arguments, sending them to your Zope object and returning the results. It's like having the remote Zope object locally available.
To get the contents of a Zope document you can call the document_src method.
>>> print d.document_src() <dtml-var standard_html_header> <h2><dtml-var title_or_id></h2> <p> This is my sample test document. </p> <dtml-var standard_html_footer>
Notice how you just call the method on our proxy object as though it were the actual Zope document object. This is the magic of XML-RPC--simple distributed objects.
Uploading a Document
Now let's make some changes to the contents of the document.
>>> content=d.document_src() >>> import string >>> content=string.replace(doc, 'test', 'CHANGED') >>> print content <dtml-var standard_html_header> <h2><dtml-var title_or_id></h2> <p> This is my sample CHANGED document. </p> <dtml-var standard_html_footer>
Now that you've changed your document let's upload it to Zope. You can do this by calling the manage_upload method on your Zope document.
Zope will return a confirmation HTML message indicating that the upload was successful. You can now verify that the upload worked by going to the Zope management interface with your web browser and checking the source of the document.
Sure enough, your changes have been made.
Congratulations! You've just successfully managed Zope with XML-RPC.
Exploring Zope Folders
In addition to editing documents a Zope client should be able to locate Zope documents.
You can find out about the contents of a Zope folder by calling its objectIds method. This method tells you the names of contained objects. Here's how to query the Zope folder that contains the test document.
>>> f=xmlrpclib.Server('http://localhost:8080', ... xmlrpclib.BasicAuthTransport('myusername','mypassword')) >>> print f.objectIds() ['Control_Panel', 'standard_html_header', 'standard_html_footer', 'standard_error_message', 'Test']
This shows you all the objects contained in your top-level Zope folder. If you just want to see certain kinds of Zope objects you can pass the type(s) of the objects you are interested in to the objectIds method.
>>> print f.objectIds('DTML Method') ['standard_html_header', 'standard_html_footer', 'standard_error_message'] >>> print f.objectIds('DTML Document') ['Test'] >>> print f.objectIds('Folder') 
Using the objectIds method a Zope client can easily explore a Zope folder and its sub-folders.
The Finished Client
Now that you've seen how to locate and edit Zope documents using XML-RPC, it's relatively straightforward to build a graphical user interfacethat allows you to browse Zope folders and edit documents.
The example client includes source code so you can see how it works. The client connects to a Zope web site and allows you to edit documents. The left panel displays a tree control that lets you browse through folders. The client calls the objectIds method on Zope folders to get the information needed for this tree. When you click on a document in the left panel the right panel displays its contents. The client retrieves the document contents by calling the document_src method. You can then edit the contents and save your changes to Zope. The client commits the changes using the manage_upload method.
Here's a screen shot of the finished example client.
To try it out and see how it works download the Zope client here.
The example client should run on both Linux and Windows. To install the Zope client on you local machine, first untar and ungzip the ZopeClient.tgz file. If you are using Windows, WinZip should be able to do this. Next you will need Python, wxPython, and xmlrpclib installed on you local machine. Now you're ready to run the example Zope client. See the included README.txt file for more information.