Integration, or "embed mode" is used for cases where the storage of the diagram is taken care of by a host application, and diagrams.net is used for diagram editing. In this case, diagrams.net is used inside an iframe or window with special URL parameters, and is remote controlled using the HTML5 Messaging API. Use embed.diagrams.net only for embed mode.
The basic flow is as follows:
- Load embed.diagrams.net with special URL parameters inside an iframe
- Send the diagram data to the iframe for editing
- Receive and save diagram data from the iframe
- Remove iframe
Depending on the requirements, a PNG or SVG image or the XML for the diagram can be used as the storage format. Consider the following when picking the storage format:
- Images (PNG and SVG) should be used for fast loading with no initial delay. Embedding the diagram data for editing in PNG and SVG images can be used to avoid saving the image and diagram separately, but will result in bigger image files. When using a viewer or editor, images should be used to show a placeholder or preview.
- SVG images should be used if hyperlinks and vector images are required. (The SVG output of diagrams.net uses foreign objects, which are not supported in IE11 and earlier. To fully support IE11 in SVG output, certain application features must be disabled, which is not recommended.)
- XML should be used if no image version of the diagram is required or to store the XML separately from the image. A viewer or editor is required to handle these files.
- PNG images should be used if a bitmap image is required, to support IE11 and earlier or for special fonts.
The storage can be any persistence mechanism. The image or XML file can be stored and used in the output of the host application, such as an image tag, SVG DOM or HTML viewer. Authentication, file descriptors, revisions etc must be handled by the host application. All communication between the host application and diagrams.net happens on the client-side. The protocol specification is here.
The basic flow of the protocol is as follows:
- Wait for init event
- Send load action
- Wait for save/exit event
In some cases, additional steps may be required to check for a draft state or to export the diagram as an image. Special messages are available in the protocol to show draft states or a template dialog.
Fonts, colors, default styles, libraries, CSS and more can be configured to match the environment and style of the host application by using the configure=1 URL parameter. See localstorage-svg.html.
The following examples are available:
- JavaScript API for editing embedded SVG and PNG images in a HTML page (see example1, example2)
- Using Local Storage Saving and loading a diagrams.net diagram to/from HTML5 local storage (use the part of the hash-tag to change the local storage key)
- Using Local Storage (SVG) Saving and loading a diagrams.net diagram to/from HTML5 local storage as SVG (use the part of the hash-tag to change the local storage key). This example uses an SVG element instead of an image to support hyperlinks. Keep in mind that diagrams.net uses foreignObjects for text labels in static SVG output. ForeignObjects are not supported in IE11 and earlier. (For draft states, a special dialog is now available.)
- Using Local File Saving and loading to/from a self-modifying local file
- Using embed mode with WebDav
- Using embed mode with GitHub