inspectors

Adds panels to the editor's right column for a step of your extension, or for every macro.

Details #

When someone selects a step or a macro in the editor, the right column shows its settings. The inspectors point adds extra sections to that column: a few labelled rows, some text and a status colour. Use it to explain a step, show what the settings add up to, or warn about a problem before the macro runs.

An inspector reads; it does not edit. The engine asks your handler when the selection changes and draws what comes back.

Declare it in switchboard.json under adds.inspectors:

{
  "adds": {
    "inspectors": [
      { "id": "repeat-size", "title": "Result size", "appliesTo": "repeat-text" },
      { "id": "macro-size", "title": "Macro size", "appliesTo": "macro" }
    ]
  }
}

And implement it:

import { defineExtension, inspector } from '@switchboard/sdk';

export default defineExtension({
  inspectors: [
    inspector('macro-size', ({ macro }) => ({
      rows: [{ label: 'Steps', value: Array.isArray(macro.do) ? macro.do.length : 0 }],
    })),
  ],
});

Gotchas #

The handler must answer within 5 seconds. A panel that fails or times out is skipped, so an inspector never gets in the way of editing.
It is asked often, as the person types. Keep it quick and do not call out to the network.
The values in step.params can be unfinished or contain {{ }} templates that only have a value when the macro runs.
Your own inspectors only see steps of your extension, unless appliesTo says macro.
Unknown keys in an entry are refused.

A complete extension using this point can be downloaded from the Full example section and edited: a panel for one step and a panel on every macro.

Manifest fields #

Field	Required	What it is
`id`	yes	Lowercase letters, digits and `.` `_` `-`, up to 64 characters, starting with a letter. Unique in the list.
`title`	yes	1 to 80 characters. Used as the panel title when the handler gives none.
`description`	no	Up to 1000 characters.
`appliesTo`	no	What the panel is for: `macro` for every macro, or a step type. Give a step type in full (`com.example.thing.make`) or short for your own (`make`). Left out, the panel appears under all of your extension's steps.

What the handler gets and returns #

The handler gets a target:

kind: step or macro.
macro: the macro the selection is in (id, name, and the rest of it: when, onlyIf, do).
step: for a step, its id, type and params as they are right now.

It returns a panel, or null to show nothing:

title: a heading (defaults to the manifest title).
rows: up to 50 { label, value } pairs. A value can be text, a number, a switch or null.
text: a paragraph, up to 20000 characters.
status: ok, warning or error, which colours the panel.

A panel with no rows and no text is not shown.