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.