[BlueBream] ZAM Demo Documentation

[Christopher Lozinski]

There are a number of people interested in ZAM, and a lot of discussion
about a new ZMI, even an upcoming sprint so I am trying to do my part to
get zam.demo installing correctly.  Of course the error message was
completely incomprehensible, I did not have the context.  So step 1 is
to figure out how ZAM works.  I went to read the source code.  Very
nicely documented.  Thanks to the authors.   But there is no high level
documentation, so I wrote this user level document.   Writing this
helped me understand ZAM better.  And in general I think a great way for
new developers to work with Zope is to write documentation, because then
it helps us understand what we are doing, makes it easier to get
feedback,  and smooths the path for those coming after us.

So here is where I left off six months ago.
https://mail.zope.org/pipermail/zope-dev/2011-June/043089.html

What follows is the updated version.  

ZAM User Documentation.

ZAM is a browser based interface to BlueBream.  It allows us to interact
with the running BlueBream server. It provides three types of services. 
Administration services tell you about the Unix processes, and the ZODB
databases.  Error services tell you about server errors which have
occurred.  Hierarchy services allow one to interact with the ZODB
hierarchy of objects. 

ADMINISTRATION SERVICES (zamplugin.control)
 
This wepage has links to runtime information, ZODB information, Generations, and Registration. 
To access it you go to 

http://localhost/++skin++ZAM/++etc++ApplicationController/index.html

The runtime information includes the following:  Uptime, System platform, 
Zope version, Python version, Command line used to start the server, 
Preferred encoding, Process id, Developer mode on or off, and the Python path
   
ZODB control includes a list of ZODB databases, their file system name, current size, and the 
ability to pack them, keeping up to X number of days of version.  

Generations describes the versions of ZODB schemas, and is a way of updating the objects 
as the schema changes.  Impressive! 

Registrations allow objects to be registered as adaptors or user interfaces.  This is a complex 
topic which requires an understanding of the Zope Component Architecture.  In general beginners
do not need to worry about this. 


ERROR SERVICES (zamplugin.error)

You can see the error logs here.

http://localhost/++skin++ZAM/++etc++site/default/RootErrorReportingUtility 

Looks very nice, much like the Zope 2 error reports. You get Time, User,and exception.  
You can click on the exception for more details, the Request URL, Traceback, user permissions, 
and the full REQUEST object. 


HIERARCHY SERVICES (zamplugin.sitemanager, zamplugin.navigation)

Bluebream stores objects in the Zope Object Database.  Objects are stored in a tree.  
The  allows one to navigate the tree, browse objects, cut, copy, paste, 
and rename those objects.  In the current version, when enabled, it is possible to 
add objects to the tree. In future versions this may also require developer permisssion. 

I am not sure which part of the interface is handled by the site manager, and which part is 
handled by navigation.  

zamplugin.sampledata From pypi: "A sample data generator is a pluggable
tool to create data needed for tests."  Not really sure what this does either. 


If you want to learn more about ZAM, go into the source code.  Go into the eggs 
directory and type

more zam*/zam*/*/README.txt

That gets you all of the source code docs. 

There are several different sections.  

There is zam.api which provides the core functionality. There is
the best README.txt in this section. It explains the ZAM plugin framework.  
You can add or remove a plugin, but obviously only once.  It talks about a base 
registry plugin.  They talk about the layers model. Layers are all 
about the stuff in the skin, described below. 

zam.skin contains all the "HTML, JS, CSS and image components"

The other directories correspond to the user interfaces described above.  


QUESTION:  So where should i put this documentation? 

My next step is to try to run zam.demo again, and see if the error
message makes any more sense to me than it did this morning.

-- 
Regards
Christopher Lozinski

Check out my iPhone apps TextFaster and EmailFaster
http://textfaster.com

Expect a paradigm shift.
http://MyHDL.org