Tables

Quick start

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

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

Following a table

To let charts and diagrams follow tables, turn on the option chart.linkTables. It gives each table a chartTableId attribute, so a chart can find its table again. Without it, insertLinkedChart, linkChartToTable, and setChartLayout with a table return false.

A chart that follows a table changes in the same undo step as your edit of the table, so one undo takes back both. The table can be anywhere in the document, and listTables() lists the tables a chart can follow. The chart's data comes from the table through the document-table Data Source.

How the table is read

insertLinkedChart, linkChartToTable and updateLinkedTable take header and range.

• 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 a 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. They 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:

convertTableToChart

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

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

Returns false without a table.

convertChartToTable

Replaces a chart with a plain table of its data.

editor.commands.convertChartToTable()

Returns false without a table in the schema.

insertLinkedChart

Inserts a chart that follows a table.

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 }] },
})

columns.label names the categories and columns.series are drawn. Without columns, the first column is the label and every other column is drawn. Positions also work for a table without a header, and count among the columns that range reads.

The chart's data is read-only while it is linked.

Returns false without a table, without chart.linkTables, or when a name is not in the header or a position is not in the table.

updateLinkedTable

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

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

• A key given as undefined goes back to the default.
• A key left out keeps its value.
• A chart's label and series stay on the same columns. They stay on the column itself while it is still read, otherwise on the column at the same position. So they survive a new header.
• listCharts() reports the current values as tableRead, and listDiagrams() as part of link.

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

setChartLayout

Decides whether a chart's table is in the document, and whether the chart shows.

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

What the command does depends on the chart's current layout:

• Where the chart and its table stand is not part of the layout. Move either node to move it.
• The title, the Renderer and the rest of the spec are kept, also while the chart is hidden. Any other layout shows the chart again as it was.
• The change is one undo step.
• A hidden chart is left out of exportAll and exportDocx. In HTML, its <figure> has the hidden attribute.
• 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 true when the chart has the layout afterwards, also when it had it already. Returns false in these cases:

• For 'with-table' and 'table', without table nodes in the schema or without the option chart.linkTables.
• For 'with-table' and 'table', on a chart that follows no table and is linked to another read-only source, such as a read-only CSV URL.
• For 'table', when another hidden chart already stands directly below the table, or when the chart cannot stand there.

linkChartToTable

Makes a chart follow a table that is already in the document, wherever that table stands.

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

The table gets an id if it has none. The chart takes the table's data at once.

The chart ends with layout 'with-table', as with setChartLayout({ layout: 'with-table' }). The difference is that linkChartToTable replaces the chart's data with an existing table's data, while setChartLayout creates a new table from the chart's data, directly above the chart.

Returns false without chart.linkTables, for a position that holds no table, and for a table that is a Quick Input shown as a table.