docs(lighthouse,postcard,signpost): compile README Go examples via src= (quick-261118-qsd)
This commit is contained in:
@@ -32,57 +32,60 @@ Use cases:
|
||||
|
||||
A content plugin registers its types:
|
||||
|
||||
```go
|
||||
package blog
|
||||
|
||||
import (
|
||||
"context"
|
||||
"strings"
|
||||
|
||||
"git.golem15.com/golem15/summercms/modules/pact"
|
||||
)
|
||||
|
||||
var _ pact.HasMenuItemTypes = (*Plugin)(nil)
|
||||
|
||||
type Plugin struct{}
|
||||
|
||||
func (p *Plugin) MenuItemTypes() []pact.MenuItemType {
|
||||
```go src=modules/signpost/example_test.go#BlogPlugin.MenuItemTypes
|
||||
// MenuItemTypes registers acme-post, which points at one post, and
|
||||
// acme-all-posts, which lists every post. The list type names acme-post in
|
||||
// PatternFrom, so a host override of the post URL reaches its items too.
|
||||
func (p BlogPlugin) MenuItemTypes() []pact.MenuItemType {
|
||||
return []pact.MenuItemType{{
|
||||
Key: "acme-post",
|
||||
Label: "acme.blog::lang.menuitem.post",
|
||||
DefaultPattern: "/blog/:slug",
|
||||
Placeholders: []string{":slug"},
|
||||
References: func(ctx context.Context) ([]pact.MenuItemReference, error) {
|
||||
return []pact.MenuItemReference{{Value: "hello-world", Label: "Hello world"}}, nil
|
||||
},
|
||||
Resolve: func(ctx context.Context, in pact.MenuItemResolve) (*pact.ResolvedMenuItem, error) {
|
||||
url := strings.ReplaceAll(in.Pattern, ":slug", in.Reference)
|
||||
return &pact.ResolvedMenuItem{
|
||||
Title: "Hello world",
|
||||
URL: url,
|
||||
Alternates: []pact.MenuItemAlternate{{Locale: "en", URL: url, Title: "Hello world"}},
|
||||
}, nil
|
||||
},
|
||||
References: p.postReferences,
|
||||
Resolve: p.resolvePost,
|
||||
}, {
|
||||
Key: "acme-all-posts",
|
||||
Label: "acme.blog::lang.menuitem.all_posts",
|
||||
DefaultPattern: "/blog/:slug",
|
||||
PatternFrom: "acme-post",
|
||||
Nesting: true,
|
||||
Resolve: resolveAllPosts,
|
||||
DynamicItems: true,
|
||||
Resolve: p.resolveAllPosts,
|
||||
}}
|
||||
}
|
||||
```
|
||||
|
||||
A menu plugin resolves an entry and serves the reference dropdown of its form:
|
||||
|
||||
```go
|
||||
```go src=modules/signpost/example_test.go#ExampleRegistry_Resolve
|
||||
app := exampleApp()
|
||||
blog := BlogPlugin{posts: []BlogPost{{Slug: "hello", Title: "Hello"}, {Slug: "again", Title: "Again"}}}
|
||||
if err := signpost.Activate(app, []BlogPlugin{blog}); err != nil {
|
||||
fmt.Println(err)
|
||||
return
|
||||
}
|
||||
reg, _ := app.Lookup[*signpost.Registry]()
|
||||
item, err := reg.Resolve(ctx, entry.Type, entry.Reference, entry.URLPattern, true, "")
|
||||
item, err := reg.Resolve(context.Background(), "acme-all-posts", "", "", true, "")
|
||||
if err != nil {
|
||||
fmt.Println(err)
|
||||
return
|
||||
}
|
||||
for _, child := range item.Items {
|
||||
fmt.Println(child.Title, child.URL)
|
||||
}
|
||||
// Output:
|
||||
// Hello /news/hello
|
||||
// Again /news/again
|
||||
```
|
||||
|
||||
func (c entriesController) DependentOptions(ctx context.Context, field string, values map[string]any) (pact.DependentOptionSet, error) {
|
||||
```go src=modules/signpost/example_test.go#EntriesController.DependentOptions
|
||||
// DependentOptions serves the reference dropdown: the references of the
|
||||
// menu item type chosen in the type field, with their depth.
|
||||
func (c EntriesController) DependentOptions(ctx context.Context, field string, values map[string]any) (pact.DependentOptionSet, error) {
|
||||
typ, _ := values["type"].(string)
|
||||
return signpost.ReferenceOptions(ctx, c.registry(), typ)
|
||||
reg, _ := c.app.Lookup[*signpost.Registry]()
|
||||
return signpost.ReferenceOptions(ctx, reg, typ)
|
||||
}
|
||||
```
|
||||
|
||||
@@ -90,38 +93,64 @@ func (c entriesController) DependentOptions(ctx context.Context, field string, v
|
||||
|
||||
A record type adds a `pact.ContentDescriptor`: the admin controller that edits the records, their morph type, and a `Describe` that answers each locale's URL (built from the pattern it receives, as `Resolve` builds alternates), title, description, image and word count:
|
||||
|
||||
```go
|
||||
{
|
||||
Key: "acme-post",
|
||||
DefaultPattern: "/blog/:slug",
|
||||
Resolve: resolvePost,
|
||||
Content: &pact.ContentDescriptor{
|
||||
Controller: "acme.blog.posts",
|
||||
Model: "acme_blog_posts",
|
||||
Describe: func(ctx context.Context, in pact.ContentDescribe) (*pact.ContentRecord, error) {
|
||||
post, err := loadPost(ctx, in.ID)
|
||||
if err != nil || post == nil {
|
||||
return nil, err
|
||||
}
|
||||
return &pact.ContentRecord{
|
||||
ID: in.ID,
|
||||
Published: post.Published,
|
||||
Locales: []pact.ContentLocale{{
|
||||
Locale: "en",
|
||||
URL: strings.ReplaceAll(in.Pattern, ":slug", post.Slug),
|
||||
Title: post.Title,
|
||||
}},
|
||||
}, nil
|
||||
```go src=modules/signpost/example_content_test.go#NewsPlugin.MenuItemTypes
|
||||
// MenuItemTypes registers acme-article with a content descriptor: the
|
||||
// controller that edits articles, their morph type, what kind of record an
|
||||
// article is, the MCP tool that edits one, Describe and Match.
|
||||
func (p NewsPlugin) MenuItemTypes() []pact.MenuItemType {
|
||||
return []pact.MenuItemType{{
|
||||
Key: "acme-article",
|
||||
Label: "acme.news::lang.menuitem.article",
|
||||
DefaultPattern: "/news/:slug",
|
||||
Placeholders: []string{":slug", ":id"},
|
||||
Resolve: p.resolve,
|
||||
Content: &pact.ContentDescriptor{
|
||||
Controller: "acme.news.articles",
|
||||
Model: "acme_news_articles",
|
||||
Kind: pact.ContentKindArticle,
|
||||
Tools: map[string]string{pact.ContentToolEdit: "acme_update_article"},
|
||||
Describe: p.describe,
|
||||
Match: p.match,
|
||||
},
|
||||
},
|
||||
}}
|
||||
}
|
||||
```
|
||||
|
||||
The descriptor may also say what kind of record the type holds and which MCP tool edits one (`Kind: pact.ContentKindArticle`, `Tools: map[string]string{pact.ContentToolEdit: "acme_update_post"}`), and `Describe` may report the record's `PublishedAt`, `Parents`, `Authors` and `TopHeading`, and per locale its `Images`, `Videos` and `Headings` (see [Content descriptors](../../docs/plugins/menu-item-types.md#content-descriptors)). Every one of them is optional.
|
||||
```go src=modules/signpost/example_content_test.go#NewsPlugin.describe
|
||||
// describe answers one article per locale; the URL is built from the
|
||||
// layered pattern it receives. Besides the page defaults it reports the
|
||||
// first publication, the author and the body's heading outline, whose
|
||||
// headings start at level 2 because the page renders the title as the level-1
|
||||
// heading.
|
||||
func (p NewsPlugin) describe(_ context.Context, in pact.ContentDescribe) (*pact.ContentRecord, error) {
|
||||
for _, a := range p.articles {
|
||||
if a.ID != in.ID {
|
||||
continue
|
||||
}
|
||||
url := strings.NewReplacer(":slug", a.Slug, ":id", a.ID).Replace(in.Pattern)
|
||||
headings := []pact.ContentHeading{}
|
||||
for _, h := range a.Headings {
|
||||
headings = append(headings, pact.ContentHeading{Level: 2, Text: h})
|
||||
}
|
||||
published := a.PublishedAt
|
||||
return &pact.ContentRecord{
|
||||
ID: a.ID,
|
||||
Published: a.Published,
|
||||
PublishedAt: &published,
|
||||
Authors: []pact.ContentPerson{{Name: a.Author}},
|
||||
TopHeading: 2,
|
||||
Locales: []pact.ContentLocale{{Locale: "en", URL: url, Title: a.Title, Headings: headings}},
|
||||
}, nil
|
||||
}
|
||||
return nil, nil
|
||||
}
|
||||
```
|
||||
|
||||
The descriptor may also say what kind of record the type holds and which MCP tool edits one (`Kind` and `Tools` above), match a public path back to a record (`Match`), and `Describe` may report the record's `PublishedAt`, `Parents`, `Authors` and `TopHeading`, and per locale its `Images`, `Videos` and `Headings` (see [Content descriptors](../../docs/plugins/menu-item-types.md#content-descriptors)). Every one of them is optional.
|
||||
|
||||
A consumer maps a record event to its type and reads the record's new URL:
|
||||
|
||||
```go
|
||||
```go src=modules/signpost/example_content_test.go#listen
|
||||
app.Events.Listen("acme.audit", func(ctx context.Context, ev *pact.RecordSaved) error {
|
||||
reg, _ := app.Lookup[*signpost.Registry]()
|
||||
typ, ok := reg.ContentTypeForModel(ev.Model)
|
||||
@@ -132,7 +161,7 @@ app.Events.Listen("acme.audit", func(ctx context.Context, ev *pact.RecordSaved)
|
||||
if err != nil || rec == nil {
|
||||
return err
|
||||
}
|
||||
log.Printf("%s now lives at %s", ev.ID, rec.Locales[0].URL)
|
||||
logger.Printf("%s now lives at %s", ev.ID, rec.Locales[0].URL)
|
||||
return nil
|
||||
})
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user