DocsPlugins
Blocks
The document editor behind Pages and the CMS, for any app: paragraphs, headings, lists, tables, charts and articles.
The blocks plugin edits and shows a document made of blocks. Pages and the CMS install it for you. To add it yourself:
sluurp plugin add blocksFeatures include:
- Text, three sizes of heading, bulleted, numbered and to-do lists, quotes, callouts, code and maths
- Tables, grids, charts from a collection, figures, pull quotes and a page’s contents
- Typing shortcuts as you would expect:
#for a heading,-for a list,[]for a to-do,/for the menu of blocks - Articles set in columns, with lines that run round their pictures
- Kinds of block added by other plugins, such as a whiteboard with Board
There is nothing to set up in the admin.
Set it up once
The editor speaks through your app: its words, its addresses, its messages. Tell it how, once, when your app starts:
import { configurePages, blocksTranslations } from "plugin:blocks";
i18n.add(blocksTranslations); // its words, in English, French, Romanian and German
configurePages({
client: sluurp,
me: () => currentUser(),
t: (key, vars) => i18n.t(key, vars),
href: (route, id) => `#/${route}${id ? `/${id}` : ""}`,
detail: () => currentPageId(),
notify: (message) => toast(message),
complain: (error) => toast.error(String(error)),
});With Pages installed, call Pages’ own configurePages and add pagesTranslations instead: they set up the block editor as well.
Edit a document
import { BlockEditor } from "plugin:blocks";
<BlockEditor blocks={note.blocks} editable onChange={(blocks) => save({ blocks })} table={() => null} />blocks is the document as you saved it: an array, kept wherever your app keeps it, such as a JSON field. onChange gets the whole array a moment after anything changes. With editable={false} the same component shows the document read-only.
table draws a table block. A page that has tables passes its own renderer; otherwise return nothing. Pass page, the document’s id, to make what is on it live for everyone looking at it, such as a whiteboard.
Add a kind of block
Another plugin can add a kind of block, offered in the / menu once it is installed. Board adds a whiteboard this way:
import { addBlockKind } from "plugin:blocks";
addBlockKind({
type: "sticker",
key: "sticker.name", // its name in the menu, a key of your app's words
icon: '<circle cx="12" cy="12" r="10"/>',
make: () => ({ type: "sticker", text: "" }),
view: Sticker, // drawn with { block, editable, page, onChange }
});A document that holds a kind of block whose plugin isn’t installed shows a notice in its place, and keeps the block as it is.