Hi!
CMF 1.6 and 2.0 will ship with the same version of GenericSetup. It
consists of three major components:
1.) Setup tool and profile registry
-----------------------------------
Setup profiles are either registered with the global profile registry or
stored persistently in the local setup tool. The setup tool provides an
user interface for importing, exporting and comparing profiles from both
sources.
There were not many changes in this area, it works almost the same way
as in CMF 1.5's CMFSetup. Backwards compatibility code makes sure that
setup tools created with CMFSetup still work with GenericSetup.
2.) Content setup sub-framework
-------------------------------
This is a new feature in GenericSetup.
Tres has been working on this, I can't provide details.
3.) Configuration setup sub-framework
-------------------------------------
This CMFSetup functionality is completely rewritten using Five/Zope 3
features. Major goals of the refactoring were:
- Making setup handlers pluggable, allowing add-on products to handle
the setup of custom type info, catalog index or workflow classes.
- Making setup handlers reusable. Basically they are serializers /
deserializers which are useful for other tasks as well.
Coming closer to beta I believe this sub-framework is now stable enough
to write some documentation and to encourage people to start using it
and to give feedback. Here is I first cut of a how-to:
How-to: Writing setup handlers for GenericSetup (draft)
=======================================================
If your products subclass existing tools or provide new tools (or new
sub-object classes) they might need their own setup handlers in order to
make use of GenericSetup.
Step 1:
-------
Identify those classes in your product that need their own setup
handlers. In theory you don't need your own handlers for classes which
implement an CMF tool interface that already has a setup adapter. In
practice the adapters shipped with the CMF sometimes use methods that
are not part of the interface, so you have to verify they really work
for your classes.
Step 2:
-------
Make sure those classes that need setup handlers have Zope 3 style
interfaces. Later you will write setup adapters for those interfaces.
Step 3:
-------
Create an 'exportimport' module inside your product. If you plan to
write many setup handlers this can be a sub-package.
Step 4:
-------
Decide which kind of setup handler you need:
a) 'body adapter':
For objects represented by a complete file body. Provides IBody.
b) 'XML adapter':
'body adapter' in XML format. Also provides IBody, but has its own base
class because XML is the preferred format.
c) 'node adapter':
For sub-objects represented by an XML node of the parents XML document.
Provides INode. This is useful for sub-objects of complex tools. Custom
catalog index or action classes need that kind of adapter.
d) 'import and export steps':
Top level handlers that can be registered as import step or export step
and call the body adapters. I hope these will become obsolete for tools,
but currently they are required.
If you use the base classes from GenericSetup.utils, XML and node
adapters are implemented in a very similar way. Both can mix in
ObjectManagerHelpers and PropertyManagerHelpers.
Step 5:
-------
CMFCore.exportimport contains many examples for XML and node adapters.
If you need a pure body adapter, GenericSetup.PythonScripts would be a
good example. Follow those examples and write your own multi adapter,
register it for the interface of your class and for ISetupEnviron and
don't forget to write unit tests.
Adapters follow the convention that 'self.context' is always the primary
adapted object, so the minimal setup context (ISetupEnviron) used in
these multi adapters is 'self.environ'.
XML and body adapters are always also small node adapters. This way the
XML file of the container contains the information that is necessary to
create an empty object. The handler of the container has to set up
sub-objects before we can adapt them and configure them with their own
handlers. The base classes in GenericSetup.utils will care about that.
Step 6:
-------
If your adapter is a top-level adapter (e.g for a tool), you need import
and export steps that know how to use the adapter. Again there are many
examples in CMFCore.exportimport.
To make those steps available you have to add them to export_steps.xml
and import_steps.xml of a setup profile and to load that profile into
the setup tool.
Step 7:
-------
Now you are done. To ship default settings with your product, make your
settings through the ZMI (or set your stuff up the old way if you have
old setup code like an Install.py) and export your settings using the
setup tool.
Any kind of questions and feedback are welcome.
Cheers,
Yuppie
_______________________________________________
Zope-CMF maillist - Zope-CMF@lists.zope.org
http://mail.zope.org/mailman/listinfo/zope-cmf
See http://collector.zope.org/CMF for bug reports and feature requests
