ZCML
====

File naming conventions
-----------------------

ZCML configuration for a package should, in general, be placed in a file
named ``configure.zcml``.  If a package performs meta configuration
(defines new configuration directives), the meta configuration should go
in a file named ``meta.zcml``.  The code that implements the meta
configuration directives should (again, in general) go in a file named
``metaconfiguration.py``.


Style guide
-----------

The ZCML style guide has been developed with the following qualities in
mind:

* Lines under 80 characters wherever possible

* Indentation to reflect nesting

* Ease of maintenance

* Easy visual scanning through ZCML


Tabs and spaces
~~~~~~~~~~~~~~~

All whitespace to be made up of space characters. No chr(9) hard tabs.

Indentation of 2 characters to show nesting, 4 characters to list
attributes on separate lines. This distinction makes it easier to see
the difference between attributes and nested elements.


Logical sections
~~~~~~~~~~~~~~~~

If a configuration file has many logical sections, then mark the
sections with comments and indent the sections relative to the comments.
For example::

    <configure xmlns="http://namespaces.zope.org/zope">

      <!-- Configuration registries -->

      <content
          class="zope.app.services.configuration.ConfigurationRegistry"
          >
        <require
             permission="zope.ManageServices"
             interface="zope.app.interfaces.services.configuration.IConfigurationRegistry"
             />
      </content>

      <!-- Adapter Service -->

      <content class="zope.app.services.adapter.AdapterService">
        <implements

      ...


Namespaces
~~~~~~~~~~

Always use the "usual" names for namespaces in the document:

default (no qualification needed)
    for http://namespaces.zope.org/zope

browser
    for http://namespaces.zope.org/browser

zmi
    for http://namespaces.zope.org/zmi

security
    for http://namespaces.zope.org/security

xmlrpc
    for http://namespaces.zope.org/xmlrpc

whatevername
    for http://namespaces.zope.org/whatevername

Only define those namespaces used in the document. This is a similar
rule to what imports to use in a Python module.


Opening tags
~~~~~~~~~~~~

Close a one-line tag on the same line::

    <class class="Foo">

Close a multi-line tag on a new line, at the same level of indentation
as the tags attributes::

    <browser:pages
        name="index.html"
        class=".index.Index"
        >


Empty tags
~~~~~~~~~~

Close a one-line tag on the same line, insert a space after the last
attribute:::

    <subscriber handler=".foo.OnFoo" />

Close a multi-line tag on a new line at the same level of indentation as
the tag's attributes::

    <browser:page
        name="index.html"
        class=".index.Index"
        />


Closing tags
~~~~~~~~~~~~

Indent closing tags at the same level of indentation as the opening
tags::

    <class class=".foo.Foo">
        ...
    </class>

Attributes
~~~~~~~~~~

If all the attributes fit on one line with the tag name, do that::

    <class class=".foo.Foo">

If all the attribute fit on one line without the tag name, do that on
the line after the tag, indented 4 spaces along from the tag::

    <browser:page
        name="index.html" class=".foo.Foo" permission="zope.View"
        />

Otherwise, put the first attribute on a new line, and use one line per
attribute::

    <browser:page
        name="index.html"
        class=".foo.Foo"
        permission="zope.View"
        template="foo.pt"
        />

Use double quotes for attributes unless single quotes are needed to
enclose double quotes.


Comments
~~~~~~~~

Comments should be placed immediately above the declarations they apply
to. Keep comments to one line where possible, and open and close the
comment on the same line.