The plugin SDK
The sdk package is the only Gophenberg package a plugin imports.
It is small on purpose, and this page is all of it. It names only
its own types and the standard library’s, so a release of a module
the core uses never changes what a plugin compiles against.
The SDK is a Go module of its own,
github.com/gopherium/gophenberg/sdk. Its versions, such as
v0.1.0, come from git tags such as sdk/v0.1.0. A plugin kept in
its own repository requires that module alone, never the whole of
Gophenberg:
go get github.com/gopherium/gophenberg/sdk@latestVersions, at the end of this page, says what changed in each version and how to move your plugin to it.
Register receives one value:
| Field | What it is |
|---|---|
DB | The plugin’s share of the site’s database, described below |
DatabaseURL | The PostgreSQL connection string, for a plugin that still opens its own connection. Empty on a SQLite database |
Content | A read view of published content |
Accounts | Reads the names, roles and avatars of many accounts in one call, described below |
Env | Reads the settings under the GOPHENBERG_ prefix, for the plugin’s own configuration |
Getenv | Reads any environment variable by its full name, as it is set |
Env takes a setting’s name without the prefix and trims the
spaces around its value. Value returns the text, empty when the
setting is unset, and Required refuses an empty one. Duration,
Count and Flag read a duration above zero, a whole number above
zero, or true or false. Counts reads whole numbers above zero
split by commas, each above the one before, such as 10,50,100.
Each returns the default you pass when the setting is empty.
Within narrows the prefix, so
deps.Env.Within("FEED_").Count("ITEMS", 20) reads
GOPHENBERG_FEED_ITEMS. Every error names the full setting, such
as GOPHENBERG_FEED_ITEMS: must be a whole number, got "banana",
so Register can return it as it is.
The lifecycle interfaces
Section titled “The lifecycle interfaces”sdk.Plugin is required: ID, Start, Stop. Six optional
interfaces add capabilities the host discovers automatically:
Migrator for database migrations, RouteProvider for HTTP under
/api/plugins/{id}, PublicPathProvider for the exact paths that
answer without a login, TypeDeclarer for content types, field
groups and fields the plugin brings with it, CommandProvider
for commands on the gophenberg command line, and
RoleProvider for the roles and capabilities
the plugin brings.
Register only checks the plugin’s settings and builds it. It
opens nothing, no connection, no file and no goroutine. Start
does that. Commands such as list, check and migrate register
every plugin and stop it again without ever starting it. Only
serve starts the plugins. So Stop must work even when Start
never ran, and return by the time its context ends. When list or
help registers the plugins, DatabaseURL can be empty. On a SQLite
database it is always empty.
When a plugin fails to register or to declare its types, Gophenberg
stops every plugin that registered. When one fails to start, it
stops the ones already started. On the command line, a plugin that
fails to register shows under “Not loaded:” in gophenberg list,
and check, migrate and seed -yes fail.
The database
Section titled “The database”deps.DB is the plugin’s share of the site’s one database pool. A
plugin never needs a pool of its own, so many plugins cannot use up
the connections PostgreSQL allows.
_, err := p.db.Exec(ctx, "INSERT INTO greetings (name) VALUES ($1)", name)Exec,QueryandQueryRowtake PostgreSQL’s$1,$2placeholders.Beginstarts a transaction that offers the same three, plusCommitandRollback.Enginenames the engine,sdk.Postgreson PostgreSQL andsdk.SQLiteon SQLite.- Each statement, open result set and transaction holds one slot
until it ends, so close every
Rows. The share holdsGOPHENBERG_PLUGIN_DB_CONNSslots for each plugin, 4 by default. Today all plugins draw from one share of that size. - The share always leaves
GOPHENBERG_PLUGIN_DB_RESERVEof the pool’s connections to the site, 2 by default, so it may hold fewer slots than the plugins add up to. A statement that finds no free slot before its deadline fails. - A statement ends at
GOPHENBERG_PLUGIN_QUERY_TIMEOUT, 5 seconds by default, its wait for a slot included. A transaction ends atGOPHENBERG_PLUGIN_TX_TIMEOUT, 30 seconds by default. - The share opens once every plugin registered. Keep
deps.DBinRegisterand use it fromStarton. A statement duringRegisteris refused. - On a SQLite database the share stays closed for now.
Exec,Query,QueryRowandBegineach answerthe plugin database share is closed while GOPHENBERG_DATABASE_URL names a SQLite database. AMigratethat runs throughdeps.DBgets the same error, sogophenberg migratestops there.Enginetells a plugin which database it runs on before it sends a statement. - On a SQLite database the content reads of
Depsare not ready yet either, so checkdeps.DB.Engine()first and skip them when it answerssdk.SQLite. The account reads work there.
Reading content
Section titled “Reading content”posts, err := deps.Content.ListPublished(ctx, "post", 10)Each sdk.Item carries ID, Type, Path, Slug, Title,
Excerpt, Content, Fields, PublishedAt, and UpdatedAt.
ID is an sdk.ID, sixteen bytes whose String gives the
36 character form, such as 019fb000-0000-7000-8000-000000000001.
JSON carries an sdk.ID as that same text, in both directions.
Path is the item’s public address, so a plugin building links
prefixes it with / and nothing else. The Content has the same
HTML filter applied that the public API uses, block markers intact.
Title and Excerpt arrive as stored, so if your plugin serves
HTML, escaping everything but Content is your job.
Fields holds the item’s field values keyed by field key, shaped
the way the content API serves them and
decoded the way encoding/json decodes them. A media value is an
object naming the file, a relation lists the items it points at,
and a Linked from field lists the items pointing this way. They are
data, not markup, so escape them too before serving them as HTML.
Reading account names
Section titled “Reading account names”deps.Accounts turns account ids into the names people see. Ask
for every id a page needs in one call, with the avatar size you
draw, so a page of fifteen authors costs one read:
people, err := deps.Accounts.People(ctx, authorIDs, 96)People works the same way on a SQLite database.
The answer is a map keyed by sdk.ID. Each sdk.Person carries
ID, Name, Role, Avatar and Disabled. Name is the display
name. Role is the stored role, such as member. Build profile
links from ID.
Avatar is an image address at the size you asked, from 1 to 2048
pixels. A size outside that range is refused. For sharp screens, ask
for twice the size you draw, and ask once with the largest size the
page shows. The site’s avatar settings
decide what the address holds. By default it is a
data:image/svg+xml;base64, address that holds the picture itself,
so the browser makes no request. With Gravatar it points at
secure.gravatar.com. With avatars off it is empty, so draw no
picture then. Put the address in an <img src> as it is.
html/template writes #ZgotmplZ in place of a data: address, so
pass it as template.URL(person.Avatar). The site builds every
avatar address, so it is safe to mark:
data := struct{ Avatar template.URL }{template.URL(person.Avatar)}Disabled is true for an account an administrator turned off. Show
its name, link nowhere, and show your own word for its role, such as
“Inactive”.
An id the site does not hold is missing from the map, and so is an
account that never confirmed its address. Show your own words for
it, such as “Former member”. An id asked twice comes back once, and
asking for no ids reads nothing. Keep deps.Accounts in Register
and use it from Start on. A read during Register is refused, and
a read ends at GOPHENBERG_PLUGIN_QUERY_TIMEOUT.
A test that fakes the reader by embedding sdk.HostOnly stops
compiling when the reader gains a method.
Declaring content
Section titled “Declaring content”A plugin that implements TypeDeclarer is handed a TypeRegistrar
once at every start, before anything serves:
func (p plugin) DeclareTypes(ctx context.Context, types sdk.TypeRegistrar) error { if err := types.DeclareType(ctx, sdk.TypeDeclaration{ Key: "event", SingularLabel: "Event", PluralLabel: "Events", RouteWord: "events", Description: "Gatherings near you.", }); err != nil { return err } return types.DeclareGroup(ctx, sdk.GroupDeclaration{ Key: "event-details", Title: "Event details", Location: [][]sdk.Rule{{{Source: "content_type", Operator: "==", Value: "event"}}}, Fields: []sdk.FieldDeclaration{{Key: "venue", Label: "Venue", Kind: "text"}}, })}Declaring is safe to repeat. A definition that is not there yet is created, one that is there is left alone, and a changed label, description, required flag, setting or location is carried onto it. Two things are refused: changing a field’s kind, and changing a type’s route word, because both would strand stored content. A definition the plugin stops declaring stays in place.
What a plugin declares belongs to that plugin. The admin shows it with a badge naming the plugin and offers no way to change or delete it, though it can still be turned off. If the site already holds a type or group under the same key, the plugin’s declaration is skipped and the start log says so.
Commands
Section titled “Commands”A plugin that implements CommandProvider offers commands on the
gophenberg command line. Each command’s name is the plugin id, a
colon, then the command:
func (p plugin) Commands() []sdk.Command { return []sdk.Command{{ Name: "hello:greet", Summary: "print a greeting for one name", Args: []string{"name"}, Run: func(ctx context.Context, call sdk.Call) error { name := strings.TrimSpace(call.Args[0]) if name == "" { return sdk.Misuse(errors.New("hello:greet wants a name that is not blank")) } _, err := fmt.Fprintf(call.Stdout, "hello, %s\n", name) return err }, }}}gophenberg list shows it under the plugin id,
gophenberg help hello:greet prints its page, and
gophenberg hello:greet Maria runs it.
| Field | What it is |
|---|---|
Name | <plugin id>:<command>, in lowercase words joined by hyphens |
Summary | The one line the listing prints beside the name |
Args | The names of the positional arguments, in order, each one required |
Flags | Declares the command’s own flags on a flag.FlagSet. The flags h, help, yes, json and as belong to the command line |
Needs | The names of the flags every run must set, each one declared by Flags and taking a value |
Writes | Makes the command a dry run until -yes |
JSON | Offers -json |
Capability | A capability the core or a plugin declares, such as manage_users or notes.manage, which adds -as <email> |
Run | Does the work |
Run receives a sdk.Call. Args holds the arguments, and Flags
maps each of the command’s own flags the line set to its value as
text. Stdout takes the answer, Stderr takes progress and
warnings, and Stdin holds any input. call.JSON reports whether
-json was passed, and call.Encode writes one JSON document to
Stdout. A command reads its settings and the database address
from the Deps the plugin kept at Register. Start never ran,
so a command opens what it needs inside Run and closes it before
it returns.
A command that sets Writes runs on every call, but call.Apply
stays false until -yes. The command line does not stop a write,
so Run checks call.Apply and, until it is true, prints what it
would change and changes nothing. The command line then adds
dry run, nothing changed, pass -yes to apply on stderr.
A command that names a Capability is refused before Run unless
the -as account exists, is enabled and activated, and holds a
role with that capability. Each run it applies is stored as one
record, which gophenberg account:records lists. Name a capability
the core declares, such as manage_users, or one your plugin
declares through RoleProvider, such as
notes.manage. No account carries a capability nobody declares, so
a command naming one refuses every account.
An error from Run exits with code 1. Wrap it in sdk.Misuse when
the command line itself is wrong, a bad argument value for example.
It then exits with code 2 and prints the command’s help under the
error. A missing argument or an unknown flag is already refused that
way. A command that breaks a rule, such as a name outside its
plugin’s id, a malformed or repeated name, an empty summary, no
Run, a flag the command line owns, or a needed flag it does not
declare, is dropped, and gophenberg check names it. The
commands page shows all of this from the
operator’s side.
Flags a run must set
Section titled “Flags a run must set”Flags declares the command’s own flags with Go’s standard flag
package, and Needs names the ones every run must set. This command
of an archive plugin brings back the rows archived since the day the
line names:
// restore returns archive:restore, which brings back the rows archived since the day -since names.func (p plugin) restore() sdk.Command { return sdk.Command{ Name: "archive:restore", Summary: "bring back the rows archived since one day", Flags: func(fs *flag.FlagSet) { fs.String("since", "", "first `day` to bring back, such as 2026-10-01") }, Needs: []string{"since"}, Writes: true, Run: func(ctx context.Context, call sdk.Call) error { day := call.Flags["since"] since, err := time.Parse(time.DateOnly, day) if err != nil { return sdk.Misuse(fmt.Errorf("archive:restore: -since %q is not a day like 2026-10-01", day)) } return p.bringBack(ctx, call, since) }, }}Add p.restore() to the list Commands returns. A line that leaves
-since out, or gives it empty text or only spaces, exits 2 with
gophenberg: archive:restore wants -since <day> and the help page.
The command line checks this as soon as it has read the line, before
it calls Run, so Run never has to look for a missing -since
itself. gophenberg archive:restore -h still prints the help page.
The placeholder day is the word in backquotes in the flag’s usage.
Without backquotes it names the kind of value, such as string or
int, or just value.
The command line checks the text the line types for the flag, not the
value the flag reads back. So a flag declared with fs.Func, which
keeps no value of its own, works in Needs too. A default does not
count. A flag declared as fs.Int("batch", 500, ...) and named in
Needs still stops a line that leaves -batch out. Each name in
Needs must be a flag that Flags declares and that takes a value,
unlike a bool flag. Otherwise the command line drops the command,
gophenberg check names it, and running it exits 1.
Needs only checks that a value is there. To stop a bad value, such
as -since soon, Run returns the error wrapped in sdk.Misuse, as
above, so the run exits 2 with the help page the same way.
Writing commands
covers Needs in full.
Roles and capabilities
Section titled “Roles and capabilities”A capability is one named permission, such as notes.manage. A role
is a set of capabilities an account holds. The core declares four
roles, admin, editor, author and member, and seven
capabilities. A plugin adds its own through RoleProvider, which
returns them as data:
// Roles returns the role the notes plugin brings and the capability it adds to editors.func (plugin) Roles() []sdk.RoleDeclaration { return []sdk.RoleDeclaration{ {Name: "archivist", Capabilities: []string{"notes.manage"}}, {Name: "editor", Capabilities: []string{"notes.edit"}}, }}The first entry brings a new role. The second adds a capability to a
role the core already has. In WordPress, these are add_role and
add_cap. The site declares every plugin’s roles into one
registry,
under these rules:
- A new capability starts with your plugin’s id and a dot, such
as
notes.manage, so two plugins never share one by accident. You may still grant a capability that already exists, such as the core’smanage_users. - The administrator carries every capability a plugin declares, so it can hand out your roles.
- Names use lowercase letters, digits,
_,.and-, start with a letter, and hold at most 64 characters. Role names take no prefix, and two plugins that declare the same role widen it together. - Order matters. Plugins declare in the order of their folders
under
plugins/. A plugin that grants another plugin’s capability must come after it, so name it after its parent, such asnotes-tagsafternotes. The idcoreis reserved. - A declaration that breaks a rule stops
serve,check,migrate,seed -yes, every plugin command and every account command exceptaccount:listandaccount:records, and the error names your plugin:plugin notes: goncierge: new capability outside the source's prefix "notes.": "manage_archive".
Ask for a capability, never a role name: session.Can("notes.manage")
in a route, and Capability: "notes.manage" on a command. The
account commands take your roles too:
gophenberg account:role maria@example.com archivist -yes -as admin@example.comAn account whose role nobody declares any more, after its plugin is removed, keeps the stored name and carries no capability.
The admin opens only for a role carrying access_admin, which the
core’s admin, editor and author carry. The core’s member
carries no capability: it signs in and keeps a session, but never
enters the admin. Your routes see members too, so ask session.Can before
a member acts, the way a forum asks whether it may post. A role you
declare for the admin needs access_admin beside its own
capabilities, and granting access_admin opens the admin’s content
and media to every account holding that role.
The signed-in account
Section titled “The signed-in account”A request reaches your routes only with a login, except on the
paths PublicPaths names. The host files the account on the
request’s context, and sdk.SessionFrom reads it:
session, ok := sdk.SessionFrom(r.Context())if !ok || !session.Can("manage_settings") { http.Error(w, "forbidden", http.StatusForbidden) return}ok is false on a public path, where nobody has to sign in. An
sdk.Session carries ID, an sdk.ID like an item’s, and the
account’s Email, Name and Role. Can reports whether the
account’s role holds a capability, such as manage_users or one a
plugin declares.
What the SDK withholds
Section titled “What the SDK withholds”The absences are deliberate, so build against them:
- No content writes. Plugins read published content, the editor is the one writer.
- No account changes. You read the signed-in account, and the SDK gives you nothing to change accounts with.
- No other account’s email address.
Accountsgives names, never addresses. The signed-in account’s ownEmailstays on itsSession.
Admin screens for plugins
Section titled “Admin screens for plugins”A plugin can add screens to the admin. Name the package in the
manifest’s frontend field and export an object called plugin:
export const plugin = { id: 'hello', routes: (parent) => [/* routes, as children of parent */], nav: [{ label: 'Hello', to: '/hello', icon: someIcon, capability: 'hello.manage' }],}make generate wires it in: routes mount inside the admin layout
and the rows of nav appear in the sidebar after the built-in ones.
Each row is a MenuItem: the label it shows, the address to, and
an optional icon, capability and count. No built-in plugin uses
this path yet, so expect to be the first through it.
A count is { value, label }: the number drawn after the label,
hidden at zero, and the translated sentence a screen reader reads for
it, such as 1 update available. The core’s Updates row counts the
update that waits this way. A plugin’s nav is plain data, so a count
there stays the same while the admin is open.
A row naming a capability shows only to an account whose role
carries it. The screen still opens from a pasted link, so the Go
routes your plugin serves must check session.Can themselves, as
the signed-in account shows. In the
browser, a screen asks the same question through the frontend SDK’s
can(session, capability), which reads the capabilities the
signed-in account carries:
import { can, useSession } from '@gophenberg/frontend-sdk'
const session = useSession().dataconst manages = can(session, 'hello.manage')The SDK names the core’s capabilities as constants, such as
MANAGE_USERS and UPDATE_CORE, so can(session, UPDATE_CORE)
asks whether the account may update Gophenberg.
A row can open a sub menu of its own, as the Site Editor’s Navigation
row opens the list of menus. Give the route a staticData.Sidebar
component that draws a NavigationScreen. The admin swaps the main
menu for it, slides it in, and puts Back at its top, which leads to
the list the admin opens on. Put its rows in a NavigationList, each
one a NavigationItem. A sub menu on a parent route stays while the
reader moves between the screens under it:
import { NavigationItem, NavigationList, NavigationScreen } from '@gophenberg/frontend-sdk'import { createRoute } from '@tanstack/react-router'import type { AnyRoute } from '@tanstack/react-router'
function HelloSidebar() { return ( <NavigationScreen title="Hello"> <NavigationList> <NavigationItem to="/hello/drafts">Drafts</NavigationItem> <NavigationItem to="/hello/archive">Archive</NavigationItem> </NavigationList> </NavigationScreen> )}
export const plugin = { id: 'hello', routes: (parent: AnyRoute) => [ createRoute({ getParentRoute: () => parent, path: '/hello', staticData: { Sidebar: HelloSidebar }, }), ], nav: [{ label: 'Hello', to: '/hello' }],}Leave out the screen’s back, so Back goes where the admin’s own sub
menus go. NavigationList also takes items, rows as MenuItem
data, and hides a row whose capability the reader lacks. A
NavigationItem hides itself when its address opens a route the
reader may not open. DrilldownItem draws a row that opens a further
sub menu, with a chevron, and MenuCount draws a number at the end of
a row, such as the updates waiting.
renderPluginAt from @gophenberg/frontend-sdk/testing mounts your
plugin inside the admin’s real sidebar, with Back, the focus moves and
the phone drawer. Pass session to seed the account a test reads, or
null for none. A row that names a capability shows only when that
account carries it. Leave session out and the test asks the server
for the account at /api/auth/session, so serve that address with
http and server from the same entry.
To move a plugin written for Gophenberg v0.19.0 or earlier:
- Replace the type
NavItemwithMenuItemfrom@gophenberg/frontend-sdk.NavItemis gone, with no alias. - If a route declares
staticData.Sidebar, draw it as aNavigationScreenwith its rows in aNavigationList, so it gets its title, Back and the focus the admin moves to it. - In a test through
renderPluginAt, seed a session that carries the capability a row names, or serve the session address. The test host now hides a row the reader cannot open, and asks the server for the session when the test seeds none. - Remove
StyleProviderand keep what it wrapped. The SDK no longer passes it on, with no alias, since the WordPress components now load their own styles into the admin page. - In your plugin’s
package.json, takemsw3 andvitest5.0.4 or newer. Thehttpandserverthat@gophenberg/frontend-sdk/testinghands out now need them. - If your plugin imports a
@wordpresspackage itself, take the major version the SDK pins. Every one of them moved a major, such as@wordpress/componentsfrom 42 to 43 and@wordpress/uifrom 0.24 to 0.25. - If your plugin imports
@gopherium/godminitself, move it from 0.18 to 0.31, the version the SDK pins.ConfirmBodyandRenameBodyno longer takefailure, andRenameBodyno longer takesbusy, so show a failure in a toast.useToaster().nameis gone, so put the whole name in the message.ListEmptytakesdescriptionin place ofhint, andactionsfor its buttons. The SDK now passes all of these on, so you can import them from it instead.LoadingRowsis gone, so pass the list’s loading state toisLoadingon DataViews, or showLoadingScreen.NavScreenandNavScreenPropsare nowNavigationScreenandNavigationScreenProps, which the SDK passes on.Frame.RailandFrameRailPropsareFrame.SidebarandFrameSidebarProps, andRAIL_BREAKPOINTisSIDEBAR_BREAKPOINT. godmin now needs@tanstack/react-router1.170.44 or newer. - If your plugin’s id is
about,update,server,plugin,theme,setup,buildorhealth, give it another one. These ids are now reserved, andmake generatestops on them withid "update" is reserved. Rename its folder underplugins/to match, and start the names of its commands and of the capabilities it declares with the new id.
The frontend SDK, @gophenberg/frontend-sdk, passes on a few icons
from @wordpress/icons, each named after the job it does in the
admin: audioIcon, authorIcon, backIcon, backupIcon,
brushIcon, categoryIcon, closeIcon, customPostTypeIcon,
downIcon, fileIcon, imageIcon, languageIcon, listIcon,
listViewIcon, mediaIcon, pageIcon, postIcon, redoIcon,
saveIcon, settingsIcon, sidebarIcon, sidebarRtlIcon,
trashIcon, undoIcon, upIcon, updateIcon, uploadIcon and
videoIcon. authorIcon is the one an
author cell shows when the site shows no avatars, postIcon the one
an empty content list shows, mediaIcon the one an empty media
library shows, and uploadIcon the one an upload button carries.
imageIcon, videoIcon, audioIcon and fileIcon are the ones a
media card draws for a file that shows no picture, picked by its
file type as WordPress picks them.
sidebarIcon is the one the editor’s Settings button carries, and
sidebarRtlIcon its mirror for a language written right to left.
saveIcon is the one Save draft shows on a phone, and closeIcon
the one a panel’s close button carries.
The sidebar rows carry the icons WordPress draws for the same rows:
postIcon for Posts and every type a site adds, pageIcon for
Pages, categoryIcon for Categories, mediaIcon for Media,
brushIcon for Themes, customPostTypeIcon for Content Types,
listIcon for Field Groups, languageIcon for Language,
settingsIcon for Settings and updateIcon for Updates.
Import them from the SDK, so the admin keeps one copy of the icon set:
import { trashIcon } from '@gophenberg/frontend-sdk'A write that fails never shows inside a dialog. Say why in a toast
at the bottom of the screen, as WordPress does. useToaster from the
SDK hands you the admin’s own toasts:
const toaster = useToaster()
toaster.show(failure.message)To confirm an action outside a list, such as a button in your
screen’s header, use ConfirmDialog from
@gophenberg/frontend-sdk/dialogs. It draws the WordPress modal, a
sheet along the bottom of the screen on a phone, with Cancel
focused. Leave title out on a confirm that removes something, so
the question is the only text. What onConfirm returns decides when
the dialog goes. For a button, make it a plain function that returns
nothing. The dialog then closes at once while your write runs, as the
editor’s Move to trash does, and the button that opened it shows the
work:
import { Button, useToaster } from '@gophenberg/frontend-sdk'import { ConfirmDialog } from '@gophenberg/frontend-sdk/dialogs'
const remove = () => { setRemoving(true) removeItem(item.id) .then(() => toaster.show(done)) .catch((failure) => toaster.show(failure.message)) .finally(() => setRemoving(false))}
<Button variant="outline" loading={removing} onClick={() => setAsking(true)}>{label}</Button>{asking ? ( <ConfirmDialog confirmLabel={label} cancelLabel={cancel} onConfirm={remove} onClose={() => setAsking(false)}> {question} </ConfirmDialog>) : null}An async function always returns a promise, which keeps the dialog
open, so leave onConfirm plain. Return the write’s promise only
for a confirm on a row of a list you draw yourself, outside DataViews,
as WordPress does for a row’s own menu. The dialog then stays open
with its button busy until the write ends. Put the .catch inside
and return what it answers, such as
() => removeItem(item.id).catch((failure) => toaster.show(failure.message)).
FormDialog from the same entry asks for a form from a button, as
WordPress opens Add Page: a title, the first field focused, and the
dialog left open after a failure so the reader keeps what they typed.
The SDK still passes on AlertDialog and Dialog from
@wordpress/ui. They float as a card on a phone, where WordPress
draws a sheet, so prefer the two dialogs above.
Popover from @gophenberg/frontend-sdk is the one from
@wordpress/ui. It anchors a small panel to a button, and it paints
above a dialog. The Popover from @gophenberg/frontend-sdk/editor
is a different one, from @wordpress/components. Reach for it inside
the block editor, and for its Popover.Slot, which a dialog needs to
show the controls a components overlay draws.
A block that fails at something, such as an upload the server
refused, leaves a message for the block editor and draws nothing
itself. useBlockNotices from @gophenberg/frontend-sdk/editor
hands you each message, so a screen holding the block editor can show
it, in a toast for example.
A field the reader has to fill, or that the server may refuse, draws
through ValidatedInputControl from @gophenberg/frontend-sdk, as
the Email and Name of Add User do. Give it required and its label
ends in (Required). Its message shows under the field once the
reader leaves it or sends the form. To show the server’s reason
about that field there, such as a taken email, pass
customValidity={{ type: 'invalid', message }}. Then call the
form’s reportValidity() in an effect that runs once the message is
set, as Add User does. The reader may have sent the form with Enter
from that very field. The field was never left, so its message stays
hidden. reportValidity() shows it and moves the focus to the field.
Set customValidity back to undefined once the reader changes the
field, since the browser holds back a form while one of its fields
is invalid. A failure about no one field still goes to a toast.
A confirm on a list row is different: WordPress draws it inside the
list’s own modal. A confirm that removes something, such as Move to
trash, hides the header, so give that row action
hideModalHeader: true. A plain confirm, such as making an item the
default, keeps its header, which shows the action’s modalHeader or
else its label. Either way, give the row action
modalFocusOnMount: 'firstContentElement' and render RunConfirm
with the question as its child, the words of Cancel and of a
button named after the action, and run, a function that takes the
picked rows and settles once your screen shows how it went. It keeps
Cancel inert while the run goes and closes once it settles.
Import RunConfirm from @gophenberg/frontend-sdk, beside
useListRun and useBulkRun, the hooks the admin’s own lists run
their actions with. useListRun holds the ticked rows and the focus
after a run. It also hands out refreshing, which you pass to the
isLoading of your DataViews beside your own loading state, so the
old rows stay on screen, dimmed, while the list reloads.
useBulkRun makes one call per picked row. The list shows as
reloading as the first call that works ends. One toast shows as the
last call ends, in the words you pass as BulkWords: the failure
words when a row failed, else the done words. Your list then reloads.
As the list starts to reload, its region takes the focus from the table or the footer, and after a run started from the keyboard it draws the focus ring. Once the new rows land, the focus goes back to the control the reader pressed, or to the first control of the row in its place. It stays on the region when that control is a primary action, so a one click action of your plugin never takes a second Enter meant for another row.
A write to one row, such as a rename, runs the same way: pass that
row alone to useBulkRun. For a write that is no run, show its toast
as the call ends, then mark the list around your reload:
const ended = run.onRefresh()await refresh().then(ended, ended)For a row action that asks for more, the SDK passes on the bodies
the admin draws in a row modal. ConfirmBody asks a question you
run yourself. RenameBody asks for a new name. Give its button the
label Save, as WordPress does, close the modal the moment the
reader saves, then write. FormBody holds any fields, with kind
set to edit, copy or create to space its buttons as WordPress
does. A copy, or a change to several rows, keeps the modal open with
busy until the write ends. Taking all of these from the SDK keeps
your plugin on the admin’s own copy.
A modal that stays open during its write, such as a ConfirmBody
you run yourself or a busy FormBody, closes through
useCloseWhileOpen(closeModal). Every dialog on a row gets the same
closeModal, so a write that ends after the reader dismissed your
modal and opened another one would shut the new one. The close
useCloseWhileOpen returns does nothing once your modal left the
screen. A dialog your screen holds open on one row loses the button
that opened it when the list draws that row again, and the focus
falls to the page. useFocusBack finds the row again and puts the
focus back on the Trigger that focusedTrigger() noted when the
dialog opened. Mark the title cell of each row with the id DataViews
keys the row by, as data-item-id. useListRun reads the same mark
to find an item a reload moved, before the focus falls to the row in
its place. focusInDialog() tells whether a dialog holds the focus,
for a write you finish yourself outside a run.
A rename, or a form that closes before its write, is gone by the time
a write fails. Keep what the reader typed, so the next open of the
modal starts from it and the reader can try once more.
useUnsavedText from the SDK holds that text, by item id, for as long
as the screen stays. Keep the store in the hook that builds your
actions, never in the modal, which goes the moment the reader saves.
Pass the item’s kept text as the first value of the field. Clear the
item’s text before each write, so a save that works leaves nothing
behind. markLatest marks the write as the latest one sent to the
item and returns a check. Keep the failed text only while that check
holds, so an earlier save that fails late never overwrites what a
later save sent:
import { RenameBody, markLatest, useToaster, useUnsavedText } from '@gophenberg/frontend-sdk'import type { Action } from '@gophenberg/frontend-sdk/dataviews'import { useMemo } from 'react'
function useRenameAction(): Action<Note> { const toaster = useToaster() const renames = useUnsavedText() return useMemo<Action<Note>>( () => ({ id: 'rename', label: 'Rename…', modalHeader: 'Rename', modalFocusOnMount: 'firstContentElement', RenderModal: ({ items: [note], closeModal }) => ( <RenameBody name={renames.get(note.id) ?? note.title} fieldLabel="Name" submitLabel="Save" cancelLabel="Cancel" onSubmit={(title) => { closeModal?.() renames.delete(note.id) const stillLatest = markLatest(renames, note.id) renameNote(note.id, title) .then(() => toaster.show('Name updated.')) .catch((failure) => { if (stillLatest()) { renames.set(note.id, title) } toaster.show(failure.message) }) }} onCancel={closeModal} /> ), }), [toaster, renames], )}The store holds any value, so a form with several fields keeps them
all, as useUnsavedText<NoteFields>(). Type a store you pass on with
UnsavedText, from the SDK too.
ListEmpty is what your list shows when it has no rows. It titles
the empty list one level under your page’s title, as the admin’s own
lists do. Pass it to DataViews as empty, with an icon and a short
title with no full stop. An optional description goes under the
title, and actions holds the buttons under that. Draw your add
button there at its default size.
When a search or a filter emptied the list, show ListNoResults
instead. It takes no props, and the admin already loads its words.
viewNarrows tells the two cases apart:
import { ListEmpty, ListNoResults, postIcon, viewNarrows } from '@gophenberg/frontend-sdk'import { DataViews } from '@gophenberg/frontend-sdk/dataviews'
const empty = viewNarrows(view) ? ( <ListNoResults />) : ( <ListEmpty icon={postIcon} title="No notes yet" actions={<AddNote size="default" />} />)
<DataViews {...props} empty={empty} />Versions
Section titled “Versions”Each version below says what it adds and what it changes. When a
change stops a plugin from compiling, To move lists the steps.
To take a version, pass its number to go get, such as
github.com/gopherium/gophenberg/sdk@v0.5.0.
Your plugin compiles into Gophenberg, so it builds against the SDK inside the Gophenberg you build. Build with one that holds the version your plugin requires, or a later one.
v0.5.0
Section titled “v0.5.0”Tagged 2026-10-14. A plugin can show who wrote something.
- New: the
Accountsfield onDeps, anAccountReader. ItsPeoplemethod takes many account ids and an avatar size, and returns the public face of each account in one call. See reading account names. - New: the
Persontype, withID,Name,Role,AvatarandDisabled, and never an email address. - Nothing breaks for a plugin that names the fields of
Deps.
v0.4.0
Section titled “v0.4.0”Tagged 2026-10-12. A plugin can declare roles and capabilities.
- New: the
RoleProviderinterface. A plugin with aRolesmethod returning[]sdk.RoleDeclarationbrings new roles, or adds capabilities to roles the site already has. See roles and capabilities. - New: the
RoleDeclarationtype, a role’sNameand theCapabilitiesit carries. - A command’s
Capabilitycan now name a capability your plugin declares, such asnotes.manage. Before, only the core’s capabilities worked. - In the frontend SDK, which ships inside Gophenberg with no versions
of its own,
cantakes the signed-in session instead of its role, and a nav row can name thecapabilityit needs. - Gophenberg built after this version opens the admin only for a role
carrying
access_admin. Before, every role entered it.
To move:
- If a screen calls
can, pass it the session, as incan(session, 'hello.manage'), where you passedsession.role. - If a role your plugin declares should work in the admin, add
access_adminto itsCapabilities.
v0.3.0
Section titled “v0.3.0”Tagged 2026-10-10. A command can name the flags every run must set.
- New: the
Needsfield onsdk.Command, the names of the flags every run must set. The command line refuses a run that leaves one out beforeRunstarts. See flags a run must set. - Nothing breaks. A command that looks for a missing flag inside
Runcan name the flag inNeedsand drop that check.
v0.2.0
Section titled “v0.2.0”Tagged 2026-10-09. Each plugin gets a capped share of the site’s database.
- New: the
DBfield onDeps, the plugin’s share of the site’s one database pool. See the database. - New types for it:
DB,Tx,Querier,Rows,Row, andEnginewith the valuesPostgresandSQLite. The site reportsPostgrestoday. - New: the
HostOnlytype, which the site embeds in the share it lends. - Nothing breaks.
DatabaseURLstays, so a plugin that opens its own connection keeps working. To use the share instead, keepdeps.DBinRegister, use it fromStarton, and stop opening a pool of your own.
v0.1.0
Section titled “v0.1.0”Tagged 2026-10-08. The SDK becomes a Go module of its own.
Before this version, the sdk package lived inside the Gophenberg
module, and its last release there was Gophenberg v0.18.2, which
holds the same package as v0.18.1. The import path stays
github.com/gopherium/gophenberg/sdk, so your import lines do not
change. What changes is the module your plugin requires, and the SDK
now names only its own types and the standard library’s. Compared
with Gophenberg v0.18.2:
- The SDK is the module
github.com/gopherium/gophenberg/sdk. Its versions come from tags such assdk/v0.1.0. Item.IDandSession.IDare ansdk.ID, no longer auuid.UUIDfromgithub.com/google/uuid.NewSessiontakes ansdk.IDtoo. Text and JSON show the same 36 characters as before, and reading one from text accepts only that form.Plugin,Migrator,RouteProvider,PublicPathProvider,Command,Call,CommandProviderandEnvare the SDK’s own types now, no longer other names for pluginkit’s and gonsole’s. The lifecycle interfaces keep their methods, so a plugin that implements them needs no change.CalllosesEnv,Describe,DatabaseURL()andPlugins().CommandlosesMigrates.Env.DurationandEnv.Counttake no bounds any more, andEnv.Timeoutsis gone.Env.Countsis new.Misuseis a function now, andErrMisusedis new, soerrors.Is(err, sdk.ErrMisused)spots a misused command line.- New: the
Descriptionfield onTypeDeclaration.
To move:
-
Swap the module your plugin requires:
Terminal window go mod edit -droprequire=github.com/gopherium/gophenberggo get github.com/gopherium/gophenberg/sdk@v0.1.0go mod tidyKeep no requirement on Gophenberg v0.18.2 or earlier. Each of those releases holds the
sdkpackage too, so Go stops the build withambiguous import. -
Where you still need a
uuid.UUID, convert it. Both are sixteen bytes, souuid.UUID(item.ID)andsdk.ID(someUUID)work. -
A command reads its settings and the database address from the
Depsit kept atRegister,deps.Envanddeps.DatabaseURL, not from theCall. -
Drop
Migratesfrom your commands. Check a limit such as a highest count yourself, afterEnvreads the value. -
Compare with
sdk.ErrMisusedwhere you compared withgonsole.ErrMisused.