Hello Zope Fans: Here's the first rough draft of a Z Classes Tutorial. Take a look and let me know what you think. Please note that Z Classes are an *experimental feature* of Zope at this time. We debated about whether to make a release now or wait until Z Classes were more fully cooked (and until we had more bandwidth to answer questions about Z Classes). We decided to make a release now. I think that if you play with Z Classes you'll agree that they represent a very exciting development. Have fun, and send me your feed back on the tutorial, I'd love to improve it. -Amos -- Introducing Z Classes About this document Z Classes are an exciting addition to Zope which made their debut in the 1.11 release. This document is an introduction to using and understanding Z Classes. This information will be added to the Zope Manager's Guide soon. Important Warning *IMPORTANT NOTE: Z Classes are currently (as of Zope 1.11.0pr1) an experimental, unsupported feature in Zope.* Bugs still exist in the current Z Classes implementation. In addition new features will probably be added and existing features may be changed in the near future. We fully intend to make Z Classes rock solid, but we're just not there yet. Introduction What are Z Classes? Z Classes herald a big change in Zope. Classes allow you to build your own objects through the web. In effect, instead of being limited to existing objects like Folders, DTML Documents, when building your site, you can now define your own objects. For example, if your site includes things like employee manuals, bug reports, shopping malls, etc., then you can actually create Employee Manual objects, and Bug Report objects, and all the rest. In short, Z Classes let you create and store "your kinds of things" instead of Zope things. You define your Classes in the Control Panel, and then you can create and manipulate your objects just as you create and manipulate Folders, DTML Documents, and all the other standard Zope objects. As you change and update your Classes, all the existing instances of those classes are updated. So if you add a new method to your Employee Manual class, all your Employee Manual objects will be updated. You can even export your Classes and use them in different Zope installation, thus allowing you to leverage your work across Zope installations. Basically Zope classes make extending Zope much easier. In fact there is no Python programming required. This is a big change from the days of using the Product API and Python to extend Zope. Now building new Classes is easy enough that you justify making several specialized Classes to solve specific problems. Necessary Background To start with you should be familiar with creating Products though the Zope Control Panel. This process is outlined in the Zope Manager's Guide. http://www.zope.org/Documentation/Guides/ZMG/ Working with Zope classes builds on Zopes existing Product Creation facilities but extends it in important ways. The basic difference between creating traditional Products through the Control Panel and creating Z Class Products through the Control Panel is that with Classes, your objects retain a connection to their Classes. So when you make changes to your Class, your instances are updated. With traditional Control Panel Products, no such link between the Control Panel and the created object is retained. Getting Started Overview Let's begin using ZClasses by building a simple example Class that represent a music CD. In this scenario, we want to let people fill out forms that collect information about CDs in their music collection. To create new "records", people just choose your newly-defined "thing" from the kinds of "things" to add to their folder. Overview of Steps 1. Create a Z Class. 2. Provide some meta-information about the Z Class. 3. Define a property sheet for the Z Class. 4. Create a View. 5. Create a Factory. Creating a Simple ZClass Start by going to the Control Panel and creating a new Product. Choose "Product" from the add form and call it 'CDProduct'. Now go the the 'CDProduct' Product Folder and create a ZClass. For the Class 'id' specify 'CDClass'. Don't worry about the 'Selected Base Classes' widget. Click 'Add', and you've just created your first ZClass. Now let's set up our newly minted CD Class. Click on the 'CDClass' object inside the 'CDProduct' Folder. Now you are presented the the 'Basic' Class management screen. For now let's restrict ourselves to just supplying a 'meta-type' for our class. For the Class 'meta-type' specify 'CD'. 'meta-type' basically means Zope Product type. Creating a PropertySheet Now let's give our Class some properties. We can do this by creating one or more PropertySheets for our Class. A PropertySheet is a schema that describes what kind of properties instances of our Class will have. To create a PropertySheet click on the 'PropertySheets' tab. This takes you to the PropertySheets management screen. Let's create a PropertySheet by selecting 'Common Instance Property Sheet' from the Product add list. Then specify 'cd_info' as the id of the PropertySheet. Now you should have a new PropertySheet object listed on the PropertySheets management screen. Click on 'cd_info' to edit our PropertySheet. Now you should see a familiar Zope property setting management screen. It's important to remember that right now we are not setting the properties of an individual CD, but we are defining what properties which all CDs will have. So let's create a few properties. Create a 'title' and 'artist' property, both of type string. Then create a text property named 'description'. Creating a View Now let's add a View to our class which will let use manage these properties. A View is a management screen which is available via a management tab. Click the 'Views' tab to edit a Class's views. Now you should see that our Class currently has only one View, 'Security'. This view calls the Class's 'manage_access' method. Let's create a new view named 'Properties' which calls the Class's 'propertysheets/cd_info/manage' method. Fill out the 'New' form and then click 'Add'. Now you should see that our class has two Views. Let's make the 'Properties' View the first or default view by checking the checkbox next to it and clicking 'First'. Now Properties should be at the top of the list of Views. Creating Instances of the ZClass So far so good. We've created all the basic stuff we need to get our class working. Now we need to create a way to make instances of our Class. This process is basically identical to what is described in the Zope Manager's Guide. We'll need to build an add form and then create a Factory which will make our add form available from the Product add list. Let's build a very basic add form. Go to the 'CDProduct' Folder and create a new DTML Method. Give it an id of 'addForm' and give it these contents:: <!--#var standard_html_header--> <H2>Add CD</H2> <table> <form action="CDClass"> <tr> <th>Id</th> <td><input type="text" name="id"></td></tr> <tr><td></td><td><input type="submit" value="Add"></td></tr> </form> </table> <!--#var standard_html_footer--> This DTML Method basically displays a form which gathers the CD's id and then calls the Class. The Class will create an instance and plug it into the Folder from which the add method is called. The final step is to create a Factory to put this add form into the Product add list. Choose 'Zope Factory' from the Product add list and create a Factory with id 'CDFactory', add list name 'CD' and method 'addForm'. OK, now you should be able to create a CD object from most anywhere in Zope, by selecting 'CD' from the Product add list and filling out the add form. Using ZClass Instances. To find out more about our Class, let's explore an instance. Leave the Control Panel and create a CD object. Now click on the CD object you just created. You'll note that you can edit the CD's properties with the 'Properties' tab. You can also access your object's attributes via DTML. For example, suppose you created a CD object called 'SuperOldies_vol42'. In a DTML Document you can query this object like so:: <p>Information about a CD:</p> <!--#with SuperOldies_vol42--> <p>Title: <!--#var title--></p> <p>Artist: <!--#var artist--></p> <p>Description: <!--#var description html_quote newline_to_br--></p> <!--#/with--> In other words, your CD object is a normal Zope object and you can access its properties just like you access a Folder's properties. You can also manipulate its properties in the same way you manipulate the properties of other Zope objects. For example, here's a DTML fragment that changes some properties of our CD object:: <!--#call "SuperOldies_vol42.manage_changeProperties({ 'title' : 'Super Oldies volume 42', 'artist' : 'Various Artists', 'description' : 'Greatest hits of many has beens.' })"--> Instances of ZClasses inherit all the methods of their base classes. In our simple example, our CD class inherits the basic methods available to all simple Zope Products automatically without having to specify this. More Complex ZClass Topics Now that we have a basic example of a working ZClass, let's return to some of the details that we glossed over the first time. Basic ZClass Attributes On the 'Basic' ZClass management screen you can set the Class's icon in addition to defining a ZClass's 'meta-type'. This icon is used in the Zope management interface to identify instances of the ZClass. You should use a GIF file for your icon which is 16 by 16 pixels. It should have a transparent background. You can set a Class's icon by uploading the icon file. This will create the icon and define the icon's URL. You can change the icon by uploading new icon files. If you need to, you can change the URL of the icon, but in general this shouldn't be necessary. ZClasses and Inheritance When you first create a ZClass you are presented with a complex widget which allows you to specify your Class's base classes. You ZClass inherits the methods and attributes of all its base classes. If you do not specify any base classes your class will still inherit basic Zope features which are defined by the 'SimpleItem' class. This is generally what you want, and this allows instances of your class to perform normal Zope functions such as properties management. If you want your Class to be able to contain other objects, like a Folder does, then you'll have to subclass 'Object Manager'. This will provide you with all the standard methods to support object containment. Other base classes may be available in the future. You can also subclass other ZClasses. This is a very powerful feature. It allows you to build complex and related classes. Another thing to notice is that you can subclass more than one base class. This is one way in which Python differs from many other object-oriented languages. When you subclass more than one class, the order of the base classes is important, because it determines the order in which classes are searched when acquiring method and attributes. Creating Methods A Class's heavy lifting is done by its methods. In addition to defining a property schema, your main task in crafting a ZClass will be to build a collection of methods which manipulate your Class's properties and do useful work. To create methods for your Class, you simply create objects in the 'Methods' tab management view. For the most part your methods will consist of DTML Method objects, SQL Method objects and External Method objects. These Zope objects will provide all instances of your Class with services just as they would provide services to their enclosing Folders if they were not defined as ZClass methods. In other words, there is nothing new or unusual about method objects--they are simply made available to Class instances through the ZClass rather than through acquisition. One useful method to create is the special 'index_html' method which is used to display an object when called from the web. Just as Folder's manage their default view with an 'index_html' object, so you can control the default representation of your class. For example our CD class might define a DTML Method 'index_html' like so:: <!--#var standard_html_header--> <h2>CD</h2> <p>Title: <!--#var title--></p> <p>Artist: <!--#var artist--></p> <p>Description: <!--#var description html_quote newline_to_br--></p> <!--#var standard_html_footer--> Creating Views We've already covered almost all there is to creating Views. The only thing to add is that by default your ZClass starts with the same views as its subclasses. Creating Permissions Zope manages security though a system of permissions and roles. Users are assigned roles which are in bound to permissions for given objects. See the Zope Managers Guide for more information about security. For our purposes, you should understand that a Class's permissions define collections of methods which are grouped together in functional groups. Using Classes your job is not to set access controls on your Class, but to define permissions so that access controls can be set on instances of your Class. So you must define to permissions before they can be bound to roles. The first step in defining your Class's permissions should be to to create methods for your class. After your class can do something, then you should decide how to describe what it can do in terms of permissions. You must figure out if your methods should be covered by existing permissions of whether it would be better to create new permissions. For example if your class has an 'index_html' method, this method is used to view instances of the class, so you can probably use the existing 'View' permission with this method. If your class defines a number of methods for accessing remote servers, you might want to create a new permission for these methods called something like 'Access remote server'. To control what permission a given method is bound to, click the 'Security' tab while managing the Class's permission. You will be presented with a form which maps the method's permissions to the Class's permissions. This looks complex but in general you will only want to bind one permission of the method to a permission. In the case of DTML Methods this will be the 'View' method. The reason for this is that you really only want instances of your class to be able to 'View' a DTML Method. An instance should not be able to perform other actions on its methods such as editing. By going to the 'Permissions' management tab you can define your Class's permissions. You can create new permissions with the 'Add a new permission' form, and you may delete existing permissions. In general you should limit the number of new permissions you create, to the smallest reasonable number. By doing so you make it easier for managers to control the security settings of instances of your Class. Subobjects If you create an a ZClass which is a subclass of 'Object Manager' you'll be able to control what types of objects it can contain. The task is performed by clicking the 'Subobjects' management tab. From this management screen you can select object types which can be added to instances of your Class as subobjects. If the 'Objects should appear in folder lists' option is checked then instances of the class will appear expandable in the Zope management interface. In general this option is appropriate when you wish to make your object act like a normal Zope container. Conclusion The information here should be enough to get you going with Z Classes. We hope to expand this documentation soon and include much larger examples to show how you can build systems with multiple Z Classes that work together. Have fun!