[Zope-CVS] CVS: Products/Ape/doc - ape.txt:18.104.22.168
Tue, 29 Jul 2003 18:15:09 -0400
Update of /cvs-repository/Products/Ape/doc
In directory cvs.zope.org:/tmp/cvs-serv6333
Started documentation on the configuration vocabulary.
=== Added File Products/Ape/doc/ape.txt ===
Ape Configuration XML
Ape configures mappers using configuration files. The standard Zope 2
mapper configuration is in the file 'apeconf.xml' in the
'apelib.zope2' package. Look over the standard configuration file to
get a feel for what the file does.
Ape lets you mix configurations from any number of configuration
files, as long as none of the files contain conflicting directives.
To add support for a new class to Ape, write your own 'apeconf.xml'
rather than modify the standard configuration. If you're writing a
Zope product, place your 'apeconf.xml' in your product directory. Ape
will look for it and mix your configuration with the standard
The Ape configuration schema is fairly simple. The root
'configuration' tag contains component declarations. Component
declarations contain component-specific configurations and
registrations. Variation tags are intermingled with the other
configuration directives, allowing a configuration file to define
variations of the standard configuration.
The schema uses two conventions that differ from most XML schemas.
First, 'variation' elements may appear anywhere; see the description
of the 'variation' element. Second, most attributes and child
elements are optional, allowing minimal declarations.
The root element of an Ape configuration file. Uses no attributes
at this time.
The variation tag signifies that all contained directives belong
to a variation rather than the standard configuration. A
variation element may appear anywhere in the file, as long as the
variation element is a descendent of the configuration element.
Variation tags let you specify multiple configuration variations
in a single file, keeping independent configurations together in a
logical way. Ape uses variations to keep 'apeconf.xml' clear
while providing alternative configurations.
The 'name' attribute is required. It specifies which variation
the child directives belong to. Placing many directives in a
single variation tag is equivalent to splitting those directives
into several variation tags of the same name.
Directives within a variation tag become part of a varied
configuration rather than the standard configuration. A
configuration file can modify any number of variations.
Directives outside any variation tag become part of the standard
configuration. When Ape loads a mapper, it specifies which
variation it needs, then the configuration machinery combines
directives from the variation with the standard directives.
Ape uses variations to configure both a SQL and filesystem mapper
in the same file. Before Ape used XML, it used three Python
modules to configure mappers: a base mapper, a filesystem
variation, and a SQL variation. The three separate files made it
difficult to understand how to configure a mapper, and in fact
introduced minor errors that went unnoticed for a long time. A
single XML file containing multiple variations turned out clearer
and shorter than equivalent Python code.
Declares a mapper component. The 'name' attribute is required and
usually specifies a module-qualified class name. The rest of the
attributes are optional. A mapper element should be a direct
child of either a 'variation' or a 'configuration' element. A
mapper element may contain the following child elements, all
Ape mixes mapper configurations based on the mapper name. One
configuration file can define a mapper while another adds an extra
serializer, for example, as long as the two configurations do not
The 'class' attribute specifies the class the mapper is to be used
for. If no 'class' attribute is associated with a mapper, Ape
defaults to using the mapper name as the class name. Since most
mappers are used for exactly one class and are named according to
that class, you can generally omit the 'class' attribute.
There are a few situations where you should specify a 'class'
attribute. Ape recognizes two special values for the 'class'
attribute, 'none' and 'any'. Use 'none' for abstract base mappers
designed to be extended but never used directly. Use 'any' for
mappers designed to work with any class (see the 'anyfile' and
'anyfolder' Zope 2 mappers.) Also, if you're using multiple
domain mappers, you may need to apply a class to different mappers
depending on the context. To do this, set the class attributes
for both mappers to the module-qualified class name, but use
different mapper names.
The 'extends' attribute tells Ape to inherit gateways,
serializers, a classifier, and a keychain generator from a base
Internally, Ape interprets a mapper element as several directives.