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>
textus-resource:<path>names one of the plugin's files (webview.asWebviewUri(path)writes the same).- The page is in the UI's language: Textus sets
<html lang>(alang="{{lang}}"left in the page takes it too) and makes the page again with the new strings when the language changes (Textus 1.4.3). Before 1.4.3 a plugin replaced{{lang}}and setwebview.htmlagain onenv.onDidChangeLanguageitself. - A webview shows pictures (
<img>, CSS) and frames from the HTTPS hosts its plugin'snetwork:permissions name, and nothing else from the network. For data, and for storage, it asks its plugin withpostMessage.api.getState()/api.setState(value)keep a little state while Textus runs. - A page out of sight (its tab behind another, its panel closed) may be
let go to save memory, and is built again from its HTML when shown. It
is told first:
api.onDidChangeVisibility(visible => …)(1.7) runs as it goes out of sight, the moment tosetStatewhat it should come back to (a scroll, a zoom, a filter not yet applied). Writing to the plugin's storage belongs there too, not on a timer the page may not live to run. - From 1.3.13 a page may go full screen (
element.requestFullscreen()); Esc leaves it. - The theme's colours and sizes are CSS variables that follow the theme
and dark mode, the same ones Textus draws with
(design-language.md): the interface's
colours
--ui-bg,--ui-surface,--ui-subtle,--ui-text,--ui-muted,--ui-accent(--ui-accent-textfor words),--ui-border,--ui-hover,--ui-selected,--ui-danger; the document's--doc-bg,--doc-text,--doc-accent,--doc-accent-text,--doc-mark,--doc-code-bg; text by role,--text-captionto--text-title; shapes,--shape-mfor a panel or card,--shape-sfor a box or row inside one,--shape-pillfor a button or chip;--control-height(-sm),--space-1to--space-6and--font-sans/--font-mono. Buttons, inputs,.toolbar,.listand.emptylook as Textus's own without any CSS of yours. - Motion is Textus's too:
animation: motion-enter var(--dur-medium) var(--ease-out) backwardsfor a part arriving,motion-exitfor one leaving, amotion-cascadecontainer for items one after another. With the system's Reduce motion they become fades. Animate onlyopacityandtransform. - A code block's frame grows with its page; others fill their place.
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.