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 the data can be sent as XML or compressed XML. It will send back XML or an empty string if apply or cancel are pressed, respectively. The following URL parameters are available in embed mode:

  • spin=1: Shows a Loading... spinner while waiting for the diagram data in embed mode.
  • modified=0: Disables update of the modified state in embed mode after save is pressed and enables update of the status message after changes. If 0 is used, the status bar is cleared after changes. Else the value of this is used as the resource key. Instead of using this URL parameter, this can also be specified in the load message below.
  • keepmodified=1: If modified (above) specifies a resource key, this is used to keep the modified state after save is pressed.
  • libraries=1: If libraries should be enabled in embed mode. Default is disabled.
  • saveAndExit: Displays an additional save and exit button (see below). Instead of using this URL parameter, this can also be specified in the load message below.
  • ready=message: The message to send in embed or client mode. Default is 'ready'. If JSON protocol is used then this is ignored.

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

Description of the JSON protocol

When the client is ready, it sends {event: 'init'} and expects {action: 'load', xml: '...'}. An optional autosave: 1 can be specified in this message to enable autosave. An optional modified flag can be specified with the same semantic as the modified URL parameter which is defined above. The modified URL parameter has precendence over this. An optional saveAndExit flag can be specified with the same semantic as the saveAndExit URL parameter which is defined above. The saveAndExit URL parameter has precendence over this. An optional title string can be specified to show a title in the menubar (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 graph. The XML in this message can be any supported XML represenation of the graph including SVG and PNG with embedded XML. (For passing PNG+XML, the old parameter name was xmlpng, which can still be used.)

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

If save is clicked, the same message as load is sent but with an additional event: 'save' and xml: '...' containing the XML of the diagram. If save and exit is clicked the message has an additional exit: true.

If exit is clicked, an {event: 'exit', modified: boolean} is sent.

{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, titleKey, messageKey and buttonKey can be used instead.

{action: 'prompt', title: '...', okKey: '...', defaultValue: '...'} can be sent at any time to display a prompt in the editor window. To translate the title, titleKey can be used instead. If the user clicks the ok button, 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 a dialog to the user for picking a template. This is normally sent instead of a load message to create an initial diagram. If Create is clicked, the diagram is created, else if Cancel is clicked, an exit message is sent. An optional callback: true parameter can be specified to pass the current template and filename back to the caller for validation. The message for the callback is {event: 'template', xml: '...', blank: '...', name: ...} where blank is true if a blank diagram diagram was selected.

{action: 'draft', xml: '...', name: '...', editKey: '...', discardKey: '...', ignore: bool} can be sent to show a draft dialog. If edit or discard is clicked, an {event: 'draft', error/result: '...', message: ...} with the incoming message and a 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 returned 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 message, messageKey can be used 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 message or hide the current spinner if show is set to false. Instead of message, messageKey can be used to 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 are html (old embed format), html2 (new embed format), svg (default), xmlsvg (SVG with embeddded XML), png and xmlpng (PNG with embedded XML). For png and xmlpng, an additional spin (or spinKey) parameter can be used to enable a spinner and specify a message (or message key) while the image is being generated. An optional xml parameter can be used to specify the XML of the diagram to be exported for all supported formats. An optional embedImages: false can be specified for the svg and xmlsvg formats to disable embedded images in the SVG output.

The data parameter in the export event contains a valid data URI for the given export format. Currently, a base64 encoding is used but this may change in the future.

If any unknown message is received, the system responds with {error: 'unknownMessage'}.

Examples