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`.
|
||||
|
||||
@@ -2,6 +2,7 @@ package cabana_test
|
||||
|
||||
import (
|
||||
"fmt"
|
||||
"io/fs"
|
||||
"os"
|
||||
"testing"
|
||||
|
||||
@@ -81,9 +82,25 @@ func ExampleActivate() {
|
||||
// false
|
||||
}
|
||||
|
||||
// TestDocsDeclarations checks the plugin declarations the Backend pages show.
|
||||
// TestDocsDeclarations checks the plugin declarations the Backend pages and
|
||||
// the README show.
|
||||
func TestDocsDeclarations(t *testing.T) {
|
||||
p := &BlogPlugin{}
|
||||
c := PostsController{}
|
||||
if c.ID() != "acme.blog.posts" || c.ModelName() != "Post" || c.ConfigDir() != "controllers/posts" {
|
||||
t.Fatalf("controller = %q %q %q", c.ID(), c.ModelName(), c.ConfigDir())
|
||||
}
|
||||
if _, ok := c.NewRecord().(*Post); !ok || (Post{}).TableName() != "acme_blog_posts" {
|
||||
t.Fatalf("NewRecord() = %T, table %q", c.NewRecord(), Post{}.TableName())
|
||||
}
|
||||
if ctrls := p.AdminControllers(); len(ctrls) != 1 || ctrls[0].ID() != c.ID() {
|
||||
t.Fatalf("AdminControllers() = %+v", ctrls)
|
||||
}
|
||||
for _, name := range []string{"controllers/posts/config_list.yaml", "controllers/posts/config_form.yaml", "models/post/columns.yaml", "models/post/fields.yaml"} {
|
||||
if _, err := fs.Stat(p.AdminFS(), name); err != nil {
|
||||
t.Fatalf("AdminFS(): %v", err)
|
||||
}
|
||||
}
|
||||
if n := len(p.Permissions()); n != 2 {
|
||||
t.Fatalf("Permissions() = %d entries", n)
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user