> 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
