Skip to main contentElyra

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.

Introduction

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 pipline flows, Pipeline IDs must be globally unique identifiers.

Pipeline flow methods

The API provides the following:

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

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

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

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.

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 Specification documentation 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

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 section 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)

Node methods

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


// Returns a new node created from the object passed in which has the
// following properties:
// nodeTemplate - a node template from the palette
// offsetX - the x coordinate of the new node
// offsetY - the y coordinate of the new node
// pipelineId - the ID of the pipeline where the new node will exist

The format of the message object is described in Pipeline Flow UI schema: https://github.com/elyra-ai/pipeline-schemas/blob/master/common-pipeline/pipeline-flow/pipeline-flow-ui-v1-schema.json

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)

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)

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

Operational methods

These are general purpose methods for operation of the canvas:

// 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)


// Opens the palette
openPalette()
Previous
Common Canvas: Enabling external node creation
Next
Canvas controller API: Style spec