docs(cooler,diary,festival,fetchguard): compile README Go examples via src= (quick-261118-qsd)
- cooler: ExampleFromApp and the articlesController purge declarations; AllowExport run by TestDocsAllowExport on miniredis - diary: blogLog and ExampleFor; the generated main's run function, run by TestDocsRun in a temp directory with diary.Reset on cleanup - festival: PostPublished/ExampleBus_Fire and PostFormExtended/Collected/ ExampleBus_Collect, with a TestDocsDeclarations for Collected - fetchguard: fetch region run by TestDocsFetchImage (loopback refused as private_ip), client region run by TestDocsSyncItems on a stub transport
This commit is contained in:
@@ -33,39 +33,65 @@ Use cases:
|
||||
|
||||
## Usage
|
||||
|
||||
```go
|
||||
package blog
|
||||
|
||||
import (
|
||||
"context"
|
||||
|
||||
"git.golem15.com/golem15/summercms/modules/festival"
|
||||
)
|
||||
|
||||
// PostPublished is fired after a post goes live. Listeners add payload
|
||||
// entries and may mark the event handled.
|
||||
```go src=modules/festival/example_test.go#PostPublished
|
||||
// PostPublished is the event the acme.blog plugin fires after a post goes live.
|
||||
type PostPublished struct {
|
||||
PostID uint
|
||||
payload map[string]any
|
||||
handled bool
|
||||
}
|
||||
|
||||
func (e *PostPublished) Collected() map[string]any { return e.payload }
|
||||
func (e *PostPublished) IsHandled() bool { return e.handled }
|
||||
|
||||
func publish(ctx context.Context, bus *festival.Bus) (map[string]any, error) {
|
||||
bus.ListenPriority("acme.search", 10, func(ctx context.Context, e *PostPublished) error {
|
||||
if e.payload == nil {
|
||||
e.payload = map[string]any{}
|
||||
}
|
||||
e.payload["indexed"] = true
|
||||
return nil
|
||||
})
|
||||
return bus.Collect(ctx, &PostPublished{PostID: 42})
|
||||
Title string
|
||||
}
|
||||
```
|
||||
|
||||
The event type is inferred from the listener's parameter, so this listener only receives `*PostPublished` events. In a plugin, the bus is `app.Events` on the `backpack.App` passed to Boot; `festival.New` is for tests and standalone use.
|
||||
```go src=modules/festival/example_test.go#ExampleBus_Fire
|
||||
bus := festival.New() // in a plugin, use app.Events
|
||||
|
||||
// acme.search and acme.notify extend acme.blog from their Boot steps.
|
||||
bus.Listen("acme.search", func(ctx context.Context, e PostPublished) error {
|
||||
fmt.Println("index", e.Title)
|
||||
return nil
|
||||
})
|
||||
bus.ListenPriority("acme.notify", 10, func(ctx context.Context, e PostPublished) error {
|
||||
fmt.Println("notify subscribers of", e.Title)
|
||||
return nil
|
||||
})
|
||||
|
||||
// acme.blog fires the event; higher priorities run first.
|
||||
if err := bus.Fire(context.Background(), PostPublished{Title: "Hello"}); err != nil {
|
||||
fmt.Println(err)
|
||||
}
|
||||
// Output:
|
||||
// notify subscribers of Hello
|
||||
// index Hello
|
||||
```
|
||||
|
||||
The event type is inferred from the listener's parameter, so these listeners only receive `PostPublished` events. Events that listeners modify are pointers; `festival.Bus.Collect` merges what each listener collected:
|
||||
|
||||
```go src=modules/festival/example_test.go#PostFormExtended
|
||||
// PostFormExtended gathers extra fields other plugins add to the post form.
|
||||
type PostFormExtended struct {
|
||||
fields map[string]any
|
||||
}
|
||||
```
|
||||
|
||||
```go src=modules/festival/example_test.go#PostFormExtended.Collected
|
||||
func (e *PostFormExtended) Collected() map[string]any { return e.fields }
|
||||
```
|
||||
|
||||
```go src=modules/festival/example_test.go#ExampleBus_Collect
|
||||
bus := festival.New()
|
||||
bus.Listen("acme.seo", func(ctx context.Context, e *PostFormExtended) error {
|
||||
e.fields = map[string]any{"meta_title": "text"}
|
||||
return nil
|
||||
})
|
||||
bus.Listen("acme.gallery", func(ctx context.Context, e *PostFormExtended) error {
|
||||
e.fields = map[string]any{"cover": "fileupload"}
|
||||
return nil
|
||||
})
|
||||
|
||||
fields, err := bus.Collect(context.Background(), &PostFormExtended{})
|
||||
fmt.Println(fields, err)
|
||||
// Output: map[cover:fileupload meta_title:text] <nil>
|
||||
```
|
||||
|
||||
In a plugin, the bus is `app.Events` on the `backpack.App` passed to Boot; `festival.New` is for tests and standalone use.
|
||||
|
||||
## API reference
|
||||
|
||||
|
||||
Reference in New Issue
Block a user