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:
@@ -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`.
|
||||
|
||||
Reference in New Issue
Block a user