Technical overview

So you want to start using cromlech / dolmen, but you need the big picture

Cromlech or Dolmen

Cromlech is the namespace of packages providing underlying technical packages (say technical infrastructure) while Dolmen provides more framework level packages.

Environment

Cromlech / dolmen application try to be fair players in the python world and it also borrow lots of bits from ztk.

Cromlech applications are meant to be WSGI applications.

Cromlech also use transaction (from zope) to manage transactions.

Crom and underware

Cromlech itself lies above some libraries, providing mechanism for declarations and configuration.

Crom and Grokker are at the heart of the declarative mechanism. They relies on Venusian and zope.interface

Venusian comes from pyramid and permits to use decorators as directives that will be harvested at start time.

Grokker harvest venusian directives and gives them to special components named grokkers (yes they are the equivalents of grok ones) which use them to setup configurations, mostly, but not only, in the registries of Crom.

Crom use zope.interface registry mechanism but providing new ways of querying them. It is a replacement for zope.component, which aims to be more generic, giving more flexibility in registry use.

Thanks to Crom grokkers shall be able to register utilities, adapters, handlers and such objects in a way very close to the ZCA (Zope Component Architecture).

Cromlech stack

At the heart of the Cromlech stack is cromlech.browser. It mostly defines interfaces (hence the api) representing the different actors of a browser request / response.

Then comes some implementations of such parts.

cromlech.webob
provides an implementation of the request and response object based on webob
cromlech.dawnlight
provides an object publishing mechanism (aka routing of request) [1] using dawnlight, a flexible object traverser.
cromlech.beaker
implements a session mechanism using Beaker
cromlech.events
implements events through zope.interfaces handlers and declares some comon events (inspired by zope.lifecycleevent
cromlech.i18n
implements internationalization (i18n) using translationstring that is negociating language with browser and making it available to application.

And more packages dedicated to specific domains:

cromlech.file
Defines interfaces and an implementation for files objects be it incoming files in request, or files stored in some database.
cromlech.security
Gives base interface and implementation for a permission based security policy
cromlech.sqlalchemy
is a package providing connectivity to SQL databases through SQLAlchemy, using transaction management thanks to zope.sqlalchemy
cromlech.zodb
is a package providing connectivity to ZODB
cromlech.content
defines IContent (an object which is a content) and IFactory (inversion of control to create content) and directives like schema (declaring content attributes).
cromlech.container
defines IContainer (the container interface) and some directives to declare containments with a very basic implementation.
cromlech.location
base upon zope.location, it defines location by containment of objects. A published object has a __name__ and __parent__, which may depends on the way it was retrieved. This also permits to compute an object url.

Some packages are in an undefined state:

  • cromlech.wsgistate aims at integrating wsgistate which may be a candidate for replacement of beakers (the latter do not play well with transaction).

Cromlech did evolve from a preview version to the Crom actual version so you may find some packages lying around.

  • cromlech.grok and cromlech.configuration adds supports for ZCML files using zope.configuration and supportig grok directives inside them.

  • cromlech.io at the old days, this was a subpart of cromlech.browser

  • cromlech.registries aims at

    playing with multiple registries in zope.component before Crom exists.

  • cromlech.wsgi some utilities for wsgi that are not so useful !

  • cromlech.session is a yet to come attempt to have sessions plays nicely with transactions (fixme ?)

Dolmen packages

rendering

dolmen.layout
Layout is an important concept for most website, it defines the frame around your content, that is footer, header, but also common scripts, additionnal columns with contents.
dolmen.view
View is the renderer for an object. Some times it will provide the main part in a layout, but can be standalone. For example, if you call the display view of an object it will give you informations about it and if you call the edit view of your object it may be a form to modify it.
dolmen.viewlet
Aside from main view lots of part of a pages are reusable and depends upon displayed content, users right and so on. They are called viewlets. The layout defines plugs for viewlet managers (also called content providers) which in turn gathers viewlets (pieces of html) in a certain way.
dolmen.template
Defines the templating components and provide an implementation using Chameleon
dolmen.tales
Adds some tales expressions and statements to Chameleon for use with dolmen.template. Especially, it provides the expressions responsible for gathering content providers (aka viewlet managers).

helpers

dolmen.menu
Utilities to declare menu entries and render menu. Decorators helps you quickly add a menu entry for a specific view while you may also define more complex menu entries through classes.
dolmen.container
This is a simple integration of cromlech.container with ZODB
dolmen.message
This is a simple messaging utility. Typical use include displaying messages to the user on pages.

forms

Dolmen contains several packages to handle forms. Those set of libraries are based upon Zeam-Form but have diverged to remove zope dependencies.

Core packages are:

dolmen.collection
provides an implementation of a collection of items, with nice semantics.
dolmen.forms.base
provides components to create forms. The main concepts are the form (the view), its fields and widgets, the action (the controller), data extraction, error handling.
dolmen.forms.ztk
integration of zope.schema which defines declarative fields
dolmen.forms.crud
A handy package that provide CRUD (Create, Read, Update and Delete) forms for objects providing a schema (aka contents).

Some more features are provide by other packages:

dolmen.forms.table
helps you designing forms that are tables, be it for batch modifications, or just listings with simple actions.
dolmen.forms.viewlet
for forms which are not the main content of your page but are reused over a site aside contents.
dolmen.forms.composed

Forms composed of multiple sub-forms.

not yet available

dolmen.forms.events

just provide a FormActionResolvedEvent so that third parts maybe notified of a form being processed. Tipical use include logging form use.

not yet available

Managing dependencies

As Cromlech comes as a lot of bits, you necessarily have to use something to manage dependencies. You may choose pip but Cromlech normally use buildout which offers higher level features.

Note

link packages to their official pypi pages as they are published

[1]if you do not understand this concept see http://docs.zope.org/zope2/zope2book/ZopeArchitecture.html#object-publishing