Export

Files

import { downloadBlob } from '@tiptap-pro/extension-diagrams/export'

const { blob, svg, width, height, alt } = await editor.storage.diagrams.export(
  { pos },
  { format: 'png', scale: 2, background: '#ffffff' },
)
downloadBlob(blob, 'chart.png')

What to export

The first argument, target, is one of:

• A diagram is drawn by its Diagram Renderer.
• renderer and size do not apply to a diagram.
• A diagram's theme comes from the --tt-flow-diagram-* properties.

Options

What comes back

• The SVG carries concrete colors, not var(…), so it looks the same outside the page.
• A Renderer that draws pixels, such as one on a canvas, is exported too. Its SVG holds the picture rather than shapes, so it does not scale without loss. See Your own Renderer.
• Image formats need a browser.
• The SVG of ECharts and d3 can be made on a server.

@tiptap-pro/extension-diagrams/export also has svgToBlob, svgToImage, toDataUrl, readSvgSize, inlineSvgStyles and rasterToSvg.

Word

const { blob, notes } = await editor.storage.diagrams.exportDocx({
  targets: [{ pos }],
  title: 'Report',
})
downloadBlob(blob, 'charts.docx')
for (const note of notes) console.info(note.title ?? 'All charts', note.message)

What the file holds

• One native Word chart per target, in order, each with its data in an embedded workbook, so Word can restyle the chart and open "Edit data".
• A diagram becomes a PNG picture, scaled to the page width, with its title as caption.
• Without targets, every chart that has data and every diagram that has source, in document order.
• With none of them, the promise rejects.
• A chart with caption is followed by its description in Word's Caption style.
• Every chart and picture carries its title and description as alt text.
• A matrix becomes a Word table with shaded cells.
• Series colors and the font come from the page; see Styling.
• Only the charts and diagrams are in the file, not the rest of the document.

Charts as pictures

• A chart Word's own would show differently is a scatter chart with numbers on its x axis, which Word would space evenly.
• A chart no Renderer can draw as a picture stays a Word chart, with a note.

Notes

notes says what Word shows differently from the editor, one sentence each. It is known from the data and the spec before the file is opened. A note has pos, title and message. Notes cover:

• a font Word lacks (pos: null),
• a pie with more than one series,
• the range of the x axis,
• a color that is not a hex value,
• options only one Renderer understands,
• that a linked chart holds a snapshot in Word,
• a chart written as a picture, and why when its type has a Word form,
• a diagram, which is a picture in Word, or was left out when it could not be drawn.

Without exporting

These come from @tiptap-pro/extension-diagrams/core:

A whole document

A converter that does not know the chart and flowDiagram Nodes leaves them out. toPortableContent from @tiptap-pro/extension-diagrams/core returns a copy of the document in which they are made of Nodes every converter knows. Export that copy instead, here with @tiptap-pro/extension-export-docx, which sends it to Tiptap's Convert service:

import { Editor } from '@tiptap/core'
import { ConvertKit } from '@tiptap-pro/extension-convert-kit'
import { toPortableContent } from '@tiptap-pro/extension-diagrams/core'
import { ExportDocx } from '@tiptap-pro/extension-export-docx'

const file = await new Promise((resolve, reject) => {
  const exporter = new Editor({
    element: null,
    content: toPortableContent(editor.getJSON()),
    extensions: [
      ConvertKit,
      ExportDocx.configure({ token: 'CONVERT_TOKEN', onCompleteExport: resolve, onError: reject }),
    ],
  })
  exporter.commands.exportDocx()
})

• toPortableContent needs no browser. It runs on a server too.
• CONVERT_TOKEN is your Convert API token. See the export-docx docs for its options.

What the copy holds

• A chart has a picture only when your integration uploads one (uploadImage, which sets previewUrl). Without it, the copy holds its data as a table.
• A matrix cell's color is its background attribute, and its text color a textStyle mark. A converter that reads them keeps the colors.

Options

'paragraphs' keeps a diagram's source in a converter that leaves out code blocks. Choose 'codeBlock' for a converter that writes them, such as one to Markdown or HTML.

Native Word charts

With charts: 'native', a chart of a type Word draws itself (bar, line, area, scatter, pie and their kin) becomes a marker line instead of a picture and a table. After any converter wrote the Word file, addNativeCharts replaces each marker with a native Word chart, which the reader can restyle and whose data opens in Excel ("Edit data").

import { Editor } from '@tiptap/core'
import { ConvertKit } from '@tiptap-pro/extension-convert-kit'
import { addNativeCharts, toPortableContent } from '@tiptap-pro/extension-diagrams/core'
import { ExportDocx } from '@tiptap-pro/extension-export-docx'

const doc = editor.getJSON()
const exported = await new Promise((resolve, reject) => {
  const exporter = new Editor({
    element: null,
    content: toPortableContent(doc, { charts: 'native' }),
    extensions: [
      ConvertKit,
      ExportDocx.configure({
        token: 'CONVERT_TOKEN',
        exportType: 'buffer',
        onCompleteExport: resolve,
        onError: reject,
      }),
    ],
  })
  exporter.commands.exportDocx()
})
const docx = addNativeCharts({ docx: exported, doc })

• Other types are written as with 'both'.
• Pass addNativeCharts the same document you passed toPortableContent; it finds the charts in the same order.
• theme and fallbackFont are taken by addNativeCharts as by exportDocx of the storage.
• A marker a converter split or changed is left as text.

Commands

convertChartToImage

Replaces a chart with an image of it, through the image Node named by the option imageNodeName.

editor.commands.convertChartToImage({ format: 'svg', keepData: true })

• The image is uploaded with uploadImage, or embedded as a data URL without it.
• The chart is replaced once the image is ready, unless it changed in the meantime.
• The image is exported at twice its size, so it stays sharp on high-density screens.
• When the image Node has a width attribute, as @tiptap/extension-image does, the command sets it to the chart's width, and the image shows at that size.

Give images max-width: 100% so they shrink on a narrow screen:

.tiptap img {
  max-width: 100%;
  height: auto;
}

convertImageToChart

Turns an image made with keepData back into the chart.

editor.commands.convertImageToChart()

redrawChartImage

Draws an image made with keepData again from the chart it keeps, with the current styles, Renderers and color scheme.

editor.commands.redrawChartImage({ pos })

• The image keeps its other attributes and the chart it keeps.
• Only its file, text and width change, once the new file is ready, unless the image changed in the meantime.

Returns false for an image that keeps no chart, and when no Renderer draws its type.