These are the docs of plugin API 1.7, as Textus 1.4.3 had them. API 1.8 is the newest.

Plugin pages

A plugin draws what Textus can't draw for it - a board, a chart, a calendar - in a page of its own: a webview. This is how pages work, what they get from Textus, and the few rules that keep them looking like Textus. The design standard behind them is design-language.md §15.

Webviews

A webview is a sandboxed frame of HTML the plugin sets:

textus.views.registerWebview("jane.board.view", {
  async resolve(webview) {
    webview.onDidReceiveMessage((message) => {
      if (message.type === "hello") webview.postMessage({ type: "hi" });
    });
    webview.html = await ctx.plugin.readText("board.html");
  },
});
<link rel="stylesheet" href="textus-resource:board.css" />
<button id="hello">Hello</button>
<script>
  const api = acquireTextusApi();
  api.onMessage((m) => console.log(m.type));
  document.getElementById("hello").onclick = () =>
    api.postMessage({ type: "hello" });
</script>

Code blocks in an export

A page can't go into a PDF, a Word file or an HTML page, so an export asks each code block's page for a picture of itself with api.onExport: an SVG's markup or an image's data: URL, drawn for the exported page's theme ("light" for paper). The picture takes the drawing's place; a page that gives none exports as the block's source.

<div id="chart"></div>
<script src="textus-resource:lib/chart.min.js"></script>
<script>
  const api = acquireTextusApi();
  const chart = drawChart(document.getElementById("chart"));
  api.onExport(({ theme }) => chart.toSvg({ dark: theme === "dark" }));
</script>

Textus asks once the page has loaded (its scripts included), and waits a few seconds for an answer.

Textus's controls

A page shares Textus's stylesheets: buttons, inputs, .toolbar, .list and .empty look like Textus's own with no CSS of yours, and the tx- classes give the rest - tx-bar (a row of controls), tx-button (small, primary), tx-icon-button, tx-segmented / tx-segment, tx-chip, tx-tag (with data-tone), tx-card, tx-table in a tx-table-frame, tx-empty, and tx-icon with data-icon for Textus's icons. Lay them out with your own CSS, using only the variables above.

Menus are Textus's: api.menu(items, element) opens one under an element (items { label, value, checked?, danger?, items? }, "separator") and resolves with the value chosen, or null.

Dragging

HTML drag and drop doesn't work in a page: the Textus window takes it for dropping files, so the cursor shows a copy sign and nothing lands. Drag with pointer events instead - pointerdown, then pointermove and pointerup on window - and swallow the click the release sends. Textus's own official plugins share one small helper for this (shared/drag.js in textus-plugins): drag.reorder slides an item along its own row (tabs, columns) while the others make way, and drag.sortable moves it between lists with a lifted copy under the pointer (tx-drag-ghost; tx-drag-source marks where it will land). A table's row or column takes the editor tables' look: tx-table-grip with tx-table-grip-row or tx-table-grip-col is the pill to pull it by, tx-cell-lifted marks the pulled cells, and tx-making-room on the table lets the others slide aside (Textus 1.4.3).

Floating views

A floating view is a small page over the window or, on the desktop, over the whole screen - Desk Pet and Pomodoro are two. Declare it in contributes.floatingViews ({ id, title, width, height, place: "window" | "desktop" | "either" }), register its webview like any other, and open it with textus.layout.openFloating(id). The user drags, folds and closes it; layout.onDidChangeFloating says when, and layout.onDidTouchFloating when it was poked, petted or carried. Stop animating while it isn't visible.

This page is pages.md in the Textus repository.