[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!