[Zope-CVS] CVS: Products/Ape/doc - ape.txt:1.1.2.1

Shane Hathaway shane@zope.com
Tue, 29 Jul 2003 18:15:09 -0400


Update of /cvs-repository/Products/Ape/doc
In directory cvs.zope.org:/tmp/cvs-serv6333

Added Files:
      Tag: ape-scan-branch
	ape.txt 
Log Message:
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
configuration.

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.


Elements


  <configuration>

    The root element of an Ape configuration file.  Uses no attributes
    at this time.


  <variation name="...">

    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.


  <mapper name="..."
          class="..."
          parent="..."
          extends="...">

    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
    optional:

      serializer
      gateway
      use-for
      option
      classifier
      keygen
      variation

    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
    conflict.

    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
    mapper.  
    



    Internally, Ape interprets a mapper element as several directives.