How to add event hooks to your Plone code to perform actions when something happens on a Plone site.
- Registering an event handler
- Firing an event
- Event types
- Asynchronous event handling
- See also
This document briefly discusses event handling using the
The Zope Component Architecture's
zope.event package is
used to manage subscribeable events in Plone.
Some of the notable characteristics of the Plone event system are:
- it is simple;
- subscriber calling order is not modifiable — you cannot set the order in which event handlers are called;
- events cannot be cancelled — all handlers will always get the event;
- event handlers cannot have return values;
- exceptions raised in an event handler will interrupt the request processing.
Plone events can be scoped:
- globally (no scope)
- per content type
In your.product/your/product/configure.zcml insert:
<subscriber for=".interfaces.IMyContentTypeClass zope.lifecycleevent.IObjectCreatedEvent" handler=".your_python_file.your_method" />
The first line defines to which interface you want to bind the execution of your code, which means here, that the code will only be executed if the object is one of your contenttype's. If you want this to be interface-agnostic, insert an asterix as a wildcard instead.
The second line defines the event on which this should happen, which is here 'IObjectCreatedEvent' -- for Archetypes you should use 'Products.Archetypes.interfaces.IObjectInitializedEvent' instead. For more available possible events to be used as a trigger, see event handler documentation
The third line gives the path to the script that is supposed to be executed.
Create your.product/your/product/your_python_file.py and insert:
def your_method(object, event): # do sth with your created contenttype
- For Dexterity-contenttype's and additional ZOPE-Illumination see also:
- event handler documentation
Subscribing to a global event using ZCML.
<subscriber for="Products.PlonePAS.events.UserLoggedOutEvent" handler=".smartcard.clear_extra_cookies_on_logout" />
For this event, the Python code in
smartcard.py would be:
def clear_extra_cookies_on_logout(event): # What event contains depends on the # triggerer of the event and event class request = event.object.REQUEST ...
Custom event example subscribing to all
IMyEvents when fired by
<subscriber for=".interfaces.IMyObject .interfaces.IMyEvent" handler=".content.MyObject.myEventHandler" />
Life cycle events example:
<subscriber zcml:condition="installed zope.lifecycleevent" for=".interfaces.ISitsPatient zope.lifecycleevent.IObjectModifiedEvent" handler=".content.SitsPatient.objectModified" />
The following subscription is valid through the process life cycle. In unit tests, it is important to clear test event handlers between the test steps.
import zope.component def my_event_handler(context, event): """ @param context: Zope object for which the event was fired. Usually this is a Plone content object. @param event: Subclass of event. """ pass gsm = zope.component.getGlobalSiteManager() gsm.registerHandler(my_event_handler, (IMyObject,IMyEvent))
zope.event.notify() to fire event objects to their subscribers.
Example of how to fire an event in unit tests:
import zope.event from plone.postpublicationhook.event import AfterPublicationEvent event = AfterPublicationEvent(self.portal, self.portal.REQUEST) zope.event.notify(event)
- is fired for an Archetypes-based object when it's being initialised; i.e. when it's being populated for the first time.
- is fired for an Archetypes-based object when it's being initialised via WebDAV.
- is fired for all Zopeish objects when they are being created (they don't necessarily need to be content objects).
Archetypes and Zope 3 events might not be compatible with each other. Please see links below.
Two different content event types are available and might work differently depending on your scenario:
- called for Archetypes-based objects that are not in the creation stage any more.
Products.Archetypes.interfaces.IObjectEditedEvent is fired after
reindexObject() is called. If you manipulate your content object in a
handler for this event, you need to manually reindex new values, or the
changes will not be reflected in the
- called for creation-stage events as well, unlike the previous event type.
- called for Archetypes-based objects when they are being edited via WebDAV.
- called for Archetypes-based objects when an edit operation is begun.
- called for Archetypes-based objects when an edit operation is canceled.
Delete events can be fired several times for the same object. Some delete event transactions are rolled back.
- Read more about Delete events in this discussion.
- is triggered before a workflow transition is executed.
- is triggered after a workflow transition has been executed.
The DCWorkflow events are low-level events that can tell you a lot about the previous and current states.
- this is a higher level event that is more commonly used to react after a workflow action has completed.