[Zope] Z Classes Tutorial: Rough Draft
Amos Latteier
Amos@digicool.com
Thu, 6 May 1999 17:28:22 -0400
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!