Canvas Controller API¶

Your application code can programmatically perform many of the actions that the user can do in the Common Canvas using the Canvas Controller API. Note: See this page for differences between the structure of objects in the API and the schema.

In most cases within the API, the pipelineId parameter is optional. If pipelineId is omitted, the method will default to the pipeline that is currently displayed in the main canvas viewport.

Warning 1: Do not alter the IDs of objects that currently exist on the canvas. Changing object IDs can cause internal problems, in particular with the command stack.

Warning 2: When using external pipeline flows, Pipeline IDs must be globally unique identifiers.

The API provides the following:

Pipeline Flow methods¶

// Loads the pipelineFlow document provided into Common Canvas and displays it.
// The document must conform to the pipelineFlow schema as documented in the
// elyra-ai pipeline-schemas repo. Documents conforming to older versions may be
// provided but they will be upgraded to the most recent version.
setPipelineFlow(flow)

// Clears the pipleine flow and displays an empty canvas.
clearPipelineFlow()

// Returns the current pipelineFlow document in the latest version of the
// pipelineFlow schema as documented in the elyra-ai pipeline-schemas repo.
getPipelineFlow()

// Returns the current pipelineFlow document ID.
getPipelineFlowId()

// Returns the ID of the primary pipeline from the pipelineFlow.
getPrimaryPipelineId()

// Returns the external pipeline flow for the url passed in. The external
// flow must have been loaded through some Common Canvas action for this
// method to be able to return anything.
getExternalPipelineFlow(url)

// Returns the internal format of all canvas data stored in memory by
// Common Canvas. Nodes, comments and links are returned in the internal
// format.
getCanvasInfo()

// Returns the IDs of the ancestor pipleline of the pipeline ID passed in.
getAncestorPipelineIds(pipelineId)

// Removes all styles from nodes, comments and links. See the setObjectsStyle
// and setLinkStyle methods for details on setting styles.
// temporary - is a boolean that indicates whether temporary or permanent
// styles should be removed.
removeAllStyles(temporary)

// Specifies the new styles for objects that are not highlighted during
// branch highlighting.
// newStyle - is a style specification object.
setSubdueStyle(newStyle)

Pipeline methods¶

// Returns the pipeline object for the pipeline Id passed in.
getPipeline(pipelineId)

// Returns the ID of the pipeline object which is currently on display
// in the canvas. Typically, this is the primary pipeline but will be
// different if the user has navigated into one or more supernodes; in
// which case it will be the ID of the pipeline at the level in the
// supernode hierarchy that is currently on display.
getCurrentPipelineId()

// Returns truty if the pipeline is external (that is it is part of an
// external pipeline flow). Otherwise, return falsy to indicate the pipeline
// is local.
isPipelineExternal(pipelineId)

// Returns the flow validation messages for the pipeline ID passed in.
getFlowMessages(pipelineId)

// Returns a boolean to indicate whether there are any messages of
// includeMsgsType in the pipeline identified by the pipeline ID passed in.
// includeMsgsType - can be either "error" or "warning"
isFlowValid(includeMsgTypes, pipelineId)

// Rearranges the nodes in the canvas in the direction specified for the
// pipeline ID passed in.
// layoutDirection - can be "horizontal" or "vertical"
autoLayout(layoutDirection, pipelineId)

Palette methods¶

// Loads the palette data as described in the palette schema in
// elyra-ai pipeline-schemas repo. Any version can be loaded and it will be
// upgraded to the latest version.
setPipelineFlowPalette(palette)

// Clears the palette data from Common Canvas.
clearPaletteData()

// Sets the loading text of the category. If set to a non-empty string the
// category will show an InlineLoading control in the palette category div
// with this text as the label. If set to falsey the palette category
// will display as normal.
setCategoryLoadingText(categoryId, loadingText)

// Sets the empty text of the category. If set to a non-empty string and the
// category does not have any nodes, the palette will show a warning icon with
// this text as a message under the category title when the category is opened.
// This message will not be displayed if the field is set to falsey or if
// nodetypes are added to the category.
setCategoryEmptyText(categoryId, emptyText)

// Adds a new node into the palette:
// nodeTypeObj - must conform to the style of node used by the palette as
// described in the palette schema. See objects in nodeTypes array in the
// palette schema:
//  https://github.com/elyra-ai/pipeline-schemas/blob/master/common-canvas/palette/palette-v3-schema.json
// category - is the name of the palette category where the node will be
// added. If the category doesn't exist it will be created.
// categoryLabel - Is an optional param. If a new category is created it will
// be displayed with this label.
// categoryDescription - Is an optional param. If a new category is created
// it will be displayed with this description.
// categoryImage - Is an optional param. The image displayed for the category provided as a
// reference to an image or the image itself.
addNodeTypeToPalette(nodeTypeObj, categoryId, categoryLabel, categoryDescription, categoryImage)

// Adds an array of new node into the palette:
// nodeTypeObjs - an array of nodetypes that must conform to the style of
// nodes used by the palette as described in the palette schema. See objects
// in nodeTypes array in the palette schema:
//  https://github.com/elyra-ai/pipeline-schemas/blob/master/common-canvas/palette/palette-v3-schema.json
// category - is the name of the palette category where the node will be
// added. If the category doesn't exist it will be created.
// categoryLabel - is an optional param. If a new category is created it will
// be displayed with this label.
// categoryImage - the image displayed for the category provided as a
// reference to an image or the image itself.
// categoryDescription - Is an optional param. If a new category is created
// it will be displayed with this description.
// categoryImage - Is an optional param. The image displayed for the category provided as a
// reference to an image or the image itself.
addNodeTypesToPalette(nodeTypeObjs, categoryId, categoryLabel, categoryDescription, categoryImage)

// Removes nodetypes from a palette category
// selObjectIds - an array of object IDs to identify the nodetypes to be
// removed
// categoryId - the ID of the category from which the nodes will be removed
removeNodesFromPalette(selObjectIds, categoryId)

// Returns the palette data document which will conform to the latest version
// of the palette schema.
getPaletteData()

// Returns the palette node identified by the operator ID passed in.
getPaletteNode(operatorId)

// Returns the palette node identified by the node ID passed in.
getPaletteNodeById(nodeId)

// Returns the category of the palette node identified by the operator passed in
getCategoryForNode(nodeOpIdRef)

// Converts a node template from the format use in the palette (that conforms
// to the schema) to the internal node format.
convertNodeTemplate(nodeTemplate)

// Opens the palette category identified by the category ID passed in.
openPaletteCategory(categoryId)

// Closes the palette category idetified by the category ID passed in.
closePaletteCategory(categoryId)

// Opens all the palette categories.
openAllPaletteCategories()

// Closes all the palette categories.
closeAllPaletteCategories()

// Returns true or false to indicate whether a palette category is open or not.
isPaletteCategoryOpen(categoryId)

Selections methods¶

// Sets the currently selected objects replacing any current selections.
// newSelection - An array of object IDs for nodes and/or comments
// pipelineId - Optional. The ID of the pipeline where the objects exist.
// Selected objects can only be in one pipeline. If this parameter is omitted
// it is assumed the selections will be for objects in the 'top-level' pipeline
// being displayed.
setSelections(newSelection, pipelineId)

// Clears all the current selections from the canvas.
clearSelections()

// Selects all the objects on the canvas.
selectAll()

// Returns an array of the IDs of the currently selected objects.
getSelectedObjectIds()

// Returns the currently selected Nodes.
getSelectedNodes()

// Returns the currently selected Comments.
getSelectedComments()

// Returns the ID of the pipeline in which the currently selected objects
// exist. Only one pipeline may contain selected objects.
getSelectedPipelineId()

// Deletes all currently selected objects.
deleteSelectedObjects()

// Returns true if the currently selected objects are all linked together.
// This is used when deciding to creating a supernode.
areSelectedNodesContiguous()

Notification messages methods¶

The notification panel is displayed by the user by clicking the notifications icon in the toolbar. Your application can display whatever messages it wants in the notification panel. See the Notification Messages paage for the structure of message objects. The contents of the notification panel can be managed using the methods below:

// Overwrites the array of notification messages shown in the notification
// panel.
// newMessage - An array of messages (see getNotificationMessages)
setNotificationMessages(newMessages)

// Deletes all notification messages shown in the notification panel.
clearNotificationMessages()

// Removes the notification messages from the given array of ids
deleteNotificationMessages(ids)

// Returns the array of current notification messages. If the messageType is
// provided only messages of that type will be returned. If messageType is
// not provided, all messages will be returned. The format of a notification
// message is an object with these fields:
// {
//   "id": string (Required),
//   "type" : enum, oneOf ["info", "success", "warning", "error"] (Required),
//   "callback": function, the callback function when a message is clicked (Required),
//   "title": string (Optional),
//   "content": string, html, JSX Object (Optional),
//   "timestamp": string (Optional),
//   "closeMessage": string (Optional)
// }
getNotificationMessages(messageType)

// Returns the maximum notification message type present in the current set
// of notification messages. For this: ("error" > "warning" > "success" > "info")
getNotificationMessagesMaxType()

Node AND comment methods¶

In Common Canvas nodes and comments are collectively known as objects. The following methods may be used to manage either collections of comments or nodes or a mixture of both. Note:

See this sections if you are working with styles.
See this section if you are working with decorations.

See this section for differences between the structure of objects in the API and the schema.

// Moves the objects identified in the data object which must be in the
// pipeline identified by the pipeline ID.
// data - A javascript object like this:
// {
//   nodes: []       // An array of node and comment IDs
//   offsetX: number // Offset in pixels the objects will move in the X dir
//   offsetY: number // Offset in pixels the objects will move in the Y dir
// }
moveObjects(data, pipelineId)

// Deletes the objects specified in objectIds array.
// objectIds - An array of node and comment IDs
deleteObjects(objectIds, pipelineId)

// Removes the links to and from the objects specified in the objectIds array.
// objectIds - An array of node and comment IDs
disconnectObjects(objectIds, pipelineId)

// Deletes the object specified by the id in the pipleine specified by
// pipeline ID.
// @Deprecated Use deleteNode or deleteComment as appropriate instead.
deleteObject(id, pipelineId)

// Sets the style of the objects specified by pipelineObjectIds to be
// the newStyle which will be either temporary or permanent.
// pipelineObjectIds: This identified the objects to be styles. It is a
// javascript object like this:
//   {
//     <pipelineID_1>: [
//       <objectID_1_1>,
//       <objectID_1_2>
//     ],
//     <pipelineID_2>: [
//         <objectID_2_1>,
//         <objectID_2_2>
//     ]
//   }
// newStyles - This is a style specification objects.
// temporary - A boolean to indicate if the style is serialized when
//             getPipelineFlow() method is called or not.
setObjectsStyle(pipelineObjectIds, newStyle, temporary)

// Sets the styles of multiple objects at once.
// pipelineObjStyles - Specified the objects and the styles each should be
// set to. It is a javascript array like this:
//   [
//     { pipelineId: <pipelineId>, objId: <objectId>, style: <style_spec>},
//     { pipelineId: <pipelineId>, objId: <objectId>, style: <style_spec>},
//     { pipelineId: <pipelineId>, objId: <objectId>, style: <style_spec>}
//   ]
// temporary - A boolean to indicate if the styles are serialized when
//             getPipelineFlow() method is called or not.
setObjectsMultiStyle(pipelineObjStyles, temporary)

Node methods¶

// Retuns an array of nodes for the pipeline specified by the pipelineId.
getNodes(pipelineId)

// Returns a new node created from the data parameter in the pipeline
// identified by the pipelineId.
// The data parameter must contain:
// nodeTemplate -  a node template from the palette. The nodeTemplate
//                 can be retrieved from the palette using with Canvas
//                 Controller methods: getPaletteNode or getPaletteNodeById.
// offsetX - the x coordinate of the new node
// offsetY - the y coordinate of the new node
createNode(data, pipelineId)

// Adds a new node into the pipeline specified by the pipelineId.
addNode(node, pipelineId)

// Creates a node using the data parameter provided in the pipeline specified
// by pipelineId and adds the command to the command stack (so the user can
// undo/redo the command). This will also cause the beforeEditActionHandler
// and editActionHandler callbacks to be called.
// The data parameter must contain:
// nodeTemplate -  a node template from the palette. The nodeTemplate
//                 can be retrieved from the palette using with Canvas
//                 Controller methods: getPaletteNode or getPaletteNodeById.
// offsetX - the x coordinate of the new node
// offsetY - the y coordinate of the new node
//
// If pipelineId is omitted the node will be created in the current
// "top-level" pipeline.
createNodeCommand(data, pipelineId)

// Deletes the node specified.
// nodeId - The ID of the node
// pipelineId - The ID of the pipeline
deleteNode(nodeId, pipelineId)

// Sets the node properties
// nodeId - The ID of the node
// properties - An object containing properties to be overriden in the node
// pipelineId - The ID of the pipeline
setNodeProperties(nodeId, properties, pipelineId)

// Sets the node parameters
// nodeId - The ID of the node
// parameters - An array of parameters
// pipelineId - The ID of the pipeline
setNodeParameters(nodeId, parameters, pipelineId)

// Sets the node UI parameters
// nodeId - The ID of the node
// parameters - An array of UI parameters
// pipelineId - The ID of the pipeline
setNodeUiParameters(nodeId, uiParameters, pipelineId)

// Sets the node messages
// nodeId - The ID of the node
// messages - An array of messages
// pipelineId - The ID of the pipeline
setNodeMessages(nodeId, messages, pipelineId)

// Sets a single message on a node
// nodeId - The ID of the node
// message - A message
// pipelineId - The ID of the pipeline
setNodeMessage(nodeId, message, pipelineId)

// Sets the lable for a node
// nodeId - The ID of the node
// ndeLabel - The label
// pipelineId - The ID of the pipeline
setNodeLabel(nodeId, newLabel, pipelineId)

// Sets the class name to newClassName of the nodes identified by nodeIds
// array in the pipleine specified by pipeline ID. The class name will be
// applied to the node body path.
setNodesClassName(nodeIds, newClassName, pipelineId)

// Sets the decorations on a node. The decorations array passed in
// will replace any decorations currently applied to the node.
// nodeId - The ID of the node
// newDecorations - An array of decoration objects.
// pipelineId - The ID of the pipeline
setNodeDecorations(nodeId, newDecorations, pipelineId)

// Sets the input ports on a node. The inputs array of ports provided will
// replace any input ports for a node.
// nodeId - The ID of the node
// inputs - An array of input port objects.
// pipelineId - The ID of the pipeline
setNodeInputPorts(nodeId, inputs, pipelineId)

// Sets the output ports on a node. The outputs array of ports provided will
// replace any output ports for a node.
// nodeId - The ID of the node
// outputs - An array of output port objects.
// pipelineId - The ID of the pipeline
setNodeOutputPorts(nodeId, outputs, pipelineId)

// Sets the decorations of multiple nodes at once. The decorations array
// passed in will replace any decorations currently applied to the nodes.
// pipelineNodeDecorations - Specifies the nodes and their decorations.
// It is a JavaScript array like this:
//   [
//     { pipelineId: <pipelineId>, nodeId: <nodeId>, decorations: <decoration_spec_array>},
//     { pipelineId: <pipelineId>, nodeId: <nodeId>, decorations: <decoration_spec_array>},
//     { pipelineId: <pipelineId>, nodeId: <nodeId>, decorations: <decoration_spec_array>}
//   ]
setNodesMultiDecorations(pipelineNodeDecorations)

// Sets the input port label on a node
// nodeId - The ID of the node
// portId - The ID of the input port
// newLabel - The label
// pipelineId - The ID of the pipeline
setInputPortLabel(nodeId, portId, newLabel, pipelineId)

// Sets the output port label on a node
// nodeId - The ID of the node
// portId - The ID of the output port
// newLabel - The label
// pipelineId - The ID of the pipeline
setOutputPortLabel(nodeId, portId, newLabel, pipelineId)

// Gets a node
// nodeId - The ID of the node
// pipelineId - The ID of the pipeline
getNode(nodeId, pipelineId)

// Gets the UI parameters for a node
// nodeId - The ID of the node
// pipelineId - The ID of the pipeline
getNodeUiParameters(nodeId, pipelineId)

// Gets the supernodes for a pipeline.
// pipelineId - The ID of the pipeline
getSupernodes(pipelineId)

// Returns supernode ID that has a subflow_ref to the given pipelineId.
getSupernodeObjReferencing(pipelineId)

// Gets the messages for a node
// nodeId - The ID of the node
// pipelineId - The ID of the pipeline
getNodeMessages(nodeId, pipelineId)

// Gets the array of input ports for the node or null if the node ID is
// not recognized.
// nodeId - The ID of the node
// pipelineId - The ID of the pipeline
getNodeInputPorts(nodeId, pipelineId)

// Gets the array of output ports for the node or null if the node ID is
// not recognized.
// nodeId - The ID of the node
// pipelineId - The ID of the pipeline
getNodeOutputPorts(nodeId, pipelineId)

// Gets a message for a specific control for a node
// nodeId - The ID of the node
// controlName - The control name
// pipelineId - The ID of the pipeline
getNodeMessage(nodeId, controlName, pipelineId)

// Gets an array of decorations for a node
// nodeId - The ID of the node
// pipelineId - The ID of the pipeline
getNodeDecorations(nodeId, pipelineId)

// Gets the class name associated with the node specified by nodeId in the
// pipeline specified by pipelineId.
getNodeClassName(nodeId, pipelineId)

// Gets the style spcification for a node.
// nodeId - The ID of the node
// temporary - A boolean to indicate if the style is serialized when
//             getPipelineFlow() method is called or not.
// pipelineId - The ID of the pipeline
getNodeStyle(nodeId, temporary, pipelineId)

// Returns an array of nodes that are for the branch(es) that the nodes,
// identified by the node IDs passed in, are within.
// nodeIds - An array of node Ids
// pipelineId - The ID of the pipeline where the nodes exist
getBranchNodes(nodeIds, pipelineId)

// Returns an array of nodes that are upstream from the nodes
// identified by the node IDs passed in.
// nodeIds - An array of node Ids
// pipelineId - The ID of the pipeline where the nodes exist
getUpstreamNodes(nodeIds, pipelineId)

// Returns an array of nodes that are downstream from the nodes
// identified by the node IDs passed in.
// nodeIds - An array of node Ids
// pipelineId - The ID of the pipeline where the nodes exist
getDownstreamNodes(nodeIds, pipelineId)

// Returns a boolean to indicate whether the supernode is expanded in place.
// nodeId - The ID of the node
// pipelineId - The ID of the pipeline
isSuperNodeExpandedInPlace(nodeId, pipelineId)

// Sets the label, for the node identified, to edit mode, provided the node
// label is editable. This allows the user to edite the label text.
setNodeLabelEditingMode(nodeId, pipelineId)

// Sets the decoration label, for the decoration in the node identified, to edit
// mode, provided the node label is editable. This allows the user to edit the
// label text.
setNodeDecorationLabelEditingMode(decId, nodeId, pipelineId)

Comment methods¶

// Returns the comments from the pipeline.
// pipelineId - The ID of the pipeline
getComments(pipelineId)

// Returns a comment from the pipeline.
// comId - The ID of the comment
// pipelineId - The ID of the pipeline
getComment(comId, pipelineId)

// Returns a position object which indicates the position of where a new
// comment should be placed in a situation where the mouse position cannot be
// used (e.g. the toolbar button was clicked).
// pipelineId - The ID of the pipeline
getNewCommentPosition(pipelineId)

// Creates a comment for the pipeline.
// source - Input data
// pipelineId - The ID of the pipeline
createComment(source, pipelineId)

// Adds a comment to the pipeline.
// data - the data describing the comment
// pipelineId - The ID of the pipeline
addComment(data, pipelineId)

// Edits a comment with the data.
// data - the comment
// pipelineId - The ID of the pipeline
editComment(data, pipelineId)

// Sets the properties in the comment identified by the commentId. The
// commentProperties is an object containing one or more properties that will
// replace the corresponding properties in the comment. For example: if
// commentProperties is { x_pos: 50, y_pos: 70 } the comment
// will be set to that position.
setCommentProperties(commentId, commentProperties, pipelineId)

// Sets the class name to newClassName of the comments identified by commentIds
// array in the pipleine specified by pipeline ID. The class name will be
// applied to the comment body path.
setCommentsClassName(commentIds, newClassName, pipelineId)

// Deletes a comment
// comId - The ID of the comment
// pipelineId - The ID of the pipeline
deleteComment(comId, pipelineId)

// Gets the class name associated with the comment specified by commentId in the
// pipeline specified by pipelineId.
getCommentClassName(commentId, pipelineId)

// Gets the style spcification for a comment
// commentId - The ID of the node
// temporary - A boolean to indicate if the style is serialized when
//             getPipelineFlow() method is called or not.
// pipelineId - The ID of the pipeline
getCommentStyle(commentId, temporary, pipelineId)

// Hides all comments on the canvas.
hideComments()

// Shows all comments on the canvas - if they were previously hiding.
showComments()

// Returns true if comments are currently hiding.
isHidingComments()

// Sets the comment identified, to edit mode so the user can
// edit the comment.
setCommentEditingMode(commentId, pipelineId)

Link methods¶

// Gets a link
// linkId - The ID of the link
// pipelineId - The ID of the pipeline
getLink(linkId, pipelineId)

// Returns an array of link objects for the pipelineId passed in.
// pipelineId - The ID of the pipeline
getLinks(pipelineId)

// Sets the properties in the link identified by the linkId. The
// linkProperties is an object containing one or more properties that will
// replace the corresponding properties in the link. For exam`ple: if
// linkProperties is { trgNodeId: "123", trgNodePortId: "789" } the target
// node ID will be set to "123" and the target port ID set to "789".
setLinkProperties(linkId, linkProperties, pipelineId)

// Sets the source properties in the data link identified by the linkId. The
// srcNodeId and srcNodePortId will be set to the values provided. If
// srcNodePortId is set to null the current srcNodePortId will be removed
// from the link. Also, if the link has a srcPos property (because its
// source end is detached) that will be removed.
setNodeDataLinkSrcInfo(linkId, srcNodeId, srcNodePortId, pipelineId)

// Sets the target properties in the data link identified by the linkId. The
// trgNodeId and trgNodePortId will be set to the values provided. If
// trgNodePortId is set to null the current trgNodePortId will be removed
// from the link. Also, if the link has a trgPos property (because its
// target end is detached) that will be removed.
setNodeDataLinkTrgInfo(linkId, trgNodeId, trgNodePortId, pipelineId)

// Gets a node to node data link
// srcNodeId - The ID of the source node
// srcNodePortId - The ID of the source node port
// trgNodeId - The ID of the target node
// trgNodePortId - The ID of the target node port
// pipelineId - The ID of the pipeline
getNodeDataLinkFromInfo(srcNodeId, srcNodePortId, trgNodeId, trgNodePortId, pipelineId)

// Gets a comment to node link
// id1 - The ID of the comment
// id2 - The ID of the node
// pipelineId - The ID of the pipeline
getCommentLinkFromInfo(id1, id2, pipelineId)

// Gets a node to node association link
// id1 - The ID of one of the node
// id2 - The ID of one of the node
// pipelineId - The ID of the pipeline
getNodeAssocLinkFromInfo(id1, id2, pipelineId)

// Adds links to a pipeline
// linkList - An array of links
// pipelineId - The ID of the pipeline
addLinks(linkList, pipelineId)

// Deletes a link
// link - the link object to be deleted
// pipelineId - The ID of the pipeline
deleteLink(link, pipelineId)

// Creates node to node links
// data - Data describing the links
// pipelineId - The ID of the pipeline
createNodeLinks(data, pipelineId)

// Creates comment links
// data - Data describing the links
// pipelineId - The ID of the pipeline
createCommentLinks(data, pipelineId)

// Sets the class name to newClassName of the links identified by linkIds
// array in the pipleine specified by pipeline ID. The class name will be
// applied to the link line path.
setLinksClassName(linkIds, newClassName, pipelineId)

// Sets the style of the links specified by pipelineLinkIds to be
// the newStyle which will be either temporary or permanent.
// pipelineLinkIds - This identifies the objects to be styles. It is a
// javascript object like this:
//   {
//     <pipelineID_1>: [
//       <linkID_1_1>,
//       <linkID_1_2>
//     ],
//     <pipelineID_2>: [
//         <linkID_2_1>,
//         <linkID_2_2>
//     ]
//   }
// newStyle - This is a style specification objects.
// temporary - A boolean to indicate if the style is serialized when
//             getPipelineFlow() method is called or not.
setLinksStyle(pipelineLinkIds, newStyle, temporary)

// Sets the styles of multiple links at once.
// pipelineObjStyles - Specified the links and the styles each should be
// set to. It is a javascript array like this:
//   [
//     { pipelineId: <pipelineId>, objId: <linkId>, style: <style_spec>},
//     { pipelineId: <pipelineId>, objId: <linkId>, style: <style_spec>},
//     { pipelineId: <pipelineId>, objId: <linkId>, style: <style_spec>}
//   ]
// temporary - A boolean to indicate if the styles are serialized when
//             getPipelineFlow() method is called or not.
setLinksMultiStyle(pipelineObjStyles, temporary)

// Gets the class name associated with the link specified by linkId in the
// pipeline specified by pipelineId.
getLinkClassName(linkId, pipelineId)

// Returns the style specification for a link.
// linkIds - An array of links
// temporary - A boolean to indicate if the style is serialized when
//             getPipelineFlow() method is called or not.
// pipelineId - The ID of the pipeline
getLinkStyle(linkId, temporary, pipelineId)

// Sets the decorations on a link. The decorations array passed in
// will replace any decorations currently applied to the link.
// linkId - The ID of the link
// newDecorations - An array of decoration objects.
// pipelineId - The ID of the pipeline
setLinkDecorations(linkId, newDecorations, pipelineId)

// Sets the decorations of multiple links at once. The decorations array
// passed in will replace any decorations currently applied to the links.
// pipelineLinkDecorations - Specifies the links and their decorations.
// It is a javascript array like this:
//   [
//     { pipelineId: <pipelineId>, linkId: <linkId>, decorations: <decoration_spec_array>},
//     { pipelineId: <pipelineId>, linkId: <linkId>, decorations: <decoration_spec_array>},
//     { pipelineId: <pipelineId>, linkId: <linkId>, decorations: <decoration_spec_array>}
//   ]
setLinksMultiDecorations(pipelineLinkDecorations)

// Gets an array of decorations for a link
// linkId - The ID of the link
// pipelineId - The ID of the pipeline
getLinkDecorations(linkId, pipelineId)

// Sets the decoration label, for the decoration in the link identified, to edit
// mode provided the link label is editable. This allows the user to edit the
// label text.
setLinkDecorationLabelEditingMode(decId, linkId, pipelineId)

Breadcrumbs methods¶

// Returns the current array of breadcrumbs. There will one breadcrumb object
// for each level of supernode that the user has navigated into. This array
// can be used to display breadcrumbs to the user to show where they are
// within the navigation hierarchy within Common Canvas.
getBreadcrumbs()

// Returns the last breadcrumb which represents the level with supernode
// hierarchy that the user has currently navigated to.
getCurrentBreadcrumb()

Branch Highlight methods¶

// Highlights the branch(s) (both upstream and downstream) from the node
// IDs passed in and returns the highlighted object Ids.
// nodeIds - An array of node Ids
// pipelineId - The ID of the pipeline
highlightBranch(nodeIds, pipelineId)

// Highlights the upstream nodes from the node IDs passed in
// and returns the returns the highlighted object Ids.
// nodeIds - An array of node Ids
// pipelineId - The ID of the pipeline
highlightUpstream(nodeIds, pipelineId)

// Highlights the downstream nodes from the node IDs passed in
// and returns highlighted object Ids.
// nodeIds - An array of node Ids
// pipelineId - The ID of the pipeline
highlightDownstream(nodeIds, pipelineId)

Operational methods¶

These are general purpose methods for operation of the common-canvas components:

Logging methods¶

// Returns a Boolean to indicate whether canvas logging is switched on or off.
getLoggingState()

// Sets canvas logging based on the Boolean passed in.
setLoggingState(state)

Palette methods¶

// Opens the palette
openPalette()

// Closes the palette
closePalette()

// Returns true if the palette is currently open
isPaletteOpen()

// Opens the context menu
openContextMenu(menuDef)

// Closes the context menu
closeContextMenu()

Notification Panel methods¶

// Opens the notification panel
openNotificationPanel()

// Closes the notification panel
closeNotificationPanel()

// Either opens or closes the notifictaion panel based on its current status
toggleNotificationPanel()

// Returns a boolean to indicate if the right flyout is open or not
isRightFlyoutOpen()

Top panel methods¶

// Returns a boolean to indicate if the top pnel is open or not
isTopPanelOpen()

Bottom panel methods¶

// Returns a boolean to indicate if the bottom panel is open or not
isBottomPanelOpen()

// Sets the height of the bottom panel in pixels. This can be called
// immediately after the CanvasController has been created, if the bottom
// panel should be displayed at a specific height when it first opens.
setBottomPanelHeight(height)

// Displays a pipeline (identified by the pipelineId passed in). This must be
// one of the pipelines referenced by the current set of breadcrumbs. It
// cannot be used to open a new pipeline outside the current set of breadcruumbs.
displaySubPipeline(pipelineId)

// Displays a pipeline for a supernode (identifid by the supernodeId
// parameter) in a parent pipeline (identifid by the pipelineId parameter).
// This parent pipeline should be the last of the current set of breadcumbs.
// That is, the pipeline currently shown "full page" in the canvas.
displaySubPipelineForSupernode(supernodeId, pipelineId)

// Displays full-page the previous pipeline from the one currently being displayed
displayPreviousPipeline()

Command Stack interaction methods¶

// Adds the command object to the command stack which will cause the
// do() method of the command to be called.
do(command)

// Calls the undo() method of the next available command on the command
// stack that can be undone, if one is available.
undo()

// Undoes a number of commands on the command stack as indicated by the
// 'count' parameter. If 'count' is bigger than the number of undoable commands
// on the stack, all undoable commands currently on the command stack
// will be undone. Uses the editActionHandler method which will cause
// the app's editActionHandler to be called.
undoMulti(count)

// Calls the redo() method of the next available command on the command
// stack that can be redone, if one is available.
redo()

// Redoes a number of commands on the command stack as indicated by the
// 'count' parameter. If 'count' is bigger than the number of redoable commands
// on the stack, all redoable commands currently on the command stack
// will be redone. Uses the editActionHandler method which will cause
// the app's editActionHandler to be called.
redoMulti(count)

// Returns true if there is a command on the command stack
// available to be undone.
canUndo()

// Returns true if there is a command on the command stack
// available to be redone.
canRedo()

// Returns a string which is the label that descibes the next undoable
// command.
getUndoLabel()

// Returns a string which is the label that descibes the next redoable
// command.
getRedoLabel()

// Returns an array of all undoable commands currently on the command stack.
getAllUndoCommands()

// Returns an array of all redoable commands currently on the command stack.
getAllRedoCommands()

// Clears the command stack of all currently stored commands.
clearCommandStack()

Zoom methods¶

// Centers the canvas contents and zooms in
zoomIn()

// Centers the canvas contents and zooms out
zoomOut()

// Zooms the canvas contents to fit within the viewport
zoomToFit()

// Changes the zoom amounts for the canvas. This method does not alter the
// pipelineFlow document. zoomObject is an object with three fields:
// x: Is the horizontal translate amount which is a number indicating the
//    pixel amount to move. Negative left and positive right
// y: Is the vertical translate amount which is a number indicating the
//    pixel amount to move. Negative up and positive down.
// k: is the scale amount which is a number greater than 0 where 1 is the
//    default scale size.
zoomTo(zoomObject)

// Increments the translation of the canvas by the x and y increment
// amounts. The optional animateTime parameter can be provided to animate the
// movement of the canvas. It is a time for the animation in milliseconds.
// If omitted the movement happens immediately.
translateBy(x, y, animateTime)

// Returns the current zoom object for the currently displayed canvas or null
// if the canvas is not yet rendered for the first time.
getZoom()

// Returns a zoom object required to pan the objects (nodes and/or comments
// and/or links) identified by the objectIds array to 'reveal' the objects
// in the viewport. Returns null if no nodes, comments or links can be found
// using the IDs passed in. Note: node, comment and link IDs must be unique.
// The zoom object returned can be provided to the CanvasController.zoomTo()
// method to perform the zoom/pan action.
// If the xPos and yPos parameters are provided it will return a zoom object
// to pan the center of the objects specified, to a location where, xPos
// is the percentage of the viewport width and yPos is the percentage of the
// viewport height. So if you want the center of the objects specified to be
// in the center of the viewport set xPos to 50 and yPos to 50.
// If the xPos and yPos parameters are undefined (omitted) and all the
// objects are currently fully within the canvas viewport, this method will
// return null. This can be used to detect whether the objects are fully
// visible or not.
// If the xPos and yPos parameters are undefined and the objects are outside
// the viewport, a zoom object will be returned that can be used to zoom them
// so they appear at the nearest side of the viewport to where they are
// currently positioned.
// The zoom object returned has three fields:
// x: Is the horizontal translate amount which is a number indicating the
//    pixel amount to move. Negative left and positive right
// y: Is the vertical translate amount which is a number indicating the
//    pixel amount to move. Negative up and positive down.
// k: is the scale amount which is a number greater than 0 where 1 is the
//    default scale size.
// Parameters:
// objectIds - An array of nodes and/or comment IDs.
// xPos - Optional. Can be set to percentage offset of the viewport width.
// yPos - Optional. Can be set to percentage offset of the viewport height.
getZoomToReveal(objectIds, xPos, yPos)

// Clears any saved zoom values stored in local storage. This means
// newly opened flows will appear with the default zoom. This method
// is only applicable when the `enableSaveZoom` config parameter is
// set to "LocalStorage".
clearSavedZoomValues()

Canvas Controller API¶

Pipeline Flow methods¶

Pipeline methods¶

Palette methods¶

Selections methods¶

Notification messages methods¶

Node AND comment methods¶

Node methods¶

Comment methods¶

Link methods¶

Branch Highlight methods¶

Operational methods¶

Logging methods¶

Palette methods¶

Context menu methods¶

Notification Panel methods¶

Right Flyout methods¶

Top panel methods¶

Bottom panel methods¶

Canvas/pipeline navigation methods¶

Command Stack interaction methods¶

Zoom methods¶