Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Adding custom commands

An application can add its own commands to a <perspective-viewer>: to the right-click menu, as buttons on Datagrid rows or cells, and on pinned chart tooltips. One function declares them all, and decides per location which to show from what is there.

Declaring commands

setCommandSchema() takes a function from a context to the list of commands to offer for it, and the surfaces it should be evaluated for:

await viewer.setCommandSchema(
    (context) => {
        if (context.hit?.column_names[0] !== "security_id") {
            return { commands: [] };
        }

        return {
            commands: [
                {
                    kind: "Command",
                    key: "open-order-ticket",
                    label: `Open Order Ticket (${context.hit.value})`,
                    icon: "ticket",
                },
            ],
        };
    },
    { scopes: ["context-menu", "datagrid-cell"] },
);

The function must be synchronous and have no effects of its own. Calling setCommandSchema() again replaces it, and setCommandSchema(null) removes it. It is not part of save() or saveWorkspace(), and survives restore(), reset(), load() and eject().

Each entry of commands is one of:

kindFieldsDescription
"Command"key, label, disabled?, icon?, title?A row the user can pick
"Group"key, label, commandsA submenu of further entries

In the context menu, custom commands are shown above the built-in items. As a button, a command shows its label as text, preceded by its icon when it has one, drawn through the theme’s --psp-icon--<icon>--mask-image property. An application supplies its own icons by defining that property on the <perspective-viewer> with a url() to an SVG, which the plugins use as a mask. Its tooltip, in the menu and on a button, is title when given and the label otherwise, so a button can read “Buy” while its tooltip reads “Buy 100 PRSP”. A Group renders as one button that opens a menu.

Scopes

scopes names the surfaces the schema is evaluated for; it defaults to ["context-menu"], and an unknown scope rejects. The schema is never called for a surface outside its scopes, so a plugin pays nothing for a scope the application did not ask for.

ScopeWhere the commands appearEvaluated
"context-menu"The right-click menuOnce per open
"datagrid-row"A button column on every Datagrid rowOnce per row drawn
"datagrid-cell"Buttons beside every Datagrid cell valueOnce per cell
"chart-tooltip"A button row under a pinned chart tooltipOnce per pin

Each plugin can turn a surface off through its plugin_config, and offers the option only while the schema declares the scope. Call setCommandSchema before restoring one of these options; a value restored before its scope is declared is dropped, like any plugin_config key the plugin does not offer:

PluginOptionValues
Datagridcommand_column"left" (default), "right", "tree" (after the group columns), "none"
Datagridcommand_cellstrue (default) or false
Chartstooltip_commandstrue (default) or false

Chart hover tooltips are drawn on canvas and show no buttons; pinned tooltips do.

Handling a command

Picking a command fires perspective-command, whose detail carries the command’s key and the same context object the schema function was called with:

viewer.addEventListener("perspective-command", (event) => {
    const { key, context } = event.detail;
    if (key === "open-order-ticket") {
        openOrderTicket(context.hit.value);
    }
});

Invalidating commands

A command listener usually changes the state the schema reads: after “Flag order” runs, the same row should offer “Unflag order”. The viewer cannot see that, so the listener says so with invalidate(), which redraws each panel’s plugin from its current view, re-querying the schema for every rendered button surface, and resolves when the plugins have redrawn. Calls within one task run as one, and panel limits the redraw to one panel:

viewer.addEventListener("perspective-command", async (event) => {
    const { key, context } = event.detail;
    if (key === "flag") {
        flagged.add(String(context.hit.id));
        await viewer.invalidate({ panel: context.panel });
    }
});

setCommandSchema() with a new function or new scopes performs the same re-query. The context menu re-queries on every open.

The command context

FieldTypeDescription
locationPerspectiveCommandLocationThe scope the commands will be shown in
panelstring?The targeted panel; absent only at zero panels
tablestring?The name of the panel’s Table
pluginstring?The name of the panel’s plugin
view_configViewConfig?The panel’s view config, as from getViewConfig()
point{x, y}?Viewport coordinates of the right-click
hitPerspectiveHit?What the plugin rendered at the location

In the context menu, hit is present only when the right-click landed on something a plugin drew. It is absent over a panel’s tab, the status bar and the settings sidebar, and over empty space inside a plugin. In a button scope it is always present.

FieldTypeDescription
kind"cell" | "row" | "column"Which axes the location addresses
ynumber?The view row index, as drawn
xnumber?The view column index, as drawn
idScalar[]?The row’s index value(s), or its group_by path
row_pathScalar[]The row’s group_by values, outermost first
column_pathScalar[]The column’s split_by values, outermost first
column_namesstring[]The column targeted
valueScalar?The cell’s value, for a "cell" hit
configViewConfigUpdateA restore() patch selecting the target

A chart mark is a "cell" of its measure column, without a value.

config.filter is the panel’s filter plus one clause per group_by level of the row and per split_by level of the column, and, when the view is not grouped and the table has an index, one clause per index column from id. For a composite index, id is the key tuple in index order, such as ["AAPL", "Tech"], rather than the nested [["AAPL", "Tech"]] that to_json({ id: true }) reports. config.expressions is the panel’s expressions whenever it has any, so the patch is viewable when a filter names one. A flat row of an unindexed table has no stable identity, so its config selects only what the panel’s filter does.

The hit does not carry the row. A command that needs more of it fetches it in its listener, where async is available. y and x address the view as it was drawn and are stale after the next update on a live table; config identifies the row and column against the data, so table.view(context.hit.config) reads the row regardless of what has moved since:

viewer.addEventListener("perspective-command", async (event) => {
    const { context } = event.detail;
    const table = await viewer.getTable({ panel: context.panel });
    const view = await table.view(context.hit.config);
    const [row] = await view.to_json({ end_row: 1 });
    await view.delete();
    openOrderTicket(row);
});