docs: add a Role in the framework section to every module README
Each module README now says where the module sits in the dependency graph, why it is its own module, and lists use cases for application developers.
This commit is contained in:
@@ -10,6 +10,16 @@ Typed, synchronous event bus with listener priorities, payload collection and st
|
||||
|
||||
`festival` is the SummerCMS counterpart of WinterCMS's `Event::listen` and `Event::fire`, the mechanism plugins use to extend each other without direct calls. Events are routed by their Go type rather than by a string name, so a listener registered for `*PostPublished` receives exactly that type, and a payload mismatch is a compile error. Each application owns one bus: [backpack](../backpack/README.md) creates it in `backpack.New` and exposes it as `backpack.App.Events`, and plugins register listeners from their Boot step.
|
||||
|
||||
## Role in the framework
|
||||
|
||||
A dependency-free core primitive owned by `backpack`, so every plugin reaches the bus through the application. It is in-process and synchronous. Delivery to browsers is `lighthouse` and delivery to devices is `flare`; those depend on the database and jobs, so they cannot sit under `backpack` without an import cycle.
|
||||
|
||||
Use cases:
|
||||
|
||||
- Let one plugin react to another without importing it, for example sending a welcome mail when a user registers.
|
||||
- Let plugins veto or change an action by priority, the WinterCMS "before" event style.
|
||||
- Collect contributions from several listeners, such as extra fields for an API response.
|
||||
|
||||
## Features
|
||||
|
||||
- Listener registration with `festival.Bus.Listen` (priority 0) and `festival.Bus.ListenPriority`. Higher priorities run first; listeners with equal priority run in registration order. Every listener carries the ID of the plugin that owns it.
|
||||
|
||||
Reference in New Issue
Block a user