Editor extensions
Blocks, components, Build a block, channels, history, the site view, site settings, the Design panel and the command palette are all extensions. Each is two small files: one for the editor server and one for the page.
An extension has a server half, src/extensions/<name>.js, and a browser half, editor/ext-<name>.js. The server loads every file in src/extensions/ when it starts. The editor loads every ext-*.js file on every page.
The server half
Export an async setup(ctx) that returns what the extension adds:
export async function setup(ctx) {
return {
// Answer a request. Return true if you answered it.
async handle(req, res, url) {
if (url.pathname !== '/__verso/word-count') return false;
const page = ctx.renderUrl(url.searchParams.get('url') || '/');
const words = page.html.replace(/<[^>]*>/g, ' ').split(/\s+/).filter(Boolean).length;
ctx.sendJSON(res, 200, { ok: true, words });
return true;
},
// Extra properties merged into the editor's data for each page.
editorData(site, page, template) {
return { wordCountReady: true };
},
};
}
handle is called for each request the editor’s own routes don’t answer, in file-name order, until one returns true. Keep your routes under /__verso/. Whatever editorData returns is merged into the data the page’s editor receives.
What ctx holds
| Property | What it is |
|---|---|
root | The site’s folder |
broadcast(event) | Sends an event to every open editor page |
written | A Map of files Verso wrote itself, by relative path, so the file watcher ignores them. Add to it with hash() when you write a file |
hash(data) | The hash written expects |
relPath(file) | A path relative to the site, with forward slashes |
send, sendJSON | Write a response: sendJSON(res, status, body) |
readBody, readRaw | Read a request’s JSON body, or its raw bytes |
compile({ reload }) | Recompile the CSS |
renderUrl(url) | Render a page as the editor would, returning { status, html } |
css, cssError | The current stylesheet, and the error from the last compile, if any |
The browser half
Export init(verso). It runs once on every page the editor opens, after the editor itself.
export function init(verso) {
verso.menuItems.push({
label: 'Word count',
icon: '<svg …></svg>',
run: async () => {
const res = await fetch(`/__verso/word-count?url=${encodeURIComponent(verso.data.url)}`);
const { words } = await res.json();
verso.toast(`${words} words on this page`);
},
});
}
What verso holds
| Property | What it is |
|---|---|
root | The editor’s shadow root. Put your interface here, so the page’s styles can’t reach it |
data | The page’s editor data: its URL, fields, values, templates, pages and anything extensions added |
values | The page’s current field values |
queue(change), flush() | Queue a change to the page ({ fields: { name: value } }, or a title, description or date) and save it |
toast(message, kind, action) | Show a short message. Pass 'error' as the kind for a problem, and { label, run } as the action for a button like Undo |
menuItems | Push { label, icon, run } to add to the page menu and the command palette |
paletteItems | Push { label, run } to add to the command palette only. Create it first: verso.paletteItems = verso.paletteItems || [] |
addBarButton({ id, title, svg, onClick }) | Add a button to the editor’s bar. Below md the bar has no room, so the button is offered in the page menu instead, on its own |
settingsSections, openSettings() | Push { html, bind } to add a section to Page settings: html() returns its markup and bind(panel) wires it up. openSettings() opens the panel |
show(el), hide(el), esc(s), icon(name) | Small helpers |
refreshStatus(), reload(), flash(el) | Update the publish status, reload the page when it’s safe to, or outline an element for a moment to show where something landed |
ui(classes) | Marks a class string for the editor’s own Elevate build |
Extensions can offer things to each other on verso too. The builder sets verso.builder.open(name), which opens a block in Build a block.
Styling an extension
The editor is styled with Elevate too, from its own tokens. Write every class string as ui("…"), so Verso’s build can find it, then run npm run build:ui in the Verso folder to compile the editor’s stylesheet. A class that isn’t in that build has no styles.