If the embed=1 URL parameter is used, the client runs in embed mode and the page will send a "ready" message to the opener or parent when the page is loaded. After receiving the ready message, diagram data can be sent as XML or compressed XML. It will return XML or an empty string if Apply or Cancel are selected, respectively. The following URL parameters are available in embed mode:

  • spin=1: Shows a Loading... spinner while waiting for the diagram data to load in embed mode.
  • modified=0: Disables update of the modified state in embed mode after Save is selected and enables the update of the status message after changes are made. If 0 is used, the status bar is cleared after the changes. Otherwise, the value of this is used as the resource key. Instead of using this URL parameter, you can specify this setting in the load message.
  • keepmodified=1: If modified specifies a resource key, this is used to keep the modified state after Save is selected.
  • libraries=1: Specifies whether libraries should be enabled in embed mode. The default is disabled (0).
  • noSaveBtn=1: Displays a Save and Exit button instead of a Save button. Instead of using this URL parameter, you can specify this setting in the load message. If this is used, then saveAndExit is ignored.
  • saveAndExit=1: Displays a Save and Exit button. Instead of using this URL parameter, you can specify this setting in the load message. (If noSaveBtn=1 is used, this can be disabled with saveAndExit=0.)
  • noExitBtn=1: Displays no Exit button. Instead of using this URL parameter, you can specify this setting in the load message.
    Note: To hide all buttons in embed mode, use saveAndExit=0&noSaveBtn=1&noExitBtn=1.
  • ready=message: Specifies the message to send in embed or client mode. Default is 'ready'. If the JSON protocol is used then this is ignored.

  • returnbounds=1: Returns a JSON structure with the diagram bounds in embed and client mode. This message is dispatched immediately after receiving the diagram XML.
  • proto=json: Uses JSON for message passing in embed and client mode.
  • configure=1: Sends the configure event and waits for the configure action.


Configuration

If the configure=1 URL parameter is used, the client sends {event: 'configure'} and waits for {action: 'configure', config: obj} before creating the main application and sending the init event. The obj is specified in the configuration, e.g. config: {defaultFonts: ["Humor Sans"]}.



Description of the JSON protocol

When the client is ready, it sends {event: 'init'} and expects {action: 'load', xml: '...'}. Specify an optional autosave: 1 in this message to enable autosave.

You can set the optional modified flag with the same semantic as the modified URL parameter described above. The optional saveAndExit flag can be specified with the same semantic as the saveAndExit URL parameter which is defined above. The URL parameters have precedence over these flags.

Specify the optional title string to show a title in the menu bar (on the right).

If autosave is enabled the editor will send the current XML in an {event: 'autosave'...}.

The XML in the load message is displayed and an {event: 'load'...} is returned with some data about the size of the diagram and the input XML. The input XML in the load action message can be any supported XML representation of the diagram including SVG and PNG files with embedded XML. (The xmlpng parameter is still supported.)

Note: For XML, all supported file formats can be used, including PNG+XML, the data part of an SVG data URI with UTF8 encoding, or the complete SVG or PNG data URI with base64 encoding. For all .vsd* files, a data URI with a 

data:application/vnd.visio;base64 prefix must be used. Lucidchart and Gliffy files are represented as a JSON string.

When you select Save, the same message as the load event is sent, but with an additional event: 'save' and xml: '...' containing the XML of the diagram. When you select Save and Exit, the message includes an additional exit: true. If you select Exit, an {event: 'exit', modified: boolean} is sent. For links that are clicked in the UI, the app tries to open the link with the given target (default is _blank) and sends a {event: 'openLink', href: String, target: String} event.

  • {action: 'merge', xml: '...'} can be sent at any time to merge the contents of the given XML into the current file, an {event: 'merge', error: '...', message: ...} with the incoming message and an optional error is returned. If the merge was successful then the error is null.
  • {action: 'dialog', title: '...', message: '...', button: '...', modified: bool} can be sent at any time to display a dialog in the editor window. To translate the dialog, use titleKey, messageKey and buttonKey instead.
  • {action: 'prompt', title: '...', okKey: '...', defaultValue: '...'} can be sent at any time to display a prompt in the editor window. To translate the title, use titleKey instead. When OK is selected, an {event: 'prompt', value: '...', message: ...} with the incoming message and the value entered in the dialog is returned.
  • {action: 'template'} can be sent at any time to show the template dialog. This is normally sent instead of a load message to create an initial diagram. When Create is selected, the diagram is created from the selected template. If Cancel is selected, an exit message is sent. Specify an optional callback: true parameter to pass the current template and filename back to the caller for validation. The message for the callback is {event: 'template', xml: '...', blank: '...', name: ..., message: ...} where blank is true if a blank diagram was selected in the template dialog and message is the incoming message.
  • {action: 'draft', xml: '...', name: '...', editKey: '...', discardKey: '...', ignore: bool} can be sent to show a draft dialog. If Edit or Discard is selected, an {event: 'draft', error/result: '...', message: ...} with the incoming message and the result of 'Edit' or 'Discard' is returned. If there was an error when displaying the dialog, the error is returned instead of the result in the message. If ignore is true, an ignore option is used which returns result: 'ignore'.
  • {action: 'status', message: '...', modified: bool} can be sent at any time to display a message in the status bar. The optional modified flag is used to update the modified state. Instead of a message, you can use messageKey to specify a resource key for the message.
  • {action: 'spinner', message: '...', show: bool, enabled: bool} can be sent at any time to display a spinner with a message or hide the current spinner if show is set to false. Instead of a message, you can use messageKeyto specify a resource key for the message.
  • {action: 'export', format: '...'} can be sent at any time to return {event: 'export', format: '...', message: ..., data: '...', xml: '...'} with the incoming message, data and XML used for the given format. Supported formats include html (old embed format), html2 (new embed format), svg (default), xmlsvg (SVG with embeddded XML), png and xmlpng (PNG with embedded XML). The data parameter in the exportevent contains a valid data URI for the given export format. Currently, a base64 encoding is used but this may change in the future.
    • For png and xmlpng, use an additional spin (or spinKey) parameter to enable a spinner and specify a message (or messageKey) while the image is being generated. 
    • Use the optional xml parameter to specify the XML of the diagram to be exported for all supported formats. 
    • Use the optional embedImages: false for the svg and xmlsvg formats to disable embedded images in the SVG output.


If any unknown message is received, the system responds with {error: 'unknownMessage', data: ...} where data is the string representation of the incoming message.


Examples