Data Sources

A chart can take its data from a Data Source, such as a CSV file, a table in the document, or a service your own provider reads.
New tab

The chart stores the address and a snapshot, a copy of the data it last read. It draws from the snapshot, so it draws offline, in an export and for people who cannot reach the source.

Quick start

In the editor from A first chart, this inserts an empty chart, which is then selected, and links it to a CSV file. It needs no other option:

editor.commands.insertChart({ type: 'line' })
editor.commands.linkChartSource({
  provider: 'url-csv',
  address: { url: 'https://example.com/sales.csv' },
  readOnly: true,
})

Stored in the document

A chart stores source, which is { provider, address, mode, readOnly }, and syncedAt, the ISO time the snapshot was last written, by a read or by data passed to a command, or null. editor.storage.diagrams.listCharts() reports both.

Linked or detached

mode, 'linked' or 'detached', says whether the chart updates from its source.

Linked. linkChartSource, syncChartData, requestSync, relinkChartSource and a provider's subscribe (Writing a provider) fetch a new snapshot from the source. In between, the chart shows the last one.

Detached. detachChartSource stops the updates and keeps the snapshot and the address, so the data can be edited. relinkChartSource starts them again and replaces the data with the source's.

Read-only

readOnly decides whether the data of a linked chart can be edited in the editor:

  • readOnly: true: editing commands such as updateChartData return false, and rows pasted onto the chart change nothing. Only a new snapshot, such as syncChartData({ data }), changes the data.
  • readOnly: false, the default of linkChartSource: the data can be edited while linked, but the next synchronization replaces those edits with the source's data.

To keep hand edits, detach the chart. A detached chart can be edited whatever readOnly says, and the flag acts again after relinkChartSource. The Chart Spec stays editable.

Showing only some columns

A synchronization replaces all columns. To show only some, set encoding, which survives every synchronization. An id the new data does not have is ignored, so the chart still draws after the source renames a column:

editor.commands.updateChartSpec({ spec: { encoding: { series: ['revenue'] } } })

When a chart synchronizes

A synchronization reads the source and writes a new snapshot. It is left out of the undo history, and it sets syncedAt even when the data is the same.

When a source cannot be read, the chart keeps its snapshot, and the onSourceError option of Diagrams gets the error and { provider, address }.

Every client that synchronizes needs the provider registered. Without it, a client shows the snapshot and its read fails with No Data Source provider "…" is registered.

requestSync synchronizes every chart that reads a source, and resolves to false when the read failed or no chart reads it. The extension has no schedule, but your app can call it with setInterval, within the limits of the service:

await editor.storage.diagrams.requestSync({ provider: 'url-csv', address: { url } })

Built-in providers

These providers need no setup:

ProviderAddressReads
url-csv{ url } or a URL stringCSV, also with semicolons or tabs, through fetch
url-json{ url } or a URL stringChart Data, or an array of arrays or of objects, also under data. The first text key names the rows
document-table{ tableId }A table in the same document

Reading a URL

A URL must be absolute and use http: or https:. If you set the optional allowSourceUrl check, a URL must also pass it. The server must allow your app's web page to read the file, which is called CORS. A published Google Sheet does.

In these cases the read fails, and onSourceError gets the message:

CaseMessage
Not such a URL<url> is not an address this editor reads data from.
An error status<url> answered <status>.
A blocked requestCould not load <url>: the server is unreachable or does not allow this page to read it (CORS).
An HTML page, not a file<url> answered with a web page, not data. Check the address.

Reading a table

A chart that follows a table in the document uses document-table, see Tables.

Writing a provider

In the demo, a provider reads a weather API and fills a chart with the next seven days:

New tab

A provider is an object with an id and a read function. Pass it in the sources option, such as Diagrams.configure({ sources: [salesApi] }), or add it with editor.storage.diagrams.registerSource(provider), which returns a function that removes it. A provider with an id already registered replaces the other.

import type { ChartSourceProvider } from '@tiptap-pro/extension-diagrams'

const salesApi: ChartSourceProvider = {
  id: 'sales-api',
  read: async (address, { fetch }) => {
    const { region } = address as { region: string }
    const response = await fetch(`/api/sales?region=${encodeURIComponent(region)}`)
    const rows: { month: string; total: number }[] = await response.json()
    return {
      columns: [
        { id: 'month', label: 'Month', role: 'label' },
        { id: 'total', label: 'Total', role: 'series' },
      ],
      rows: rows.map(row => [row.month, row.total]),
    }
  },
  describe: address => `Sales, ${(address as { region: string }).region}`,
}
MemberRequiredDescription
idYesWhat a chart stores as provider
read(address, context)YesReturns Chart Data, or a Promise of it. Throw to report an error
subscribe(address, onChange, context)NoFor a pushing source: call onChange(data) on each change, return a stop function
describe(address)NoA label for a user interface

context has fetch, decimalSeparator, editor, and allowUrl when your app sets allowSourceUrl. To report an error, throw a ChartSourceError from @tiptap-pro/extension-diagrams/core with a message a person can read. Each change that subscribe reports goes into every chart linked to that address.

Everyone who opens the document sees the address, so do not put credentials in it. A provider takes a key or token from your app when you create it. Google Sheets, Excel and Airtable has a provider for each service.

Commands

linkChartSource

Links a chart to a Data Source.

editor.commands.linkChartSource({ provider: 'url-csv', address: { url } })
OptionTypeDefaultDescription
providerstringRequiredThe id of a registered provider, such as 'url-csv'
addressunknownRequiredWhere the provider reads, in its form
readOnlybooleanfalsetrue blocks editing while linked, see Read-only
dataChartDataRead from the sourceThe first snapshot
posnumberThe selected chartThe chart's position

Returns false without a chart, or for a provider that is not registered.

syncChartData

Writes a new snapshot into one chart, or into every chart linked to a source.

editor.commands.syncChartData({ source: { provider: 'url-csv', address: { url } } })
OptionTypeDefaultDescription
dataChartDataRead from the sourceThe new snapshot, written even into a read-only chart
source{ provider, address }NoneWrites into every linked chart that reads that source
posnumberThe selected chartThe chart's position, without source

Without data, the command returns true once the read is requested, not when it succeeds. Returns false without a matching chart, or without data for a chart that has no source.

detachChartSource

Stops following the source, and keeps the snapshot and the address.

editor.commands.detachChartSource()
OptionTypeDefaultDescription
posnumberThe selected chartThe chart's position

Returns false for a chart without a source.

relinkChartSource

Follows the source again and reads it.

editor.commands.relinkChartSource()
OptionTypeDefaultDescription
posnumberThe selected chartThe chart's position

Returns false for a chart without a source.