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:
|
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() |