2.0 Common Canvas Documentation - elyra-ai/canvas Wiki

Introduction

Common canvas displays a flow of data operations as nodes and links which the user can create and edit to get the flow they want. These visual flows of data operations are translated into data processing steps performed by a back-end server. Common canvas provides functionality for the visual display of flows in the browser and leaves persistence and execution of data flows to the application. Within common canvas the user can perform operations such as:

  • Create a new node by dragging a node definition from a palette onto the canvas.
  • Create a new node by dragging a node from outside the canvas onto the canvas (you'll have to do some programming to get this to work).
  • Delete a node by clicking a context menu option.
  • Create a link by dragging a line from one node to another.
  • Delete a link by clicking a context menu option.
  • Add a comment to the canvas and draw a link from it to one or more nodes.
  • Edit a comment.
  • Move nodes and comments around in the canvas to get the desired arrangement.
  • And more! ...

Architecture

Common Canvas react object

Common-canvas is a react component that can be used in your react application to display a fully-functional canvas user interface including the function mentioned above. The <CommonCanvas> component is displayed in a <div> provided by your application.

Common-canvas has these constituent parts that are visible to the user:

  • Canvas editor - the main area of the UI where the flow is displayed and edited
  • Palette - a set of node templates that can be dragged to the canvas to create new nodes
  • Context menu - a menu of options for nodes, comments, etc
  • Toolbar - a set of tools across the top of the UI
  • Notification panel - a panel for displaying runtime and other messages to your user
  • Right side flyout - a panel, often used to display node properties
  • Bottom panel - a panel which can be used to display other app related information

and it handles:

  1. the visual display of the flow of operations;
  2. any user gestures on the canvas;
  3. display of context menus;
  4. display and handling of the palette.
  5. provision of callbacks to tell your code what operations the user is performing on the canvas
  6. and much much more.

Canvas Controller

The only mandatory parameter for the <CommonCanvas> component is a regular JavaScript object called the CanvasController.

The CanvasController routes handles calls from the host application and actions performed by the user. It then updates the internal object model which stores:

  1. the data that describes the flow of nodes, links and comments (called a pipelineFlow);
  2. the data that describes the definition of the palette which contains node templates that can dragged to add nodes to the canvas;
  3. the set of currently selected objects.
  4. notification messages
  5. breadcrumbs that indicate which sub-flow is being viewed
  6. layout information

The CanvasController provides an API which allows your code to:

  1. set a new pipelineFlow;
  2. get the current pipelineFlow (after the user has edited it);
  3. update and edit objects in the canvas (for example, add node, delete link etc.);
  4. set the node definition data (for display of nodes in the palette)

Getting started with common canvas programming

Hello Canvas!

You can start by looking at these two 'hello world' examples for using common canvas:

  • This first one called app-tiny.js has the bare minimum necessary to get a fully functioning common-canvas to appear including all the basic functionality, a palette and a flow of nodes and links.
  • The second, called app-small.js, shows many of the options available to a common-canvas developer such as configurations and callback handlers.

You can also look at the App.js file in the test harness section of this repo to see examples of code that uses the common canvas component.

Now let's walk through the different steps to get common-canvas working:

Step 1 : Install Elyra Canvas NPM module

Enter:

     npm install @elyra/canvas 

Step 2 : Import Common-canvas

To use common canvas in your react application you need to do the following. First import the CommonCanvas react component and CanvasController class from the Elyra Canvas library. Elyra Canvas produces both esm and cjs outputs. By default esm will be used when webpack is used to build the consuming application.

All Components

    import { CommonCanvas, CanvasController } from "@elyra/canvas";

Canvas only

To import only canvas functionality in cjs format use:

    import { CommonCanvas, CanvasController } from "@elyra/canvas/dist/lib/canvas";

In addition you'll need to import <IntlProvider> from the react-intl library.

    import { IntlProvider } from "react-intl";

Step 3 : Create an instance of the canvas controller

To control the canvas you'll need an instance of the canvas controller so create an instance of it like this (probably in the constructor of your object).

    this.canvasController = new CanvasController();

Step 4 : Set the palette data

Next you'll need to populate the palette data. This will specify the nodes (split into categories) that will appear in the palette. The user can drag them from the palette to build their flow. This is done by calling CanvasController with:

    this.canvasController.setPipelineFlowPalette(pipelineFlowPalette);

The pipelineFlowPalette object should conform to the JSON schema found here:
https://github.com/elyra-ai/pipeline-schemas/tree/master/common-canvas/palette

Some examples of palette JSON files can be found here:
https://github.com/elyra-ai/canvas/tree/master/canvas_modules/harness/test_resources/palettes

Step 5 : (Optional) Set the flow data

This is an optional step. If you want a previously saved flow to be shown in the canvas editor so the user can start to edit it, you will need to call the CanvasController with:

    this.canvasController.setPipelineFlow(pipelineFlow);

The pipelineFlow object should conform to the JSON schema found here:
https://github.com/elyra-ai/pipeline-schemas/tree/master/common-pipeline/pipeline-flow

Some examples of pipeline flow JSON files can be found here:
https://github.com/elyra-ai/canvas/tree/master/canvas_modules/harness/test_resources/diagrams

Step 6 : Pull in the CSS

Check this section to find info on what CSS to include in your application's CSS.
https://github.com/elyra-ai/canvas/wiki/5.0-Styling

Step 7 : Display the canvas

Finally you'll need to display the canvas object inside an <IntlProvider> object. Inside your render code, add the following:

    <div>
        <IntlProvider>
            <CommonCanvas canvasController={this.canvasController} />
        </IntlProvider>
    </div>

The div should have the dimensions you want for your canvas to display in your page. For the canvasController property, pass the instance of canvas controller you created earlier. This is the only mandatory property. After providing this and running your code you will have a fully functioning canvas including: a palette; default toolbar; context menus; direct manipulation (move and resize) etc. To customize these behaviors and presentation continue with the sections below.

Common Canvas customization

If you want to customize the behavior of common canvas you can specify any combination of the following optional settings:

    <div>
        <CommonCanvas
            canvasController={this.canvasController}

            config={this.commonCanvasConfig}
            toolbarConfig={this.toolbarConfig}
            notificationConfig={this.notificationConfig}
            contextMenuConfig={this.contextMenuConfig}
            keyboardConfig={this.keyboardConfig}

            contextMenuHandler={this.contextMenuHandler}
            beforeEditActionHandler={this.beforeEditActionHandler}
            editActionHandler={this.editActionHandler}    
            clickActionHandler={this.clickActionHandler}   
            decorationActionHandler={this.decorationActionHandler}
            layoutHandler={this.layoutHandler}  
            tipHandler={this.tipHandler}
            idGeneratorHandler={this.idGeneratorHandler}
            selectionChangeHandler={this.selectionChangeHandler}
            actionLabelHandler={this.actionLabelHandler}

            showRightFlyout={showRightFlyout}
            rightFlyoutContent={rightFlyoutContent}

            showBottomPanel={showBottomPanel}
            bottomPanelContent={bottomPanelContent}
        >
        </CommonCanvas>
    </div>

Config objects

Common canvas has five optional configuration objects: config, toolbarConfig, notificationConfig, contextMenuConfig and keyboardConfig. They are documented here: https://github.com/elyra-ai/canvas/wiki/2.1-Config-Objects

Handlers

There are several optional handlers implemented as callback functions. They are contextMenuHandler, editActionHandler, beforeEditActionHandler, clickActionHandler, decorationActionHandler, layoutHandler, tipHandler, idGeneratorHandler, selectionChangeHandler and actionLabelHandler. They are documented here: https://github.com/elyra-ai/canvas/wiki/2.2-Common-Canvas-callbacks

Right-flyout panel parameters

There are two optional parameters to let you manage the right flyout panel which can be used to display properties for objects etc. These are:

  • showRightFlyout: This can be true or false to indicate whether the flyout panel is shown or not. The default is false.
  • rightFlyoutContent: content to display in the right flyout which is a JSX object. Nothing is displayed by default.

Bottom panel parameters

The bottom panel appears below the canvas area and between the palette and the right flyout panel. You can add whatever content you like to this panel. There are two optional parameters to let you manage the bottom panel. These are:

  • showBottomPanel: This can be true or false to indicate whether the bottom panel is shown or not. The default is false.
  • bottomPanelContent: content to display in the bottom panl which is a JSX object. Nothing is displayed by default.

Localization

You can customize <CommonCanvas> using the <IntlProvider> object to display translated test

Creating nodes on the canvas

Nodes can be created on the canvas by the user in two ways:

  • By dragging a node from the palette onto the canvas background
  • By dragging a node from outside the canvas

The first technique is provided by Common canvas. The second requires some development work which is documented here: https://github.com/elyra-ai/canvas/wiki/2.3-Enabling-node-creation-from-external-object

Keyboard support

Common canvas supports a number of keyboard interactions as follows:

Key Action Description
Ctrl/Cmnd + a selectAll Select All objects
delete deleteSelectedObjects Delete currently selected objects
Ctrl/Cmnd + x cut Cut selected objects to the clipboard
Ctrl/Cmnd + c copy Copy selected objects to the clipboard
Ctrl/Cmnd + v paste Paste objects from the clipboard
Ctrl/Cmnd + z undo Undo last command
Ctrl/Cmnd + Shift + z redo Redo last undone command
Ctrl/Cmnd + y redo Redo last undone command

Your application can disable any or all of these actions by providing the keyboard config object to the CommonCanvas react component.

When any of the shortcut keys are pressed the common-canvas object model will be updated and then the editActionHandler callback will be called with the data.editType parameter set to the action above and the data.editSource parameter set to "keyboard".

⚠️ **GitHub.com Fallback** ⚠️