docs(cabana,compass,conga): compile README Go examples via src= (quick-261118-qsd)

- cabana: the hand-written controller fence points at Post, PostsController
  and BlogPlugin declarations; TestDocsDeclarations now calls each of them
- compass: mailSettings and ExampleOpen; the YAML block matches the
  directory ExampleOpen writes
- conga: job, dispatch and progress fences reuse the Jobs page targets; new
  reindex and worker regions run in TestDocsDispatch (Docker), and the
  schedule fence is FeedPlugin.Schedule, checked by TestDocsSchedule
This commit is contained in:
Jakub Zych
2026-11-18 19:44:21 +01:00
parent a0f5b5e561
commit becb31fbef
5 changed files with 316 additions and 146 deletions

View File

@@ -196,46 +196,71 @@ Plugin CSS (declared through `pact.AdminClientAssets`) and any widget shadow DOM
## Usage
A plugin exposes an admin controller and embeds its YAML. `summer make:admin-controller` scaffolds the controller type and its four YAML files, names the model after the singular of the controller (or `--model`) and lists the controller in the plugin's generated `registry.gen.go`, which also embeds the YAML for a scaffolded plugin's `AdminFS`. Written by hand, the same pieces look like this:
```go
package blog
import (
"embed"
"io/fs"
"git.golem15.com/golem15/summercms/modules/pact"
)
// adminFS holds controllers/post/config_list.yaml, controllers/post/config_form.yaml,
// models/post/columns.yaml and models/post/fields.yaml.
//
//go:embed controllers models
var adminFS embed.FS
A plugin exposes an admin controller and embeds its YAML. `summer make:admin-controller` scaffolds the controller type and its four YAML files, names the model after the singular of the controller (or `--model`) and lists the controller in the plugin's generated `registry.gen.go`, which also embeds the YAML for a scaffolded plugin's `AdminFS`. Written by hand, the same pieces look like this. The model:
```go src=modules/cabana/example_controller_test.go#Post
// Post is the model behind the acme.blog posts controller.
type Post struct {
ID uint `gorm:"primaryKey"`
Title string `gorm:"column:title"`
ID uint `gorm:"column:id;primaryKey"`
Title string `gorm:"column:title"`
Slug string `gorm:"column:slug"`
Status string `gorm:"column:status"`
Published bool `gorm:"column:published"`
PublishedAt *time.Time `gorm:"column:published_at"`
Content string `gorm:"column:content"`
}
```
```go src=modules/cabana/example_controller_test.go#Post.TableName
func (Post) TableName() string { return "acme_blog_posts" }
```
type postAdmin struct{}
The controller (`config_list.yaml` and `config_form.yaml` live in `controllers/posts`; the model files in `models/post`):
func (postAdmin) ID() string { return "acme.blog.post" }
func (postAdmin) ModelName() string { return "Post" } // must equal modelClass in the YAML
func (postAdmin) ConfigDir() string { return "controllers/post" }
func (postAdmin) NewRecord() any { return &Post{} } // pact.AdminRecordSource
```go src=modules/cabana/example_controller_test.go#PostsController
// PostsController is the admin controller for posts: the Go form of a
// WinterCMS controller with the List and Form behaviours.
type PostsController struct{}
```
// Plugin also implements party.Plugin (ID, Requires, Register, Boot).
type Plugin struct{}
```go src=modules/cabana/example_controller_test.go#PostsController.ID
// ID is the controller ID; its admin API path is /acme/blog/posts.
func (PostsController) ID() string { return "acme.blog.posts" }
```
func (p *Plugin) AdminControllers() []pact.AdminController {
return []pact.AdminController{postAdmin{}}
```go src=modules/cabana/example_controller_test.go#PostsController.ModelName
// ModelName must equal modelClass in the YAML.
func (PostsController) ModelName() string { return "Post" }
```
```go src=modules/cabana/example_controller_test.go#PostsController.ConfigDir
// ConfigDir holds config_list.yaml, config_form.yaml and config_filter.yaml.
func (PostsController) ConfigDir() string { return "controllers/posts" }
```
```go src=modules/cabana/example_controller_test.go#PostsController.NewRecord
// NewRecord returns the model the generic admin handlers query.
func (PostsController) NewRecord() any { return &Post{} }
```
The plugin lists the controller and returns the tree that holds its YAML:
```go src=modules/cabana/example_controller_test.go#BlogPlugin
// BlogPlugin is the acme.blog plugin; only its backend surface is shown.
type BlogPlugin struct{}
```
```go src=modules/cabana/example_controller_test.go#BlogPlugin.AdminControllers
// AdminControllers registers the plugin's admin controllers.
func (p *BlogPlugin) AdminControllers() []pact.AdminController {
return []pact.AdminController{PostsController{}}
}
```
func (p *Plugin) AdminFS() fs.FS { return adminFS }
```go src=modules/cabana/example_controller_test.go#BlogPlugin.AdminFS
// AdminFS is the plugin's embedded controllers/ and models/ tree. A real
// plugin returns an embed.FS; the example reads the same files from testdata.
func (p *BlogPlugin) AdminFS() fs.FS { return os.DirFS("testdata/docs") }
```
`config_list.yaml` and `config_form.yaml` reference the model files with WinterCMS paths such as `~/plugins/acme/blog/models/post/columns.yaml`. At boot, `surf.BuildRouter` calls `cabana.Activate` with the activated plugins and mounts the returned `cabana.Routes`; when no plugin registers an admin controller, `cabana.Activate` returns nil and no admin routes exist. `surf.Router.AdminPrefix` reports which case applies, and the `serve` and `route:list` commands print it as an admin status line. Record and user lookups use the `*gorm.DB` that [lagoon](../lagoon/README.md) publishes on the `backpack.App`.