Tables | Tiptap Diagrams Docs

Quick start

With chart.linkTables on, place the selection in a table and call:

editor.commands.insertLinkedChart({ type: 'bar' })

Every edit of the table updates the chart in the same Transaction.

How the table is read

insertLinkedChart, linkChartToTable and updateLinkedTable take header and range.

Option	Type	Description
`header`	`'auto' \| 'first-row' \| 'none'`	Where the column names are. Default `'auto'`
`range.rows`	`{ from?, to? }` or an array of them	The data rows read, counted from 0 below the header
`range.columns`	`(number \| { from?, to? })[]`	The columns read, counted from 0, such as `[0, { from: 2 }]`. The first column read names the categories

`header`	The column names
`'auto'`	The first row, when it is made of header cells or holds no number outside the first column
`'first-row'`	The first row, whatever it holds
`'none'`	Every row is data; the columns get default names

Both ends of a range are included.
A negative number counts from the end: -1 is the last row, so { to: -2 } leaves out a total row.
Empty rows are not counted.
Several ranges are read in the order given.
A row or column named twice is read once.
Without range, a selection of cells in the table is the range: the rows and columns it covers, with the first column of the table as the label.
header and range are stored in the chart's Data Source address and apply to every later edit of the table.

Commands

Turn a table into a chart and back, or a chart into an image that keeps its data:

New tab

convertTableToChart

Replaces the table at the selection with a chart of its data.

editor.commands.convertTableToChart({ type: 'bar' })

Option	Type	Description
`type`	`ChartType`	The chart type. Defaults to `chart.defaultType`
`pos`	`number`	A position inside the table. Defaults to the selection

Returns false without a table.

convertChartToTable

Replaces a chart with a plain table of its data.

editor.commands.convertChartToTable()

Option	Type	Description
`pos`	`number`	The chart's position. Defaults to the selected chart

Returns false without a table in the Schema.

insertLinkedChart

Inserts a chart that follows a table: every edit of the table updates the chart in the same Transaction.

editor.commands.insertLinkedChart({
  table: editor.storage.diagrams.listTables()[0].pos,
  type: 'bar',
  columns: { label: 'Month', series: ['Retail'] },
})

// A table without a header, without its last row
editor.commands.insertLinkedChart({
  table,
  header: 'none',
  range: { rows: { to: -2 } },
  columns: { label: 0, series: [2] },
})

// The first and the last two rows, and only the columns 0, 3 and 4
editor.commands.insertLinkedChart({
  table,
  range: { rows: [{ to: 0 }, { from: -2 }], columns: [0, { from: 3, to: 4 }] },
})

Option	Type	Description
`type`	`ChartType`	The chart type. Defaults to `chart.defaultType`
`table`	`number`	The table's position, from `listTables()`. Defaults to the table at the selection
`columns`	`{ label?: string \| number, series?: (string \| number)[] }`	Columns by the text of their header cell or by their position from 0
`header`	`'auto' \| 'first-row' \| 'none'`	See How the table is read
`range`	`{ rows?, columns? }`	See How the table is read
`title`	`string`	The chart's title
`below`	`boolean`	`false` places the chart above the table. Default `true`

columns.label is the column that names the categories.
columns.series are the columns drawn.
Positions also work for a table without a header.
Positions count among the columns range reads.
Without columns, the first column is the label and every other column is drawn.
The chart's data is read-only while linked.
Needs the option chart.linkTables.

Returns false when a name is not in the header or a position not in the table.

updateLinkedTable

Changes how a chart or a diagram reads the table it follows, and reads it again.

editor.commands.updateLinkedTable({ header: 'none' })
editor.commands.updateLinkedTable({ header: undefined, range: { rows: { from: 1 } } })

Option	Type	Description
`header`	`'auto' \| 'first-row' \| 'none'`	See How the table is read
`range`	`{ rows?, columns? }`	See How the table is read
`pos`	`number`	The chart's or diagram's position. Defaults to the selected one

A key given as undefined returns to the default.
A key left out keeps its value.
A chart's label and series stay on the same columns: on the column itself while it is still read, otherwise on the column at the same position, so they survive a new header.
The current values are reported by listCharts() as tableRead, and by listDiagrams() as part of link.

Returns false for a chart or diagram that follows no table, whose table is gone, or, for a diagram, when a column it names is no longer there.

setChartLayout

Decides whether a chart's table is in the document with it.

editor.commands.setChartLayout({ layout: 'with-table' })

Option	Type	Description
`layout`	`'chart' \| 'with-table' \| 'table'`	What the document holds, see below
`pos`	`number`	The chart's position. Defaults to the selected chart

`layout`	The document holds
`'chart'`	The chart alone, with its own data
`'with-table'`	The chart and a table it follows, wherever each stands
`'table'`	The table alone; the chart stays directly below it, hidden, and keeps following it

Where the chart and its table stand is not part of the layout. Move either Node to move it.
'with-table' on a chart with its own data inserts a table of that data directly above the chart, which the chart follows from then on, as with insertLinkedChart.
'chart' keeps the data the table last gave and follows nothing. The table is removed, unless another chart or diagram still follows it.
'table' moves the chart directly below its table if it stands elsewhere.
Title, Renderer and the rest of the spec are kept, also while the chart is hidden, so any other layout shows it again as it was.
The change is one undo step.
A hidden chart is left out of exportAll and exportDocx, and in HTML its <figure> carries hidden.
Deleting or moving its table shows the chart again.
To keep only a table and no chart, use convertChartToTable.
listCharts() reports the current layout as layout.

Returns false for 'with-table' and 'table' on a chart whose data comes from another linked, read-only source, without the option chart.linkTables, and for 'table' when another hidden chart already stands below that table.

linkChartToTable

Makes a chart follow a table anywhere in the document, not only beside it.

const [table] = editor.storage.diagrams.listTables()
if (table) editor.commands.linkChartToTable({ table: table.pos })

Option	Type	Description
`table`	`number`	The table's position, as `listTables()` reports it
`pos`	`number`	The chart's position. Defaults to the selected chart
`readOnly`	`boolean`	`false` keeps the chart's data editable while linked. Default `true`
`header`	`'auto' \| 'first-row' \| 'none'`	As for `insertLinkedChart`
`range`	`{ rows?, columns? }`	As for `insertLinkedChart`

The table gets an id if it has none.
The chart takes its data at once and follows every edit in the same Transaction.
Such a chart reports layout: 'chart', since the table is not its neighbor.
Needs the option chart.linkTables.

Returns false for a position that holds no table and for a table that is an open input view.

PreviouslyPasting

Next upData Sources