Collaboration
Diagrams.Where to register Diagrams
Register Diagrams everywhere the shared document is opened: in each editor, in a read-only
viewer and in an agent.
A collaboration server has no editor. Where it turns the shared document into Tiptap JSON or back,
it uses a schema built with Diagrams, as in A client that shows nothing.
A client you missed deletes every chart and diagram from the shared document, unless it sets
enableContentCheck: true. See A client without Diagrams.
Two people changing one chart
A chart stores its data, its Chart Spec (its settings) and its Renderer as separate attributes, and the shared document merges each attribute on its own:
- Changes to different attributes at the same time are both kept, such as a title and a cell.
- Changes to the data at the same time keep only one of them, the same on every client, even in different cells, because the data is one attribute.
- Undo takes back only your own change, also after somebody else changed the chart.
A diagram's source is one attribute too, so the same applies.
A client without Diagrams
A client whose schema, the nodes its editor knows, has no chart or flowDiagram node cannot
build them. Nor can one that sets chart: false or flowDiagram: false. What happens then depends
on the editor option
enableContentCheck:
enableContentCheck | The shared document | That client |
|---|---|---|
false (default) | Loses the charts or diagrams that client cannot build. The deletion reaches every other client | Deletes them while it loads the document |
true | Stays as it is. Everybody else keeps their charts and diagrams | Shows the rest of the document, cannot be edited, sends nothing, and emits contentError |
enableContentCheck: true needs @tiptap/extension-collaboration 3.33.0 and @tiptap/y-tiptap
3.2.0 or later. With older versions, the client deletes those charts or diagrams in both cases.
Only @tiptap/y-tiptap 3.0.10 and 3.0.11 behave differently: they make the editor read-only and may
show an empty or outdated document.
Set enableContentCheck: true on every client that might not register Diagrams, for example an
older version of your app. That client stays paused while the document contains charts or
diagrams it cannot build. Also set onContentError, because the default handler throws the error.
See Invalid schema handling.
A client that shows nothing
A client that draws nothing registers Diagrams with no Renderer. It needs no
DOM and no chart library, and it keeps every chart and diagram as it is. renderers: [] is enough,
because diagramRenderers, the Renderers for diagrams, is empty by
default:
import { getSchema } from '@tiptap/core'
import StarterKit from '@tiptap/starter-kit'
import { Diagrams } from '@tiptap-pro/extension-diagrams'
const extensions = [StarterKit, Diagrams.configure({ renderers: [] })]
const schema = getSchema(extensions)An editor without a Renderer shows each chart or diagram as not drawable here, or as what
unavailable returns. Its data stays untouched.
Turning away a client without Diagrams
If clients you do not control can connect, let the server refuse those that do not declare
Diagrams. With Hocuspocus, Tiptap's collaboration server, the client adds a parameter you
choose to its connection, and the server checks it before loading the document:
// client
const provider = new HocuspocusProvider({
url: 'wss://collaboration.example.com?schema=diagram-1',
name: 'document-id',
})
// server
const server = new Hocuspocus({
async onConnect({ requestParameters }) {
if (requestParameters.get('schema') !== 'diagram-1') {
throw new Error('This document needs the Diagrams extension.')
}
},
})Mixed versions
A newer version of @tiptap-pro/extension-diagrams may store a chart attribute that an older
client does not know. The older client keeps that attribute only until it changes the chart, and
then the attribute is lost. So update every client before you use a feature that a newer version
added.