From f077653f208f6f7c89c78c87c2abb0ea7031dbc0 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Wed, 28 Jul 2010 03:00:58 +0000 Subject: - A ``repoze.bfg.events.subscriber`` decorator was added. This decorator decorates module-scope functions, which are then treated as event listeners after a scan() is performed. See the Events narrative documentation chapter and the ``repoze.bfg.events`` module documentation for more information. --- docs/narr/events.rst | 42 ++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 40 insertions(+), 2 deletions(-) (limited to 'docs/narr/events.rst') diff --git a/docs/narr/events.rst b/docs/narr/events.rst index 6ef2e2d5d..7f78139bb 100644 --- a/docs/narr/events.rst +++ b/docs/narr/events.rst @@ -34,8 +34,8 @@ The mere existence of a subscriber function, however, is not sufficient to arrange for it to be called. To arrange for the subscriber to be called, you'll need to use the :meth:`repoze.bfg.configurator.Configurator.add_subscriber` method to -register the subscriber imperatively, or you'll need to use ZCML for -the same purpose: +register the subscriber imperatively, or via a decorator, or you'll +need to use ZCML for the same purpose: .. topic:: Configuring an Event Listener Imperatively @@ -78,6 +78,44 @@ the same purpose: See also :ref:`subscriber_directive`. +.. topic:: Configuring an Event Listener Using a Decorator + + You can configure a subscriber function to be called for some event + type via the :func:`repoze.bfg.events.subscriber` function. + + .. code-block:: python + :linenos: + + from repoze.bfg.interfaces import INewRequest + from repoze.bfg.events import subscriber + + @subscriber(INewRequest) + def mysubscriber(event): + event.request.foo = 1 + + When the :func:`repoze.bfg.subscriber` decorator is used a + :term:`scan` must be performed against the package containing the + decorated function for the decorator to have any effect. See + :func:`repoze.bfg.subscriber` for more information. + +.. topic:: Configuring an Event Listener Through ZCML + + You can configure an event listener by modifying your application's + ``configure.zcml``. Here's an example of a bit of XML you can add + to the ``configure.zcml`` file which registers the above + ``mysubscriber`` function, which we assume lives in a + ``subscribers.py`` module within your application: + + .. code-block:: xml + :linenos: + + + + See also :ref:`subscriber_directive`. + Either of the above registration examples implies that every time the :mod:`repoze.bfg` framework emits an event object that supplies an :class:`repoze.bfg.interfaces.INewRequest` interface, the -- cgit v1.2.3