From 37153ad53f01157f20f120b4d65d0f6a0066e0d4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Katja=20Su=CC=88ss?= Date: Tue, 4 Mar 2025 10:03:16 +0100 Subject: [PATCH 1/2] first draft with chatgpt Write a documentation chapter about subscribers (event handler) in Plone for Version Plone 6. Take the two chapters of Plone 5 documentation https://5.docs.plone.org/external/plone.app.dexterity/docs/advanced/event-handlers.html and https://5.docs.plone.org/develop/addons/components/events.html into account. --- docs/backend/subscribers.md | 94 +++++++++++++++++++++++++++++++++++-- 1 file changed, 90 insertions(+), 4 deletions(-) diff --git a/docs/backend/subscribers.md b/docs/backend/subscribers.md index 04f8be033..05be83715 100644 --- a/docs/backend/subscribers.md +++ b/docs/backend/subscribers.md @@ -11,8 +11,94 @@ myst: # Subscribers (event handlers) -```{todo} -Move content from: -- https://5.docs.plone.org/external/plone.app.dexterity/docs/advanced/event-handlers.html -- https://5.docs.plone.org/develop/addons/components/events.html +In Plone 6, the event system provides a robust mechanism for developers to execute custom actions in response to various occurrences within the system. This capability is facilitated through the use of event subscribers, also known as event handlers, which listen for specific events and perform predefined operations when those events are triggered. + +## Overview of the Event System + +Plone's event system is built upon the Zope Component Architecture's `zope.event` package, enabling a publish-subscribe pattern where events are broadcasted, and subscribers (event handlers) respond accordingly. Key characteristics of this system include: + +- **Simplicity**: The event system is straightforward to implement and use. +- **Non-deterministic Handler Execution Order**: The order in which event handlers are invoked is not specified and cannot be controlled. +- **Non-cancelable Events**: Once an event is emitted, all associated handlers will receive it; events cannot be canceled. +- **No Return Values**: Event handlers do not return values. +- **Exception Handling**: Exceptions raised within an event handler can interrupt the request processing. + +Events are typically defined by interfaces and may carry pertinent information about the event. Object events, which pertain to specific content objects, implement the `zope.component.interfaces.IObjectEvent` interface and include an `object` attribute referencing the related content object. This structure allows event handlers to be registered for specific object types and event types. + +## Commonly Used Event Types + +Several standard event types are frequently utilized in Plone: + +- **`zope.lifecycleevent.interfaces.IObjectCreatedEvent`**: Triggered just after an object is created but before it is added to its container. +- **`zope.lifecycleevent.interfaces.IObjectAddedEvent`**: Occurs when an object has been added to its container. +- **`zope.lifecycleevent.interfaces.IObjectModifiedEvent`**: Fired when an object is modified. +- **`zope.lifecycleevent.interfaces.IObjectRemovedEvent`**: Triggered when an object is removed from its container. + +These events are part of the `zope.lifecycleevent` package and are integral to Plone's event-handling infrastructure. + +## Registering Event Handlers + +Event handlers can be registered in two primary ways: using ZCML (Zope Configuration Markup Language) or Python decorators. + +### Using ZCML + +To register an event handler via ZCML, add a `` directive to your package's `configure.zcml` file: + + +```xml + +``` + + +In this configuration: + +- The `for` attribute specifies the interface of the content type and the event interface. +- The `handler` attribute points to the function that will handle the event. + +This setup ensures that `your_function` is called whenever an object implementing `IMyContentTypeClass` is created. + +### Using Python Decorators + +Alternatively, you can register an event handler using the `subscribe` decorator from the `zope.component` module: + + +```python +from zope.component import adapter +from zope.lifecycleevent.interfaces import IObjectCreatedEvent +from .interfaces import IMyContentTypeClass + +@adapter(IMyContentTypeClass, IObjectCreatedEvent) +def your_function(obj, event): + # Your code here ``` + + +In this example, `your_function` will be invoked whenever an object implementing `IMyContentTypeClass` is created. + +## Firing Events + +To emit an event, use the `notify` function from the `zope.event` module: + + +```python +from zope.event import notify +from zope.lifecycleevent import ObjectModifiedEvent + +notify(ObjectModifiedEvent(your_object)) +``` + + +This call broadcasts an `ObjectModifiedEvent`, and all subscribers to this event will be notified. + +## Considerations for Event Handlers + +When implementing event handlers, keep the following considerations in mind: + +- **Performance**: Since event handlers are executed synchronously, long-running operations can delay the request processing. +- **Error Handling**: Exceptions in event handlers can disrupt the normal flow of the application. Ensure proper error handling within your handlers. +- **Asynchronous Processing**: For tasks that require significant processing time, consider using asynchronous processing mechanisms to avoid blocking the main application flow. + +By effectively leveraging event subscribers, developers can create responsive and dynamic behaviors in Plone 6, enhancing the functionality and user experience of their applications. From 39c84350a9ec0497c5c743d1435a65e89f0b1971 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Katja=20Su=CC=88ss?= Date: Tue, 4 Mar 2025 11:22:17 +0100 Subject: [PATCH 2/2] prompt: for better review experience: split text in one line per sentece --- docs/backend/subscribers.md | 18 ++++++++---------- 1 file changed, 8 insertions(+), 10 deletions(-) diff --git a/docs/backend/subscribers.md b/docs/backend/subscribers.md index 05be83715..efff5806d 100644 --- a/docs/backend/subscribers.md +++ b/docs/backend/subscribers.md @@ -11,11 +11,13 @@ myst: # Subscribers (event handlers) -In Plone 6, the event system provides a robust mechanism for developers to execute custom actions in response to various occurrences within the system. This capability is facilitated through the use of event subscribers, also known as event handlers, which listen for specific events and perform predefined operations when those events are triggered. +In Plone 6, the event system provides a robust mechanism for developers to execute custom actions in response to various occurrences within the system. +This capability is facilitated through the use of event subscribers, also known as event handlers, which listen for specific events and perform predefined operations when those events are triggered. ## Overview of the Event System -Plone's event system is built upon the Zope Component Architecture's `zope.event` package, enabling a publish-subscribe pattern where events are broadcasted, and subscribers (event handlers) respond accordingly. Key characteristics of this system include: +Plone's event system is built upon the Zope Component Architecture's `zope.event` package, enabling a publish-subscribe pattern where events are broadcasted, and subscribers (event handlers) respond accordingly. +Key characteristics of this system include: - **Simplicity**: The event system is straightforward to implement and use. - **Non-deterministic Handler Execution Order**: The order in which event handlers are invoked is not specified and cannot be controlled. @@ -23,7 +25,9 @@ Plone's event system is built upon the Zope Component Architecture's `zope.event - **No Return Values**: Event handlers do not return values. - **Exception Handling**: Exceptions raised within an event handler can interrupt the request processing. -Events are typically defined by interfaces and may carry pertinent information about the event. Object events, which pertain to specific content objects, implement the `zope.component.interfaces.IObjectEvent` interface and include an `object` attribute referencing the related content object. This structure allows event handlers to be registered for specific object types and event types. +Events are typically defined by interfaces and may carry pertinent information about the event. +Object events, which pertain to specific content objects, implement the `zope.component.interfaces.IObjectEvent` interface and include an `object` attribute referencing the related content object. +This structure allows event handlers to be registered for specific object types and event types. ## Commonly Used Event Types @@ -44,7 +48,6 @@ Event handlers can be registered in two primary ways: using ZCML (Zope Configura To register an event handler via ZCML, add a `` directive to your package's `configure.zcml` file: - ```xml ` directive to your pa /> ``` - In this configuration: - The `for` attribute specifies the interface of the content type and the event interface. @@ -64,7 +66,6 @@ This setup ensures that `your_function` is called whenever an object implementin Alternatively, you can register an event handler using the `subscribe` decorator from the `zope.component` module: - ```python from zope.component import adapter from zope.lifecycleevent.interfaces import IObjectCreatedEvent @@ -75,14 +76,12 @@ def your_function(obj, event): # Your code here ``` - In this example, `your_function` will be invoked whenever an object implementing `IMyContentTypeClass` is created. ## Firing Events To emit an event, use the `notify` function from the `zope.event` module: - ```python from zope.event import notify from zope.lifecycleevent import ObjectModifiedEvent @@ -90,7 +89,6 @@ from zope.lifecycleevent import ObjectModifiedEvent notify(ObjectModifiedEvent(your_object)) ``` - This call broadcasts an `ObjectModifiedEvent`, and all subscribers to this event will be notified. ## Considerations for Event Handlers @@ -101,4 +99,4 @@ When implementing event handlers, keep the following considerations in mind: - **Error Handling**: Exceptions in event handlers can disrupt the normal flow of the application. Ensure proper error handling within your handlers. - **Asynchronous Processing**: For tasks that require significant processing time, consider using asynchronous processing mechanisms to avoid blocking the main application flow. -By effectively leveraging event subscribers, developers can create responsive and dynamic behaviors in Plone 6, enhancing the functionality and user experience of their applications. +By effectively leveraging event subscribers, developers can create responsive and dynamic behaviors in Plone 6, enhancing the functionality and user experience of their applications.