> Maybe there's some potential to create a set of core ZCML registration 
> handlers
> for utility, adapter, subscriber, and interace that are not actually part of
> BFG, but on which BFG and other non-Zope apps could depend.  I suspect this is
> the only realistic way to go forward: I don't think it's reasonable to tell 
> the
> people who have Zope apps in production which use these declarations that they
> won't be able to use untrusted code or permission declarations, or the global
> registry.

In that spirit, here is the first cut at some documentation for a package I'm
now working on.  Comments appreciated...

Documentation for repoze.zcml
=============================

:mod:`repoze.zcml` is a package which provides core ZCML directives
for the Zope Component Architecture (particularly, ``utility``,
``subscriber``, and ``adapter``).

Note that ``zope.configuration`` already *has* implementations of
handlers that allow similar directives to work.  You should only use
the ``repoze.zcml`` versions of these directives if your application
doesn't need the more advanced features of the "stock" directive types
of the same names present in ``zope.configuration``.  The "stock"
implementations use the concepts of "permissions", and "trusted"
adapters and utilities.  In most applications, these features are
unnecessary, and exposing them to users may be harmful.  Using
``repoze.zcml`` in this case makes it possible to use ZCML with fewer
Zope Python packages as dependencies, and removes the possibility that
your users will attempt to use these advanced features without any
understanding of what they do.

.. note:: The effect of ``repoze.zcml`` directives is exactly
   equivalent to the effect that the "stock" directives would have,
   save for the omission of more advanced features.

:mod:`repoze.zcml` contains "meta" ZCML that can be included within
your application's ZCML that makes certain directives work (listed
below).  After this meta ZCML is loaded, you can use the directives.

For an overall description of the concepts backing the directives
defined within :mod:`repoze.zcml`, see `A Comprehensive Guide to Zope
Component Architecture <http://www.muthukadan.net/docs/zca.html>`_.

Usage
-----

To make use of :mod:`repoze.zcml`, you should install the
:mod:`repoze.zcml` package, then subsequently include its "meta.zcml"
from within some ZCML that is used by your application::

  <include package="repoze.zcml" filename="meta.zcml"/>

Thereafter, you will be able to use the directive types it defines
within your ZCML.

The directives defined in :mod:`repoze.zcml` are defined within the
namespace ``http://namespaces.repoze.org/zcml``.  Therefore to use any
of the :mod:`repoze.zcml`-defined directives without a
namespace-qualified name, you should write your ZCML like so:

.. code-block:: xml

  <configure xmnls="http://namespaces.repoze.org/zcml";>

    <adapter
       factory="some.package.Foo"
       provides="some.package.IFoo"
       for="some.package.IBar some.package.IBaz"
       name="myadapter"
       />

  </configure>

On the other hand, if you want to use these directives with a
qualified name within another application that already has a default
``xmlns``, you can do so by adding a different XML namespace to the
``configure`` tag::

  <configure xmnls="http://namespaces.zope.org/zope";>
       xmlns:zcml="http://namespaces.repoze.org/zcml";>

    <zcml:adapter
       factory="some.package.Foo"
       provides="some.package.IFoo"
       for="some.package.IBar some.package.IBaz"
       name="myadapter"
       />

   </configure>

Directives
----------

*adapter*
  The ``adapter`` directive registers an adapter within the component
  architecture registry.

Example:

.. code-block:: xml

   <adapter
     factory="some.package.Foo"
     provides="some.package.IFoo"
     for="some.package.IBar some.package.IBaz"
     name="myadapter"
     />

.. directive:: .. factory

   The factory which creates an adapter (dotted name).

.. directive:: .. provides

   This implies the interface that the adapter provides (dotted name).

.. directive:: .. for

   This implies the interface(s) which the adapter is "for".  (One or
   more dotted names).

.. directive:: .. name

   The name by which the adapter should be looked up.

*utility*
  The ``utility`` directive registers a utility within the component
  architecture registry.

Example:

.. code-block:: xml

   <utility
     factory="some.package.Foo"
     provides="some.package.IFoo"
     name="myutility"
     />

.. directive:: .. component

   Describes the component registered as the adapter.  This attribute
   is mutually exlusive with the ``factory`` attribute.

.. directive:: .. provides

   Describes the provides interface for an adapter.

.. directive:: .. for

   Describes the for interface(s) for an adapter.

.. directive:: .. name

   Describes the name of the adapter.

*subscriber*
  The ``subscriber`` directive registers an event subscriber within
  the component architecture registry.

Example:

.. code-block:: xml

   <subscriber
     handler="some.package.myhandler"
     provides="some.package.IFoo"
     for="some.package.IBar"
     />

.. directive:: .. handler

   The handler for the subscriber.  This is a subscriber which does
   not require a factory.  This attribute is mutually exclusive with
   the ``factory`` directive.

.. directive:: .. factory

   The factory which creates an subscriber (dotted name).  This
   attribute is mutually exclusive with the ``handler`` directive.

.. directive:: .. provides

   This implies the interface that the subscriber adapter provides
   (dotted name).

.. directive:: .. for

   This implies the interface(s) which the subscriber adapter is
   "for".  (One or more dotted names).

Indices and tables
------------------

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

> 
> - C
> 
> 
> _______________________________________________
> Repoze-dev mailing list
> Repoze-dev@lists.repoze.org
> http://lists.repoze.org/listinfo/repoze-dev
> 

_______________________________________________
Repoze-dev mailing list
Repoze-dev@lists.repoze.org
http://lists.repoze.org/listinfo/repoze-dev

Reply via email to