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 blocks

Features 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:

app.ts
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

note.tsx
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:

sticker.ts
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.

View as Markdown