Editor Events

The on method can be called to install event handlers for various ESD/SPD Web editor events. When an event handler is installed, the function you provide as the handler will be called when the specified event occurs. When your code installs an event handler, the return value from the on method call will be a Javascript object that contains a single member - a function called remove. To uninstall your custom event handler call the remove function.


Clipboard Events

Event Name Description Handler Signature
getClipboardContent 1 This handler is called by the editor to request the current clipboard content from an external clipboard provider. function(<Result Callback>)
Where <Result Callback> is a function your app will call to provide clipboard content to the editor. Your code should call the result callback passing it one argument: a Javascript object composed as described in the setClipboardContent event.
setClipboardContent 1 The editor calls this handler to provide updated clipboard content to the external clipboard provider. function(<Clipboard Content Object>)
Where <Clipboard Content Object> is a hash containing these values:
type: 'shapes', 'image'
value:
when type is 'shapes', an array of serialized SVG shapes.
when type is 'image', a string containing an image data URL.
width: when type is 'image', the width of the image in pixels.
height: when type is 'image', the height of the image in pixels.
copyDrawing 1 This handler is called by the editor when the user selects Copy to Clipboard in the toolbar's Manage tab, or Copy to Clipboard from the View Actions menu in the toolbar's View tab. function(<View Key>)
Where <View Key> indicates the context in which the user activated the Copy to Clipboard command. If the command resulted from the user selecting the Copy to Clipboard button on the Manage tab, the View Key argument will be undefined. If the command was triggered by the user selecting the Copy to Clipboard command on the Active View menu on the toolbar's View tab, the View Key argument will be key of the active view, or undefined if "Diagram" is the active view. If you use this handler, make sure to set the copyDrawingEnabled Startup option to true.
The ESD/SPD Web editor provides an internal clipboard manager that implements standard clipboard operations such as cut, copy and paste. These operations occur within the editor and do not access or modify the system clipboard. To provide your own clipboard management, use the getClipboardContent, setClipboardContent and copyDrawing events and the clipboardContentChanged command.

Example:
						// example assumes editor is an initialized ESDWeb object

						editor.on('getClipboardContent', myClipboard.getContent);
						editor.on('setClipboardContent', myClipboard.setContent);
						editor.on('copyDrawing', myClipboard.copyDrawing);

						...
						myClipboard.getContent = function(callback) {
							// called when user does a paste action
							var clipContent = {
								type: 'image',
								value: 'data:image/png;base64,...',
								width: 800,
								height: 600
							};
							callback(clipContent);
						};
						myClipboard.setContent = function(clipContent) {
							// This function is called when user does a cut or copy action. Add code
							// here to retain the values in the clipContent object.
						};
						myClipboard.copyDrawing = function(viewKey) {
							// This function is called when the user chooses Copy Drawing on the toolbar's Manage
							// tab or in the View Actions menu on the toolbar's View tab. Your implementation
							// should export the diagram as an image and place the resulting image into your
							// clipboard manager.
					        var options = {
					            includePrefix: true,
           						viewKey: viewKey
       						};
       						editor.exportImage(options, function(image) {
								// add code here to retain the image in your clipboard manager
       						}, function(e) {
								// log/report the export failure
							});
						};
					

Command Events

Event Name Description Handler Signature
commandBegin This handler is called when an editor command is initiated. function(<commandName>)
commandEnable The handler is called when the editor state has changed and one or more commands should be enabled or disabled. function(<commandName String OR array of commandName Strings>, <Command State Boolean>)
commandEnd This handler is called when an editor command is completed. function(<commandName>)
As described here, the ESD/SPD Web editor implements a wide variety of editor commands. Most editor commands are related to editor actions initiated via the editor's toolbar and right-click menus. The editor's built-in toolbar and menus will manage all command operations for you. If you choose to disable the toolbar and provide your own toolbar experience, you will use the executeCommand method to issue editor commands, and the commandBegin, commandEnd and commandEnable events to ensure the visual state of your command UI elements corresponds to the current editor state. The commandBegin handler is called when a command is initiated and the commandEnd handler is called when the command is completed. For example, when the user begins drawing a street shape, the commandBegin handler is called and the function's first argument is 'draw_streetStraight'. When the street draw operation is complete, the commandEnd handler is called and the function's first argument is again 'draw_streetStraight'. The commandEnable handler will be called anytime a command should be enabled or disabled. commandEnable gives your application the opportunity to disable command buttons when their corresponding editor commands are unavailable, and to enable command buttons when their corresponding editor commands are available.

Example:
						// example assumes editor is an initialized ESDWeb object

						editor.on('commandEnable', myToolbar.commandEnable);
						editor.on('commandBegin', myToolbar.commandBegin);
						editor.on('commandEnd', myToolbar.commandEnd);

						...
						myToolbar.commandEnable = function(commandInfo, enable) {
							// commandInfo will be a String or Array of Strings
							var cmdArray = Array.isArray(commandInfo) ? commandInfo : [commandInfo];

							cmdArray.forEach(function(commandName) {
								// enable/disable our zoom buttons as directed by the editor -
								// this assumes zoom buttons with IDs btnZoomIn, btnZoomOut, btnZoomToFit
								switch (cmd) {
								case 'zoomIn':		$('#btnZoomIn').disabled = !enable;		break;
								case 'zoomOut': 	$('#btnZoomOut').disabled = !enable;	break;
								case 'zoomToFit':	$('#btnZoomToFit').disabled = !enable;	break;

								// additional case statements here: for all other supported commands
								}
							});
						};

						myToolbar.commandBegin = function(commandName) {
							if ('draw_streetStraight' === commandName) {
								// while the street is being drawn show the street toolbar button pressed
								$("#streetTool").pressed=true;
							}
							// additional code here for all shapes whose draw operations are long running
						};

						myToolbar.commandEnd = function(commandName) {
							if ('draw_streetStraight' === commandName) {
								// draw operation is complete so unpress the street toolbar button
								$("#streetTool").pressed=false;
							}
							// additional code here for all shapes whose draw operations are long running
						};
					

Map/Geolocation Events

Event Name Description Handler Signature
locationSet This event is raised when the map location is set. function(<location>)
Where <location> is a location object as described in the setLocation command.
mapOpacityChange This event is raised when the map opacity has been set. function(<value>)
Where <value> is the map's opacity (floating point value between 0.0 and 1.0).
mapRemoved This event is raised when the map has been removed. function()
mapServiceChange This event is raised when the a map service is set as the active service. function(<label>, <index>)
Where <label> is the label of the map scheme, and <index> is the index of the newly active service into the list of map services. (see mapServicesUpdate below)
mapServicesUpdate This event is raised when map services are added or removed. function(<mapServices>)
Where <mapServices> is an array of objects of this form:
{
label: (string) map scheme label,
value: (string or number) value associated with this map scheme in order of creation or "None"
data:
{
selected: (boolean) indicates if this map service is currently active.
hasConfigDialog: (boolean) indicates if this map service has a configuration dialog.
}
}
Note: the last service will have label and value both set to "None", and data will be null.
mapServiceUnavailable This event is raised when a diagram is loaded which includes a map, but the map service does not correspond to any currently available map service. function(<serviceLabel>)
Where <serviceLabel> is the name of the map service that was not found.
mapUpdateBegin This event is raised when the map has started to update. Map updates are generally long running events which may need UI updates to indicate progress. This should not be confused with the commandBegin event described above. function()
mapUpdateEnd This event is raised when the map has finished updating. This should not be confused with the commandEnd event described above. function(<error>)
Where <error> is an error message returned from the map scheme, or undefined if the update was successful.

Template Events

Event Name Description Handler Signature
getTemplateGroups This event is raised to retrieve all available template groups. function()

Returns a promise that resolves to a JSON string containing template group names. This JSON string has this form:
					[
						"group name one",
						"group name two,
						...
					]
findTemplates This event is raised to retrieve the templates in a group. The event either returns all the templates in a group or all the templates in a group that match an optional search string. function(<groupName>, <search>)
Where <groupName> is a group name as returned by the getTemplateGroups event handler and <search> is an optional search s string.

Returns a promise that resolves to a JSON string containing metadata about the templates in the specified group. This JSON string has this form:
					[
						{
							"id": <template ID>,
							"name": "<template name>",
							"description": "<template description>"
						},
						...
					]
getTemplate This event is raised to retrieve the SVG for a template. function(<id>)
Where <id> is a template ID as returned by the findTemplates event handler.

Returns a promise that resolves to the template; I.E., an SVG diagram string.
The handlers for each of these events returns a Dojo promise that resolves to the requested information. More info on Dojo promises is available here.

Each of these events is analogous to one of the template service REST requests that are described here.

Example:
						// 1) These examples assume editor is an initialized ESDWeb object
						// 2) The templateDatabase methods below are just example stubs.
						//    You will need to replace them with something that retrieves
						//    the data from your data store of choice.

						require(["dojo/Deferred"], function(Deferred) {
						    editor.on('getTemplateGroups', function() {
        						var deferred = new Deferred(),
									result;

								// Retrieve and return the template groups.
								result = templateDatabase.getGroups();
								setTimeout(function() {
									deferred.resolve(JSON.stringify(result));
								});

								return deferred.promise;
						    });

							editor.on('findTemplates', function(groupName, searchString) {
        						var deferred = new Deferred(),
									result;

								// Retrieve and return a collection of matching templates.
								result = templateDatabase.getTemplates(groupName, searchString);
								setTimeout(function() {
									deferred.resolve(JSON.stringify(result));
								});

								return deferred.promise;
							});

							editor.on('getTemplate', function(templateID) {
        						var deferred = new Deferred(),
									result;

								// Retrieve and return the SVG for a template.
								result = templateDatabase.getTemplate(templateID);
								setTimeout(function() {
									deferred.resolve(result);
								});

								return deferred.promise;
							});
						});
					

Other Editor Events

Event Name Description Handler Signature
connect 1 This event is raised during editor startup. function(<Feature List>, <Success Callback>, <Error Callback>)
convertLegacyDiagram 1 The handler for this event is called when loading a text-encoded legacy ESD/SPD diagram. The default handler calls the ESD/SPD web service to convert the diagram to the SVG format supported by the ESD/SPD Web editor. function(<Text Encoded Diagram>, <Success Callback>, <Error Callback>)
diagramDirty This event is raised when the diagram has been modified. function(<Diagram Dirty State Boolean>)
exception 1 This event is raised if an exception occurs in the ESD/SPD Web editor.

Note that when you register a handler for this event, your handler is responsible for all exception logging and reporting. I.E., registering an exception handler disables the editor's built-in exception UI and exception logging mechanisms.
function(<Exception>, <Error Number>, <Summary Message>, <Detail Message>, <Log Only>)
Where:
  • Exception: The exception object.
  • Error Number: An optional numeric error code.
  • Summary Message: A summary message. If omitted, a generic message should be used.
  • Detail Message: More detailed message. If omitted, exception message should be used.
  • Log Only: When true, the exception will be logged but will not be delivered to the user using the standard exception reporting mechanism. The assumption is that when this parameter is true, the user will be informed in some other way. The default is false.
externalDragDrop This handler is called when the user drags one or more files from the file system and drops them on the editor window. function(<drop event>)
Where <drop event> is a hash containing these properties:
filenames: an array containing the name(s) of the file(s) dropped on the editor
clientX: the X coordinate of the drop location
clientY: the Y coordinate of the drop location
favoritesInitialize This handler is called during editor startup to provide the initial symbol favorites. function()
Returns a promise that resolves to a string of symbol favorites.
favoritesChange This event is raised when the user adds or removes a symbol from "favorites". The function argument is an array of objects describing the user's updated favorites list. Your application could respond by storing the favorites definition array in the user's profile data store. To set a user's favorites at editor startup, use the preferences property. function(<Favorites Definition Array>)
Where <Favorites Definition> is an array of objects - each describing a "favorite" symbol.
modalDialogBegin The handler for this event is called when a modal dialog is about to open. Examples of modal dialogs include the template selection window and the map manager's Set Location window. function()
modalDialogEnd The handler is called when a modal dialog has closed. function()
selectionChanged This event is raised when one or more shapes have been selected or unselected in the editor. function(<selectedShapeCount>)
Where <selectedShapeCount> is the number of shapes currently selected.
selectTemplate 1 The handler for this event is called when the user chooses the "Start with a template" link. This link is displayed in the editor window when the diagram is empty. Install a handler for this event if you wish to implement your own template selection facility. function()
showAttachment This event is raised when the user selects "Show Attachment" from the context menu of a camera or document symbol that represents an attachment. Your app can respond by opening a viewer or editor for the attachment identified by the attachment ID provided in the function argument. function(<Attachment ID String>)
Where <Attachment ID> is the unique id of an existing image or document attachment.
viewAdded This event is raised when a view is added to the diagram. function(<viewState>)
Where <viewState> is the viewState object for the added view.
viewDeleted This event is raised when a view is deleted from the diagram. function(<viewState>)
Where <viewState> is the viewState object for the deleted view or undefined if the diagram was erased.
viewStateChange This event is raised when a view is modified. function(<viewState>)
Where <viewState> is the viewState object for the modified view.

Info Events

Event Name Description Handler Signature
showHelpVideos 1 This event is raised when the user asks to view product help videos. function()
showErrorLog 1 This event is raised when the user asks to view the error log. function()

Notes:

1Only one handler for this event can be installed at any given time.