Quick start
In an editor with TableKit, a Mermaid Diagram Renderer and chart: { linkTables: true } in
Diagrams.configure(), as in the Tables quick start, take this
table:
| Step | Next | Team | Label | Shape |
|---|---|---|---|---|
| Order in | Check stock | Sales | start | |
| Check stock | Pack, Back order | Warehouse | in stock, missing | decision |
| Pack | Invoice | Warehouse |
With the selection in the table, this draws it below:
editor.commands.insertDiagramFromTable({
columns: { step: 'Step', next: 'Next', lane: 'Team', label: 'Label', shape: 'Shape' },
title: 'Order process',
})One undo takes back a table edit and the diagram's update. Without chart.linkTables, or with
chart: false, which leaves out charts, these commands return false.
How the table is read
columns maps each role to a column by header text, ignoring case, or by position from 0.
Without it, the extension guesses from headers such as Step, Task, Next, Then, Team, Owner, Label,
Condition and Shape:
| Role | Required | Cell holds | Becomes |
|---|---|---|---|
step | Yes | The step's name | A node |
next | Yes | The steps that follow, separated by commas | Arrows to those steps |
lane | No | A lane name | A framed group, a subgraph |
label | No | Arrow labels, separated by commas | Text on the arrows |
shape | No | A shape name, see Shapes | The node's shape |
When no header names step and next, it takes the first columns no other role took.
A step named only in a next cell is drawn too, rows with the same step name are one node, and a
row with an empty step cell is skipped.
A label cell gives one label per next step when the counts match, otherwise the whole cell to
every arrow.
Shapes
| Shape | Cell text |
|---|---|
| Box | box, rect, task |
| Rounded box | rounded, round |
| Stadium | start, end, stadium, terminal |
| Diamond | decision, diamond, gateway |
| Circle | circle, event |
| Parallelogram | data |
| Cylinder | database |
| Subroutine | subroutine |
Any other text gives a box, and case does not matter.
When the table changes
These edits do more than redraw the diagram:
- Renaming a step in its row renames it in every
nextcell too, ignoring case. An edit that also adds or removes rows or moves columns is not followed as a rename. - Emptying a step cell, or giving it another step's name, is not a rename.
- Changing a lane cell moves that one step, unlike
renameDiagramLane. - Removing a column that the link names by its header text keeps the diagram as it is until the column is back. A column given by its position reads whichever column is there now, and keeps the diagram as it is only when the table has no column at that position.
- Deleting the table leaves the diagram with its last source and its link, until a new source
or
detachDiagramFromTableends it. - Changing the source with
updateFlowDiagramends the link. - Double-clicking a shape edits nothing, because the text belongs to the table.
Stored in the document
| Where | What |
|---|---|
The diagram's options.link | { tableId, columns, header?, range? } |
| The table | A chartTableId attribute, added by chart.linkTables |
Read the link with flowDiagramLink(diagram) from @tiptap-pro/extension-diagrams on a
listDiagrams() entry, or as link in
listDiagrams(). updateLinkedTable
changes how the table is read.
Commands
Each of these commands returns false and changes nothing when it cannot act.
insertDiagramFromTable
Inserts a flowchart of the table at the selection, or of the one at table, directly below that
table rather than at the cursor, without selecting it.
This call reads a table without a header row. to: -2 counts from the end, both ends included,
so the last row is left out:
editor.commands.insertDiagramFromTable({
header: 'none',
range: { rows: { to: -2 } },
columns: { step: 0, next: 1 },
})| Option | Type | Default | Description |
|---|---|---|---|
columns | TableDiagramColumns | Guessed from the header | { step, next, lane?, label?, shape? }, header texts or positions |
header | TableHeader | 'auto' | 'none' reads every row as a step. 'auto' and 'first-row' read a header row |
range | { rows } | Every row | Some rows, as for insertLinkedChart |
table | number | The table at the selection | The table's position |
title | string | null | null | The diagram's title |
below | boolean | true | false inserts above the table |
Returns false when the selection is outside a table, or a named column is not in the table.
Without columns, it also returns false for a header of fewer than two non-empty cells and for
header: 'none'.
linkDiagramToTable
Draws an existing diagram from a table as a Mermaid flowchart, replacing its source, and makes it
follow the table at tablePos, such as a pos from editor.storage.diagrams.listTables():
editor.commands.linkDiagramToTable({ table: tablePos, columns: { step: 'Step', next: 'Next' } })table and columns are required, header and range work as for insertDiagramFromTable, and
pos is the diagram's position, by default the selected diagram.
Returns false without a diagram at pos or in the selection, when table holds no table it can
follow, and for a column the table does not have.
detachDiagramFromTable
Stops a diagram from following its table. The source stays and can be edited.
editor.commands.detachDiagramFromTable({ removeTable: true })| Option | Type | Default | Description |
|---|---|---|---|
pos | number | The selected diagram | The diagram's position |
removeTable | boolean | false | Also removes the table, unless another chart or diagram follows it |
Returns false for a diagram that follows no table.
renameDiagramLane
Renames a lane in every row of the table, also outside range, and the diagram follows in the
same undo step.
editor.commands.renameDiagramLane({ lane: 'Warehouse', name: 'Warehouse North' })| Option | Type | Default | Description |
|---|---|---|---|
lane | string | Required | The lane's name, trimmed and case-sensitive |
name | string | Required | The new name, trimmed |
pos | number | The selected diagram | The diagram's position |
Returns false for a diagram that follows no table or has no lane column, a lane no cell
names, and an empty name.
Without an editor
Functions from @tiptap-pro/extension-diagrams/core do the commands' work on a server. rows
is an array of rows of cell texts, header row first unless header is 'none', and read takes
header and range, or {} for the defaults:
import { tableToMermaid } from '@tiptap-pro/extension-diagrams/core'
const rows = [
['Step', 'Next'],
['Order in', 'Pack'],
['Pack', ''],
]
const source = tableToMermaid(rows, { step: 'Step', next: 'Next' })
// 'flowchart LR\n order_in["Order in"]\n pack["Pack"]\n order_in --> pack'| Function | Returns |
|---|---|
tableToMermaid(rows, columns, read?) | The flowchart source, or null when a named column or the header row is missing |
guessTableDiagramColumns(header) | The guessed columns, or null for fewer than two non-empty cells |
tableDiagramLanes(rows, columns, read?) | The lanes in order of appearance |
tableLaneCells(rows, columns, read, lane) | { row, column } of each cell naming lane, row counting the header row from 0 |
tableStepRenames(before, after, columns, read?) | null when no step was renamed, otherwise { renames, firstRow, nextColumn }. renames is a Map from each old name, lower-cased and trimmed, to the new one. firstRow is 1 below a header, otherwise 0 |
stepRenameEdits(text, renames) | The { from, to, text } replacements for one next cell |