- Spreadsheet docs
- Developers
Control everything from code
The command layer of an embedded workbook - every ribbon control, menu row, shortcut and dialog has an id you can run, watch, cancel, hide or show from code.
Everything a user can do in an embedded workbook goes through one command layer. Each ribbon control, each row of its menus, each context menu row, each keyboard shortcut and each dialog has a stable id. With those ids your code can:
- run any of them (
wb.commands.execute), with a value where the control takes one, - check whether one can run now (
wb.commands.canExecute), - watch what users do (
after-command) and stop it (before-command), - hide controls, groups and whole ribbon tabs (
wb.ribbon.hide,hideGroup,hideTab), - add your own commands, buttons, menu items and shortcuts (see Ribbon, menus and commands).
The kinds of commands
| Id | What it is | Needs a page | Example |
|---|---|---|---|
edit.*, format.*, rows.*, cols.*, sheet.*, data.*, nav.*, view.*, file.*, theme.* | The API's own commands | Mostly no | format.bold, rows.insert, data.toggleFilter |
ribbon.<tab>.<name> | A built-in ribbon control, named from its English label | Yes | ribbon.home.bold, ribbon.insert.pivotTable, ribbon.pageLayout.margins |
<control>.<row> | A row of a ribbon control's menu | Yes | ribbon.home.borders.allBorders |
menu.<row> | A row of the right-click menu | Yes | |
grid.<name> | A keyboard shortcut of the grid (131 of them) | Yes | grid.italic, find, replace, format cells |
ui.<name> | A dialog or pane of the app (65 of them) | Yes | ui.insertPivotTable, ui.insertChart, ui.dataValidation, ui.protectSheet |
| your own | Commands you register | No | app.markReviewed |
wb.commands.list() lists every command with its label, whether it leaves an undo step, and needsPage. The API reference has the list of all commands and the commands of a mounted workbook. wb.ribbon.controls(tab) lists the controls of one ribbon tab, or of every tab, with their ids:
wb.ribbon.controls('Home');
// [{ id: 'ribbon.home.paste', label: 'Paste', tab: 'Home', runnable: false },
// { id: 'ribbon.home.cut', label: 'Cut', tab: 'Home', runnable: true }, …]
runnable controls can be run with execute. The others open a menu or a gallery: run one of their rows instead, or hide them. A control whose label follows the state keeps one id, so ribbon.review.protectSheet is also the id when the button reads Unprotect Sheet. The Draw tab's pens and the title bar's buttons don't have ids yet.
Run, check, watch and stop
JavaScript
import { mountWorkbook } from '@8sheets/core';
const wb = await mountWorkbook(document.querySelector('#sheet'));
// Run controls and dialogs.
wb.commands.execute('ribbon.home.font', 'Georgia'); // a control with its value
wb.commands.execute('format.bold'); // an API command
await wb.commands.execute('ui.insertPivotTable'); // resolves when the dialog is open
// Enable your own button only when the command can run.
const pivotButton = document.querySelector('#pivot');
wb.events.on('selection-changed', () => { pivotButton.disabled = !wb.commands.canExecute('ui.insertPivotTable'); });
// Stop what users try, and log what they do.
wb.events.on('before-command', (e) => {
if (e.source !== 'api' && e.name === 'ribbon.home.mergeCenter') e.cancel();
});
wb.events.on('after-command', (e) => console.log(e.source, e.name, e.args));React
import { useRef } from 'react';
import { Sheet } from '@8sheets/react';
export function Workbook() {
const sheet = useRef(null);
const run = (id, args) => sheet.current?.workbook?.commands.execute(id, args);
return (
<>
<button onClick={() => run('ui.insertPivotTable')}>PivotTable</button>
<button onClick={() => run('ribbon.home.font', 'Georgia')}>Georgia</button>
<div style={{ height: 560 }}>
<Sheet
ref={sheet}
onBeforeCommand={(e) => { if (e.source !== 'api' && e.name === 'ribbon.home.mergeCenter') e.cancel(); }}
onAfterCommand={(e) => console.log(e.source, e.name, e.args)}
/>
</div>
</>
);
}Vue
<script setup>
import { Sheet, useSheet } from '@8sheets/vue';
const { sheet, workbook } = useSheet();
const run = (id, args) => workbook.value?.commands.execute(id, args);
function guard(e) {
if (e.source !== 'api' && e.name === 'ribbon.home.mergeCenter') e.cancel();
}
</script>
<template>
<button @click="run('ui.insertPivotTable')">PivotTable</button>
<button @click="run('ribbon.home.font', 'Georgia')">Georgia</button>
<Sheet ref="sheet" style="height: 560px" @before-command="guard" @after-command="(e) => console.log(e.source, e.name, e.args)" />
</template>Angular
import { Component } from '@angular/core';
import { SheetComponent, SheetEventPayload, SheetsWorkbook } from '@8sheets/angular';
@Component({
selector: 'app-workbook',
imports: [SheetComponent],
template: `
<button (click)="run('ui.insertPivotTable')">PivotTable</button>
<button (click)="run('ribbon.home.font', 'Georgia')">Georgia</button>
<eight-sheet class="grid" (ready)="wb = $event" (beforeCommand)="guard($event)" (afterCommand)="log($event)" />
`,
styles: `.grid { height: 560px; }`,
})
export class Workbook {
wb?: SheetsWorkbook;
run(id: string, args?: unknown) {
this.wb?.commands.execute(id, args);
}
guard(e: SheetEventPayload) {
if (e['source'] !== 'api' && e['name'] === 'ribbon.home.mergeCenter') e.cancel();
}
log(e: SheetEventPayload) {
console.log(e['source'], e['name'], e['args']);
}
}execute(id, args)runs a command and returns its result. Aui.*command returns a promise that resolves once its dialog or pane is open. Any command returnsundefinedwhencanExecutesays no or a listener cancelled it. Edits a command makes become one undo step; a dialog leaves its step when the user confirms it.canExecute(id, args)runs nothing and fires no event. It says whether the command exists, has the page it needs and passes its own check.before-command(cancellable) fires before every command: those your code runs (source: 'api') and the built-in controls the user uses, withsourceribbon,menuorkey. Cancelling it stops the control, and a list or checkbox shows its old value again. Forapi, sete.argsto change what the command gets; a built-in control keeps its own.after-commandfires after every command, withname,args,resultandsource.command-executedstill fires only forexecute.- Running a control of a ribbon tab that isn't on screen shows that tab first, as switching to it would, so its menus open at its button.
Hide controls, groups and tabs
wb.ribbon.hide('ribbon.insert.pivotTable'); // one control, or one row of its menu
wb.ribbon.hideGroup('ribbon.home.bold'); // the whole group that holds Bold
wb.ribbon.hideTab('Draw'); // a built-in tab by its English name
wb.ribbon.hidden; // { controls, groups, tabs } hidden so far
wb.ribbon.show('ribbon.insert.pivotTable'); // and showGroup, showTab
Hiding is a matter of the user interface: code can still run a hidden control with execute, and its keyboard shortcut still works unless you turn the key off with wb.commands.disableKey or cancel it in before-command. What you hide isn't saved with the workbook, so hide it again after each mount. To lose the ribbon entirely, leave it out at mount with parts: { ribbon: false }; it then doesn't load, and it can't be brought back without mounting again.
Lock the interface down
Hiding, cancelling and the read-only setup combine into a workbook that offers exactly the tools you choose. The Lock down the UI recipe puts them together.
const allowedRibbon = new Set(['ribbon.home.bold', 'ribbon.home.italic', 'ribbon.home.underline']);
const blockedKeys = new Set(['grid.insertSheet', 'grid.insertCells', 'grid.deleteCells', 'grid.macros']);
wb.events.on('before-command', (e) => {
if (e.source === 'ribbon' && !allowedRibbon.has(e.name)) e.cancel();
if (e.source === 'key' && blockedKeys.has(e.name)) e.cancel();
});
Keys fire before-command too, including moving around (grid.moveDown and the like), so block keys by name rather than allowing a short list.
Cancelling a command stops that path. Edits can also arrive by other routes, such as typing in a cell, dragging or pasting, which before-change covers; see Read-only workbooks.
Limits
- Ids exist only on a mounted workbook; a headless workbook has the API commands and your own.
- The Draw tab's pens and the title bar's buttons have no ids yet.
- What
hide,hideGroupandhideTabhide isn't saved with the workbook. - A ribbon left out at mount can't be shown later;
setOptions({ parts: { ribbon: true } })throws aTypeError.