diff --git a/docs/concepts/events-vs-filters.rst b/docs/concepts/events-vs-filters.rst index e18ba604..8d2b1882 100644 --- a/docs/concepts/events-vs-filters.rst +++ b/docs/concepts/events-vs-filters.rst @@ -2,61 +2,79 @@ Events vs Filters ================= Open edX Events and Filters are two types of hooks that allow developers to -extend the functionality of the platform. They are defined in the +extend the functionality of the Open edX platform. They are defined in the `openedx-events`_ and `openedx-filters`_ libraries respectively. +.. _openedx-events: https://github.com/openedx/openedx-events +.. _openedx-filters: https://github.com/openedx/openedx-filters + Events ------ -Events are signals sent in specific places in the Open edX project core. They -allow external functions to be executed when the event is triggered. These -functions can extend the functionality of the platform or perform additional +Events are Open edX specific Django signals sent in specific places in the Open edX +platform. They allow external functions, known as signal handlers in the Django world, +to be executed when the event is triggered. These functions can extend the functionality of the platform or perform additional processing based on the event data. -Events are defined using the `OpenEdxPublicSignal` class, which provides a -structured way to define the data and metadata associated with the event. This -allows developers to create custom events for specific actions or changes within -the platform. +For a more detailed explanation of Open edX Events, see the `Open edX Events`_ document. Filters ------- Filters are functions that can modify the behavior of the application by -altering the data or parameters passed to a specific function or method. They -allow developers to intercept and modify the input or output of a function -without directly modifying the function itself. +altering input data or halting execution based on specific conditions. They +allow developers to implement application flow control based on their business +login or requirements without directly modifying the application code. -Filters are defined using the `OpenEdxFilter` class, which provides a way to -define the filter function and the parameters it should receive. This allows -developers to create custom filters that can be applied to specific functions or -methods in the platform. +For a more detailed explanation of Open edX Filters, see the `Open edX Filters`_ documentation. Differences between Events and Filters -------------------------------------- Here are some key differences between Open edX Events and Filters: -+----------------------+-------------------------------------------------------+-------------------------------------------------------------+ -| | Events | Filters | -+======================+=======================================================+=============================================================+ -| Purpose | Trigger custom actions or processing in response to | Modify the behavior of the application by intercepting and | -| | specific events or actions within the platform, | altering the data or parameters passed to a specific | -| | without affecting the application's flow. | function or method. | -+----------------------+-------------------------------------------------------+-------------------------------------------------------------+ -| Usage | Used to execute external functions when an event is | Used to intercept and modify the input or output of a | -| | triggered. | component without directly modifying the component itself. | -+----------------------+-------------------------------------------------------+-------------------------------------------------------------+ -| Definition | Defined using the `OpenEdxPublicSignal` class, which | Defined using the `OpenEdxFilter` class, which provides a | -| | provides a structured way to define the data and | way to define the filter function and the parameters it | -| | metadata associated with the event. | should receive. | -+----------------------+-------------------------------------------------------+-------------------------------------------------------------+ -| Implementation | Implemented using Django signals, which allow | Implemented by intercepting the input or output of a | -| | developers to send and receive notifications within | function or method using the filter function. | -| | a Django application. | | -+----------------------+-------------------------------------------------------+-------------------------------------------------------------+ -| Example | A custom event that triggers an email notification | A filter that modifies the data returned by a specific | -| | when a user enrolls in a course. | API endpoint to include additional information. | -+----------------------+-------------------------------------------------------+-------------------------------------------------------------+ ++-----------------+------------------------------------------------------------------------+-------------------------------------------------------------+-----+ +| | Events | Filters | | ++=================+========================================================================+=============================================================+=====+ +|| Purpose || Trigger custom actions or processing in response to || Modify the behavior of the application by intercepting and || | +|| || specific events or actions within the platform, || altering the data or parameters passed to a specific || | +|| || without affecting the application's flow. || function or method. || | ++-----------------+------------------------------------------------------------------------+-------------------------------------------------------------+-----+ +|| Usage || Used to **extend** functionality via signal handlers when an event is || Used to intercept and **modify** the input or output of a || | +|| || triggered. || component without directly modifying the component itself. || | ++-----------------+------------------------------------------------------------------------+-------------------------------------------------------------+-----+ +|| Definition || Defined using the `OpenEdxPublicSignal` class, which || Defined using the `OpenEdxFilter` class, which provides a || | +|| || provides a structured way to define the data and || way to define the filter function and the parameters it || | +|| || metadata associated with the event. || should receive. || | ++-----------------+------------------------------------------------------------------------+-------------------------------------------------------------+-----+ +|| Implementation || Implemented using Django signals, which allow || Implemented using an accumulative pipeline mechanism which || | +|| || developers to send and receive notifications within || takes a set of arguments and returns a modified set of || | +|| || a Django application. || arguments to the caller or raises exceptions during || | +|| || || processing. || | ++-----------------+------------------------------------------------------------------------+-------------------------------------------------------------+-----+ +|| Example || A custom event that triggers an email notification || A filter that modifies the data returned by a specific || | +|| || when a user enrolls in a course. || API endpoint to include additional information. || | ++-----------------+------------------------------------------------------------------------+-------------------------------------------------------------+-----+ When to use an Open edX Event? ------------------------------ + +Use an Open edX Event when you need to: + +- Trigger custom actions or processing in response to specific events or actions within the platform. +- Communicate or coordinate with other components or services based on specific events or actions. +- Synchronize data between different services or systems in response to specific events or actions. +- Notify users or external systems about specific events or actions within the platform. +- Integrate with external systems or services based on specific events or actions within the platform. + +When to use an Open edX Filter? +------------------------------- + +Use an Open edX Filter when: + +- Modify the input or output of a specific function or method without directly modifying the function itself. +- Intercept and modify the data or parameters passed to a specific component or service. +- Apply a series of transformations or validations to the input or output of a specific function or method. +- Enforce specific constraints or business rules on the input or output of a specific function or method. +- Handle exceptions or errors that occur during the processing of a specific function or method. +- Apply a set of filters to the input or output of a specific function or method based on specific conditions or criteria. diff --git a/docs/concepts/glossary.rst b/docs/concepts/glossary.rst deleted file mode 100644 index 775cfbbd..00000000 --- a/docs/concepts/glossary.rst +++ /dev/null @@ -1,32 +0,0 @@ -Open edX Events Glossary -########################## - -This glossary provides definitions for some of the terms to ease the adoption of the Open edX Events library. - -Event Receiver --------------- - -An event receiver, handler or listener is a function that listens for a specific event and executes custom logic in response to the event being triggered. Event receivers are registered with the event dispatcher and are called when the event is emitted. In Django, event receivers are known as signal handlers. Both terms are used interchangeably. - -Event Trigger -------------- - -An event trigger is the action or event that causes an event to be emitted. When an event trigger occurs, the associated event is emitted, and any registered event receivers are called to handle the event. - -Event Payload -------------- - -The event payload is the data associated with an event that is passed to event receivers when the event is triggered. The payload typically includes information about the event, such as the event name, timestamp, and any additional metadata. - -Sender ------- - -The sender is the service or component that emits an event. The sender is responsible for triggering the event and passing the event payload to any registered event receivers. - -Event Type ----------- - -The event type is a unique identifier for an event that distinguishes it from other events. Event types are used to register event receivers and dispatch events to the appropriate receivers. - -Event Definition ----------------- diff --git a/docs/concepts/hooks-extension-framework.rst b/docs/concepts/hooks-extension-framework.rst index 044272bf..b218d3ad 100644 --- a/docs/concepts/hooks-extension-framework.rst +++ b/docs/concepts/hooks-extension-framework.rst @@ -12,7 +12,7 @@ Open edX platform. Hooks: Open edX Events and Filters ---------------------------------- -Hooks are predefined places in the Open edX project core where externally defined +Hooks are predefined places in the Open edX platform where externally defined functions can take place. These functions may alter what the user sees or experiences on the platform, while in other cases, they are purely informative. All hooks are designed to be extended through Open edX plugins and configurations. @@ -32,8 +32,7 @@ The main goal of the framework is that developers can use them to change the functionality of the platform as needed and still be able to migrate to newer open releases with very little to no development effort, so they're designed with stability in mind, meaning that they are versioned and backward compatible -as much as possible. In the case of the events, this approach is further -detailed in the `versioning ADR`_ and the `payload ADR`_. +as much as possible. A longer description of the framework and its history can be found in `OEP 50`_. diff --git a/docs/concepts/openedx-events.rst b/docs/concepts/openedx-events.rst index c9db5f39..c6f82ccc 100644 --- a/docs/concepts/openedx-events.rst +++ b/docs/concepts/openedx-events.rst @@ -1,14 +1,11 @@ Open edX Events =============== -Overview --------- - In the context of Open edX, events provide a mechanism for extending the platform by enabling developers to listen to specific Django signals emitted by various services and respond accordingly. This allows for customized reactions to key actions or changes within the platform, without requiring direct modifications -to the core codebase. +to the Open edX platform codebase. What are Open edX Events? ------------------------- @@ -18,26 +15,26 @@ when a specific action or event occurs. These signals are used to notify other services or components of the platform that an event has taken place, allowing them to respond accordingly. Events are defined using the ``OpenEdxPublicSignal`` class, which provides a structured way to define the data and metadata associated with -the event. +the event along with other relevant information. Why are Open edX Events important? ---------------------------------- Open edX Events are a key component of the Hooks Extension Framework, which allows developers to extend the functionality of the platform in a stable and maintainable -way. By defining events for specific actions or changes within the platform, developers -can create custom listeners that respond to these events and perform additional +way. By triggering events for specific actions or changes within the platform, developers +can create event handlers that respond to these events and perform additional actions or processing as needed. This enables a wide range of use cases, from integrating with external systems to implementing custom business logic. How are Open edX Events used? ----------------------------- -Developers can create custom listeners for Open edX Events by defining signal +Developers can create handlers for Open edX Events by implementing Django signal handlers that respond to specific events emitted by the platform. These signal -handlers can be registered using Django's signal dispatcher, allowing them to +handlers can be registered using Django's signal mechanism, allowing them to listen for events and execute custom logic in response. By defining events and -listeners in this way, developers can create modular, reusable components that +handlers in this way, developers can create modular, reusable components that extend the functionality of the platform without requiring direct modifications to the core codebase. @@ -51,9 +48,9 @@ leverage their existing knowledge of Django signals. The lifecycle of an Open edX Event can be summarized as follows: -1. A service emits an Open edX Event (Django signal) triggered by a specific action or event. The event data includes information about the event, such as the event name, timestamp, and any additional metadata. +1. A service emits an Open edX Event (Open edX specific Django signal) triggered by a specific action or event. The event data includes information about the event, such as the event name, timestamp, and any additional metadata. 2. Registered signal handlers listening for the event are called in response to the signal being emitted. -3. The signal handler can perform additional processing or trigger other actions based on the event data. +3. The signal handler performs additional processing or trigger other actions based on the event data. 4. The event is considered complete once all registered signal handlers have executed. Here is an example of how that might look like with an existing event: