Product Guidelines (old)

Zope Product Guidelines Last update: 13-01-2000

1. Introduction

   This document intends to set guidelines for Zope products. It's goal is to be a guideline document, not a tutorial or reference. It concerns itself with should and shouldn't, not with how to or how exactly. Ideally this document should refer to the relevant tutorials, examples, and references. For clarity some examples (if short enough) should be contained in this document.

   So, you go to this document when you want to know how to make your product a good one, not to learn how to write a product at all, or to look up something about writing products.

   This document is very new and therefore still a skeleton in most places.

2. User interface
   • Tab conventions

     Standard tab names, how to use them, when to include tabs and when not? There should be a tab test when..

   • Editing

     Use MessageDialog for feedback on update, or blurb on top?

   • Field dimensions

     Size of id field, size of title field, size of common textareas, etc.

   • Background color

     Background color of management interface (#FFFFFF)

   • Icon

     Each addable object should have an associated unique icon of dimensions..

   • Creation form

     A creation form should contain..

   • Edit form

     An edit form should contain..

   • Properties
3. The Zope framework
   1. 1. Base classes

      Initialization of base classes; do or don't initialize by hand..

      • OFS.SimpleItem

        When to use, what to do, what not to do.

      • ObjectManager

        When to use, what to do, what not to do.

        Restricting which objects can be created inside manager.

      • Persistent
      • Acquisition.Implicit
      • AccessControl.Role.RoleManager
   2. 2. Attributes
      • meta_type
      • manage_options
      • __ac_permissions__
   3. 3. Utilities
      • Globals.HTMLFile
      • Globals.MessageDialog
   4. 4. Naming conventions

      Which names to use for your classes methods; when to use the manage_ prefix.

   5. 5. Other
      • When to use .dtml files
      • guidelines on embedding HTML in the Python source
4. Permissions

   When to hide a method, when to show it.

   What methods should have permissions settings (all exposed ones?).

   Standard permissions and how to apply them to your own product.

   • View
   • Access contents information
   • ..

   Testing procedures.

5. Persistence

   When to make an object persistent, when not.

   When to use the ZODB to store instance data, when not (temporary data). Alternatives to the ZODB.

   Make sure your attributes are stored in the ZODB.

   • When Zope does it automatically for you
   • When you have to do it explicitly

   Avoid excessive ZODB writes (and how?).

6. DTML API

   Common supported methods (perhaps this is because of base classes).

   index_html, __call__, __str__, when to use what (if any)

   manage_beforeDelete, other management methods?

   Calling conventions (standard arguments, etc).

   REQUEST: do's and don't's.

   The namespace stack: do's and don'ts.

7. Searching

   Make sure your object can be found (also by ZCatalog).

   Other ZCatalog requirements, suggestions.

8. Various protocols your product should support

   FTP enabling

   WebDAV enabling

9. Performance considerations

   What is the impact of doing things that take a lot of time in your product? How to avoid such negative impact?

10. Direct Traversal

    ?

11. Documentation

    How to use Zope's documentation system.

    When to use docstrings (often!). What docstrings should contain.

    What files to include (README.txt, ..?)