Skip to main content

More extension points

Actions​

An action is a function one plugin answers and anyone can call.

app.registerAction("hello.greet", async (name: string) => `Hello ${name}`);

const text = await app.invokeAction("hello.greet", "Ada");

With no plugin answering, invokeAction returns undefined. Termix itself calls a few actions by name, like host.openFiles, and whichever plugin registers it answers.

Slots​

A slot is a place in the UI another plugin draws into. The owner declares it with app.declareActionSlot (and lists it in contributes.actionSlots). Others fill it:

app.registerAction("hello.wave", (context) => wave(context));

app.registerSlotContribution("terminal.toolbar", {
actionId: "hello.wave",
titleKey: "toolbar.wave",
icon: Hand,
kind: "button",
});

A button runs its action when pressed. A component contribution draws whatever you give it, with the slot owner's props. A data contribution gives plain values that Termix draws (see Data slots below). when hides it when it doesn't apply.

Some slots you can fill:

SlotWhere
terminal.toolbar, terminal.sidePanel, terminal.overlayThe SSH terminal.
dashboard.countersDashboard cards.
admin.userTabsA tab on a user's page in admin settings.
hosts.importMenu, hosts.panelThe hosts panel.
credentials.rowActionsButtons on key rows, run with { id, name }.
shell.overlayRendered once at the root of the app, for UI that is always mounted.
shell.rightEdgeThe right edge of the window. Whatever width it takes pushes the page over.
tab.menuA tab's menu.

Data slots​

Small things drawn once per host, tab or credential are data, not components. A component from a plugin that runs in a frame costs one frame per row, so a dashboard with 20 hosts would load 20 frames. Return plain values instead, and Termix draws them the same way for every plugin. Needs plugin API 2.6.

app.registerSlotContribution("dashboard.hostRow", {
actionId: "hello.row",
titleKey: "row.title",
kind: "data",
useValue: (context, rowKey) => {
const load = useLoad(Number(rowKey));
return load
? { shape: "bars", items: [{ label: "Load", value: load / 100 }] }
: null;
},
});

useValue is a hook. It runs once for each row on screen, with the owner's context and the row key. In a frame it runs in your background frame and only the values cross. Return null to draw nothing.

ShapeValue
barsitems: [{ label, value (0 to 1), tone, detail }]
statitems: [{ label, value, unit, tone, tooltip }]
badgelabel, tone, tooltip, actionId
dottone, label
texttext, tone, tooltip, actionId

Tones are default, good, warn, bad and muted. An actionId must be one of your own actions.

Data slotRow keyContext
dashboard.hostRowHost idhostId, host, online
dashboard.hostRowBadgeHost idhostId, host, online
homepage.hostMetricsHost idhostId, online, shownMetrics
terminal.toolbarStatusTab idhostId, host, isConnected, active
credentials.badgesCredential idcredentialId

Host badges, status indicators and host editor toolbar items take useValue(host) the same way. To own a data slot, declare it with accepts: ["data"] and draw it with DataSlot from @termix-ssh/plugin-sdk/ui. termix-plugin validate warns when a component goes into a data slot.

Components​

Offer a component by id and others render it with PluginComponent:

app.registerComponent("hello.badge", HelloBadge);

<PluginComponent id="hello.badge" name="Ada" />;

Start the id with your own plugin id. The props are your contract, so document them.

Extensions​

An extension point is a named list one plugin reads and others add to. The Homepage plugin reads homepage.widgets:

app.registerExtension("homepage.widgets", {
id: "hello.widget",
titleKey: "widget.title",
component: HelloWidget,
});

Other plugins' parts in a frame​

A plugin that runs in a frame can show other plugins' parts: slots it declared, extension points or component ids under its own plugin id, and any id it lists in manifest contributes.uses. Read them as usual (useSlotContributions, ComponentSlot, useExtensions, PluginComponent). Each part you get is a placeholder, and Termix draws the other plugin's view in its own frame over that spot. Needs plugin API 2.7.

  • The part is clipped to your frame and hides under your open menus and popovers. The UI kit's menus, popovers, sheets and dialogs do this for you. For one you draw yourself, use useForeignOccluder or ForeignOccluder.
  • fill parts take the box you give them, content parts take your width and their own height, inline parts size to themselves. Use ForeignSlot to add a class or style.
  • Wrap an edit mode in ForeignInteractive interactive={false} so parts let drags through. TileGrid does this while editing.
  • A slot owner can declare fit: "overlay" for parts drawn over something, like prompts over a terminal. They are see-through and only take clicks while they show something.
  • Props cross as data, functions by reference. A host you pass reaches the other plugin as its own copy of that host. You never get a handle on the other plugin's view.

In tests, pass the parts you expect to renderWithApp as others.

Onboarding steps​

app.registerOnboardingStep adds a step to first-run setup. New users see it in their setup. People who already finished see only your step the next time they open Termix. Give it a version and bump it when the step changes enough to show again.

Keybindings​

Declare an action in contributes.keybindingActions, register it with app.registerKeybindingAction, and give it a default with app.registerKeybindingDefault. Users rebind it in Settings, Keybindings.

Command palette​

app.registerPaletteEntry adds one entry. app.registerPaletteGroup adds a searchable group, loaded every time the palette opens.

Dashboard cards​

Declare the id in contributes.dashboardCards and register the component with app.registerDashboardCard.

The dashboard is a 12 column tile grid. defaultSize: { w, h } sets the width in columns and the height in px when someone adds the card. A card that can show many things, like one status out of many, can pass entries(language): each entry is its own line in the add list with a title, a group and a config. The card gets that copy's config as a prop, can change it with setConfig and knows when the user is arranging the dashboard from editMode. Keep config small, it is saved in one line. Termix 26.11.1 and later.

app.registerDashboardCard({
id: "status",
titleKey: "card.status",
defaultSize: { w: 4 },
entries: async () => [
{ key: "disk", title: "Disk space", config: { check: "disk" } },
{ key: "load", title: "Load", config: { check: "load" } },
],
component: ({ config }) => <StatusTile check={String(config?.check)} />,
});

Desktop app​

ctx.desktop.openIsolatedWindow opens a URL in its own window in the desktop app, with its own cookies. app.desktop.available tells the frontend it runs in the desktop app. These need the desktop:window capability.