Common Canvas displays a flow of data operations as nodes and links (edges) which the user can create and edit to get the flow they want. These visual flows of data operations are typically translated into data processing steps performed by the application. Common Canvas provides UI functionality for the visual display of flows in the browser and leaves persistence and execution of data flows to the application.
-
The common-canvas user can perform operations such as:
-
-
Create a new node by dragging a node template from a palette onto the canvas.
-
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.
-
Create a new node by dragging a node from the OS desktop (or elsewhere on the browser page) onto the canvas. This takes a little bit of development work.
Common Properties allows the application to display a Carbon compliant properties panel or dialog with just a Javascript (JSON) object as input. Common Properties supports the most commonly used UI components and also allows custom components to be added into its visual output.
The Flow Editor displays the flow to the user and allows the user to interact with the flow using the mouse/trackpad and the keyboard and other input devices. Typically, the flow shows a set of nodes connected by links (edges) that represent some flow of data, or flow of control, which is in the problem domain of the application.
-
-
The editor displays the following object types which the user can interact with:
The defintions of objects displayed within the flow editor are contained in a JavaScript object descibed by the pipeline flow schema. A pipeline flow object can be serialized to, or parsed from, JSON and consequently saved to, or read from, a file.
-
The storage and mangement of pipeline flow files is handled by the application. The pipeline flow can be read from the canvas controller:
-
constpflow=canvasController.getPipelineFlow();
-
-and a previously saved pipeline flow can be provided to Common Canvas also using the canvas controller:
-
canvasController.setPipelineFlow(pFlow);
-
-
A pipeline flow contains an array of pipelines, one of which is the ‘primary pipeline’. Other pipelines will be sub-flows for supernodes contained within the primary pipeline (or other pipelines).
-
Each pipeline defines sets of nodes, links and comments with all their associated attributes.
Nodes can be created by dragging from the palette and dropping onto the flow editor canvas:
-
-
Nodes can also be automatically added to the flow editor canvas by double clicking them in the palette. The node will be added at an appropriate place on the canvas and connected to the preceding node if one is available:
Objects (nodes, links and comments) on the flow editor canvas can be selected by single clicking on them. Subsequently, if the user Command/Ctrl + clicks on another object it will be:
-
-
Added to the set of selected objects if it is not currently selected or
-
Removed from the set of selected objects if it is currently selected.
-
-
Clicking on the flow editor canvas background will deselect all canvas objects.
-
A selection region can be pulled out to select multiple objects at once by pressing the Shift key and dragging on the canvas background.
-
-
A set of connected nodes through a flow can be selected by, clicking on a node to select it and then, Shift + click another downstream node. If the nodes are joined together through a set of inter-connected nodes, all of those nodes will be selected.
-
-
All canvas objects can be selected by displaying the default context menu or context toolbar for the flow-editor background and then clicking the ‘Select All’ option. Note: If the application provides its own canvas menus then it would need to add the selectAllinternal action to the menu to enable the ‘select all’ function.
-
Alternatively, the user can press Ctrl/Command + akeyborad shortcut to select all objects when the keyboard focus is on the canvas.
The Flow Editor allows direct manipulation of selected objects by dragging them to a new position.
-
-
Flow editor canvas context menu or context toolbar¶
-
The flow editor can display a context menu or context toolbar (depending on which is enabled) that can show options for the whole flow. It is displayed by the context menu gesture which is either right-clicking the mouse, or the trackpad equivalent, while the mouse cursor is over the canvas.
The objects on the flow-editor canvas can be zoomed in and out either using the zoomIn or zoomOut toolbar buttons or by performing the zoom gesture using the mouse or trackpad. The canvas background can be panned by dragging the background.
-
-
A large flow can be centrally positioned, making all the nodes visible within the viewport, by clicking the zoomToFit button.
Command actions that update the objects within the flow editor are added to the command stack and can be undone and then redone. The default toolbar has undo and redo buttons and the default context menu/toolbar for the canvas background has undo and redo options. There are also keyboard shortcuts to undo and redo.
Users can cut and copy one or more objects from the canvas onto the clipboard and paste them into the same flow or a different flow. The default canvas toolbar provides buttons for these three actions and they can also be accessed through the default context menus/toolbars for the objects on the canvas.
-
There are also keyboard shortcuts to cut, copy and paste.
Nodes displayed in the flow editor can represent data operations or other types of
-operations for the type of flow the application displays. Nodes are joined together in a flow by data links (edges). Association links can also join two nodes together (in a non-directional relationship) and nodes can be connected to comments with a comment link.
-
Nodes can be customized into a large number of different layouts depending on the needs of the application, as shown below:
Node objects are stored in the nodes array in a pipeline which itself is in the pipelines array of the pipeline flow. The node object in the pipeline holds some basic information used for node display such as:
-
-
id - unique identifier
-
position - x/y position relative to the canvas origin
-
label
-
description – displayed in the node tooltip (if enabled)
-
image – image location on the server or a JSX object
-
ports info (inputs and outputs)
-
optional decoration information
-
-
Additional information on the node layout is configured in the node layout fields.
Nodes are made up of a number of display elements:
-
-
In addition, the node might have an ellipsis icon if context menus are enabled and one or more decorations. All of the node elements are optional, except the selection highlighting element.
The enableNodeFormatType field of the canvas config object can be used to change the basic format of the node between “Horizontal” and “Vertical” format:
-
-
Each format type has its own set of node layout fields which can be overriden by the application for further customization.
The node image is specified in the image field of the node object in the pipeline flow and the palette. It can either be a URL to an image file on the server or a JSX object.
-
Here’s an example of a node using an image field with a URL that specifies an SVG object imported from a file on the server:
-
-
Here’s an example of a node using a JSX object which is an icon imported from the Carbon icons library.
Nodes are positioned at the x/y coordinate from the canvas origin of the node’s top-left corner. The x/y coordinates are stored in the node object from the pipeline flow.
A node can have zero or more input ports and zero or more output ports.
-
-
Input ports are the objects to which connections are made from other nodes that indicate a flow of data or control into the node.
-
Output ports are the objects from which connections are made to other nodes that indicate a flow of data or control out of the node.
-
-
In many applications, nodes have just a single input and/or output port. There is no strict definition of why a node might have multiple input ports or multiple output ports. Often they are used to indicate a different kind of data flowing into or out of the node. For example, a relational-database Join node might have two input ports one for the left table data and one for the right table data in the join. Or a filter node might take data and split it into two parts based on some criteria and write out the different data to separate output nodes, like this:
-
-
There can be multiple connections made into an input port or out of an output port. Each port has a maximum and minimum cardinality values which indicate the limits on the number of connections for the port. Common Canvas ensures the maximum cardinality is not exceeded for port connections.
-
Ports can be shown visually on, or close to, the node as circles or images. This positioning is controlled by the node layout fields.
A guide is an image or shape drawn at the location of an output port. The user can drag the ‘guide’ to another node to create a new link connection to that node. The appearance of the guide can be customized by altering the node layout fields and CSS for the node. If output ports are visible, it appears as if the user is dragging the port but the guide is, in fact, a different node element.
Nodes can be resized if the enableResizeableNodes canvas config field is set to true. The node can be resized if the user drags the border area in the desired direction.
A Node can be highlighted when a guide icon is being dragged towards it and a connection is allowed, if enableHighlightNodeOnNewLinkDrag canvas config field is set to true.
The body of nodes can be drawn using a React object in place of the SVG elements usually displayed by Common Canvas. The React object is specified by the application in the nodeExternalObj field in the node layout fields.
-
Here is an example of two nodes using the CardNode React object from the Carbon Charts (React) library.
Branch highlighting allows the user to highlight upstream nodes, downstream nodes or the entire branch of nodes (both upstream and downstream) by choosing one of the ‘Highlight’ options from the context menu for a particular node.
-
Clicking this:
-
-
Results in this:
-
-
Common Canvas add a class called ‘d3-branch-highlight’ to the group <g> object of the node or the link in the branch. The application can use that class to specify its own CSS styling for the branch highlighting.
-
By default, Common Canvas provides colors and styles for the highlighted branch nodes and links, but the application can override them if desired using CSS like this.
A supernode is a special kind of node that can reference another pipeline in the same pipeline flow object (internal) or, in some cases, in another pipeline flow (external). The referenced pipeline is known as a sub-flow or sub-pipeline.
-
These types of supernodes/sub-flows combinations have different uses:
-
-
Internal sub-flows are useful for organizing flows by separating out closely related sets of nodes from the main flow.
-
External sub-flows are useful for function reuse. That is, if a set of nodes performs some function that is needed by more than one pipeline flow, they would be placed into their own pipeline flow and referenced by the others.
-
-
-
Common Canvas allows the user to create a supernode by selecting a set of nodes to be placed in the sub-flow:
-
-
And then to view it as expanded ‘in-place:
-
-
The user can also navigate to a ‘full-page’ view (well, really it is a full-viewport view):
-
-
The sub-flow can be edited by the user, after it has been created, by adding, removing or editing its nodes, comments and links.
-
Supernodes can also be:
-
-
Deconstructed – that is, the supernode is remove from the flow and the nodes from the sub-flow are inserted back into the parent flow.
-
Converted from internal to external - this means the sub-flow is removed from its current pipeline flow and placed in a separate pipeline flow object that can be saved by the application.
-
Converted from an external to internal - this means the sub-flow is copied from the external pipeline flow and placed into the pipeline flow of the supernode.
Common Canvas will display one link line on the canvas for each link defined in the pipeline flow. There are three categories of links supported by Common Canvas:
-
-
Data links - a directional link between the ports on two nodes
-
Association links - a relationsjip link between two nodes with no implied direction
-
Comment links - a link from a comment to a node
-
-
The appearance and behavior of links can be customized by:
Data links are designed to model a flow from a source node to a target node. Data links are specified in the pipeline flow to connect a port on the source node to a port on the target node. Data links are typically displayed with an arrow head to display the flow along the link from source to target.
-
There are 4 types of data link:
-
-
Curve
-
Elbow
-
Parallax
-
Straight
-
-
These can be changed by specifying the enableLinkType configuration field.
-
Also, data links can be drawn either:
-
-
between ports on the source and target nodes or
-
“freeform” which means the link is drawn from and to the source node ignoring port positions. Typically with “freeform” links the application customizes the canvas to NOT display ports.
-
-
This choice can be changed by specifying the enableLinkMethod configuration field.
The enableLinkMethod config field can be set to “Freeform”. With this option, links are drawn directly between nodes without any reference to ports.
-
Here is an example of a “Freeform” link with a “Straight link type:
-
-
The “Freeform” display is useful for flows where no particular direction of the flow needs to be enforced and also where the flow has nodes with multiple ports but the ports do not need to be shown in any particular order or context.
-
When more than one link enters or exits into/from one side of the node the freeform links will be drawn to maintain some reasonable separation like this:
When enableLinkMethod is set to “Ports”, Common Canvas draws the links to maintain the flow from output ports to input ports regardless of where the nodes are positioned relative to one another.
-
Here is an example of the “Ports” links method with a “Curve” link type:
-
-
Links between ports can be useful if the application wants to allow the user to create loops in the flow, like this:
If the enableSelfRefLinks canvas config field is set to true, the user can create links that loop back to the node they originated from. These are created by the user dragging from the output port on the node and dropping the new link onto a input port, or the body, of the same node.
-
Here’s an example of a self-referencing link using a “Freeform” link method with an “Elbow” link type.
-
-
Self-referencing links behave the same as other links and can be displayed in the same combinations of link types (Curve, Elbow, Parallax and Straight) and link methods (Freeform or Ports) as other links.
Note: Typically data links must be drawn between nodes however, if the config field enableLinkSelection is set to Detachable, the links are allowed to be drawn to and/or from arbitrary points on the canvas.
-
With this option, the start and end of existing links can be dragged away from the nodes they are connected to and dropped onto an arbitrary point on the canvas to create a ‘detached’ link. Additionally, the end of any detached link that originates from, or points to, a point on the canvas can be dragged to a node to form a connection. Also, nodes can be dragged to the available ends of those ‘detached’ links to form a connection.
Association links are designed to capture a relationship between two nodes where there is no implied direction. By default these are displayed as a single straight link line in a dashed style. There are no arrow heads by default for that type of link.
Comment links connect a comment to one or more nodes. They can be created by the user by: (a) pulling out the small handle/circle that appears below a comment and dropping it on a node. (2) by selecting nodes before the comment is selected and then creating the comment. This will automatically create a comment link from the selected nodes to the newly created comment.
Comments can be created by the user by clicking the ‘Create Comment’ button in the default toolbar or by clicking the ‘Create comment’ option in the default canvas background context menu/toolbar.
-
Note: If the application is providing its own toolbar it would need to have a button defined with the createAutoCommentinternal action and, in the context menu/toolbar for the canvas background there would need to be an option defined with the createCommentinternal action.
The comment can be changed to ‘edit mode’ by either double clicking it or clicking the ‘Edit Comment’ option in the default context menu/toolbar. If the application is providing its own context menu/toolbar it would need to provide an option with the setCommentEditingMode action defined.
-
-
-
-
Doing this:
-
Yields this:
-
-
-
-
-
-
-
-
-
-
After text has been entered into the comment entry area the user can click on the canvas background to finish editing and display the comment.
Comment backgrounds can be colored by clicking the ‘Change Color’ option in the default context menu/toolbar for the comment. If the application provides its own context menu/toolbar then the colorSelectedObjects action must be defined.
Optionally, the application can switch on markdown support within comments. This allows the user to enter markdown syntax when the comment is in edit mode, which is then formated approriately in display mode.
As well as markdown syntax, the user can also enter HTML into the markdown text. This is then run when the comment is presented in display mode. HTML support allows the user more extensive customization capabilities including the specification of CSS for the text.
-
For example, specifying this will color the word Red:
-
Some <span style="color: red">Red</span> text
-
-Here’s an example comment with some sample HTML:
-
In Common Canvas, nodes and links can be enhanced with decorations. A decoration is either:
-
-
-
An image
-
-
-
-
-
A label
-
-
-
-
-
A shape (SVG path) or
-
-
-
-
-
A JSX object
-
-
-
-
-
Decorations can be applied to a node or link in a number of ways and can be made interactable so when the user clicks on the decoration the decorationActionHandler is called.
-
Here are some node decorations displayed by IBM’s SPSS Modeler application:
-
-
Here are some link decorations displayed by IBM’s Data Stage application:
-
-
Note: The link labels and the small icons on the links are decorations as well as the circle at the source of each link.
Common Canvas can display a palette which appears in the left flyout panel. The palette can display a set of palette nodes (sometimes called node templates) split into different categories.
-
-
The user can drag any of the palette nodes from the palette onto the canvas to create a new instance of a node on the canvas. The user can then join nodes together by creating link lines.
-
-
Alternatively, the user can double click node templates to add, and automatically join, them to the current flow. When a palette node is double clicked, Common Canvas will look for the node at the end of the current flow of nodes and will add the node to the canvas to the right of the end node in the flow. Common Canvas will also automatically join the nodes together by creating a new link line.
The host application must tell Common Canvas what node templates and categories it wants the user to see in the palette. This is done by providing Common Canvas with a palette (JavaScript) object by calling the canvas-controller setPipelineFlowPalette(palette) method. The palette object is often read from a JSON document stored in the host application’s repository or it can be automatically generated.
-
The palette object should conform to the palette schema. The host application can ensure that palette conforms to the schema by switching on schema validation in the canvas configuration.
The user can enter a search string into the Search field at the top of the palette. The behavior is as follows:
-
-
When the search field is empty, the palette shows categories which can be expanded to show the node templates within the expanded category.
-
As the user enters characters into the search field, Common Canvas immediately searches through the node template labels, node template descriptions and category labels for the characters entered and finds a subset of the node templates that match the search string. Common Canvas then replaces the category-based view of the palette with a list of node templates that match the search criteria. In this view the node templates also include the node description under the node label.
-
The search is case insensitive.
-
The search text is highlighted wherever it appears in the labels, descriptions or category labels.
-
Common Canvas uses a ranking algorithm to order the display of node templates so those most relevant to the search text are positioned at the top of the list. The ranking algorithm puts more weight on those node templates where the search text appears in the label than if the text appears in the description or the category label.
-
If the user enters words into the search field (separated by spaces), Common Canvas searches for each word separately. Therefore, if say the user entered “data import” into the search field, Common Canvas would find a node with “ImportData” as the label or even a node with a description that said “This node does lots of things and also data can be imported.”
-
Nodes that have text which have hits on multiple words are ranked more highly than node templates whose text only contains one search word.
-
Common Canvas uses a debounce function so that, if the user types the search string very quickly, Common Canvas does not perform multiple searches for each key press but only runs a full search when rapid typing has ended.
According to the schema, node template descriptions are not mandatory in the palette object. However, it is recommended you provide descriptions for each of your node templates. The reason for this is that, the search function searches through node template descriptions, as well as node template labels and category labels. This means you can write your node template descriptions to contain appropriate keywords that a user might search for when looking for a node.
-
For example, if there is a node template called ‘Import Data’ and that node could import comma-separated files you could add ‘comma-separated’ and ‘csv’ into your description for that node template. If the user entered comma in the search field the ‘Import Data’ node template would be shown in the search results even though comma does not appear in the node template label.
A context menu is a small window containing a list of options applicable to an object or set of selected objects.
-
A traditional context menu, like the one shown below, will be displayed when enableContextToolbar is set to false (or omitted) from the canvas config, and either:
-
-
a right-click (or equivalent on a trackpad) is performed on a canvas object or the canvas background or
-
Control + click is done on an obejct or
-
the ellipsis icon (only shown for nodes) is clicked
By default, Common Canvas will display appropriate context toolmenus for all flow editor canvas objects. The application can override or replace the default menus by implementing the contextMenuHandler callback.
Context toolbars are an alternative to traditional context menus. It can be enabled by setting enableContextToolbar to truein the canvas config.
-
A context toolbar is a small toolbar that appears above nodes, links and comments as the mouse cursor is hovered over them. A context toolbar for the canvas background can also be displayed by right-clicking on the canvas background.
-
The context toolbar displays a set of icons that represent the most likely actions the user would want to perform on the object under the mouse cursor. If necessary, the toolbar can also show an overflow (vertical ellipsis) icon that, when clicked, reveals additional actions that can be performed on the object.
-
For a “vertical” style node the context toolbar looks like this:
-
-
For a “horizontal” style node it looks like this:
-
-
when the user clicks the overflow icon it looks like this:
-
-
Note: Since the mouse cursor can be hovered over a node, comment or link that is NOT currently selected, the actions shown in the context toolbar will apply to just that object, even if there is one or more currently selected objects.
-
If the mouse cursor is hovered over a selected object when there are other selected objects, the actions in the context toolbar will be applicable to all the selected objects. This is the same as how a traditional content menu shows actions that are applicable to the set of selected objects.
By default, Common Canvas will display appropriate context toolbars for all flow editor canvas objects. The application can override or replace the default toolbars by implementing the contextMenuHandler callback.
The canvas toolbar appears at the top of the <div> occupied by Common Canvas. By default, the toolbar will be displayed with appropriate buttons to perform the most popular actions. The toolbar can be customized by the application to show whatever action buttons are required. Buttons can be positioned to the left or right of the toolbar area.
-
-
The toolbar is customized by providing a toolbar config object as one of the <CommonCanvas> props.
JSX can be provided to add additional information into the toolbar. In this case, the Autosaved time is added amongst the regular toolbar action buttons.
The Notification Panel allows the application to display error, warning, success and info messages to the user.
-
-
The canvas toolbar provides a button to display a sub-panel that contains the notifications. The button will be added to the far right side of the toolbar whenever a Notification Config is specified to the <CommonCanvas> React object.
-
The notifications button in the toolbar indicates the state and number of the messages in the panel.
-
A colored circle will be shown to indicate the highest severity message to be shown in the notification panel: info/blue, success/green, warning/yellow or error/red. Also, a number is displayed within the icon to indicate the number of current messages.
A State Tag is an optional pill-shaped object that can displays the state of the flow to the user. This can be either ‘Locked’ or ‘Read-only’. By default, no state tag is shown.
-
The application can request a state tag be shown by setting the enableStateTag canvas config field.
-
When the State Tag is display it will show a tooltip, with an appropriate message, if the mouse cursor is hovered over it. The application can override the default message by implementing the Tip Handler callback.
-
-
-
Note
-
It is the application’s reponsibility for making the flow read-only. See the Read Only or Locked Flows page for more details.
The application can switch tooltips on and off as required for the different types of object and can also customize what text is displayed in the tooltip.
By default, Common Canvas will display tooltips where appropriate. Tooltips can be switched on or off, for evertything except the toolbar, by specifying the tipConfig field for the canvas config object.
Common Canvas has three additional optional panels: top panel, bottom panel, right-flyout. These can be used by the application to display any additional content to the user such as logs or data previews or properties of selected objects. Traditionally, the right-flyout is used to display node properties.
-
The application can, optionally, use Common Properties to display the controls for the properties of a node.
Common Properties is a React component that allows the application to display a set of UI components (radio buttons, text entry areas, drop down lists, sliders, tables, etc) to present the properties of a node to the user. Common Properties supports the most commonly used UI components and also allows custom components to be added into its visual output.
-
The Common Properties React object has a ‘prop’ called the Parameter Definition which is a Javascript (JSON) object and some configuration objects as props.
-
Traditionally, the right-flyout is used to display properties but the application can choose to display them elsewhere. The UI elements displayed by Common Properties comply with the Carbon design language.
-
For more details and examples of the components supported by Common Properties, see the Common Properties Components page.
-
Here’s an example of the type of output a <CommonProperties> React object can produce. This is from the IBM SPSS Modeler application:
You’ll need to build your application with Elyra Canvas.
-
-
Elyra Canvas requires react, react-dom, react-intl, and react-redux libraries to be installed. See peerDependencies in package.json for versions requirements.
If you want to see text displayed by Elyra Canvas components in different languages you must wrapper <CommonCanvas> and <CommonProperties>in an <IntlProvider> object.
-
The sample code below shows how <IntlProvider> should be imported and initialized. Your code can set this.locale to indicate which language should override the default which, in this sample code, is set to English en. The default locale will be used if this.locale is set to a language which is not currently supported.
-
If you want to provide translations for your own application’s text you can import your own bundles and load them into the this.messages object along with the common-canvas and common-properties text. If you do this you will have to move <IntlProvider/> so that it wrappers your React objects as well as <CommonCanvas/> and/or <CommonProperties>.
-
import{IntlProvider}from"react-intl";
-
-importCommandActionsBundlesfrom"@elyra/canvas/locales/command-actions/locales";
-importCommonCanvasBundlesfrom"@elyra/canvas/locales/common-canvas/locales";
-importCommonPropsBundlesfrom"@elyra/canvas/locales/common-properties/locales";
-importPaletteBundlesfrom"@elyra/canvas/locales/palette/locales";
-importToolbarBundlesfrom"@elyra/canvas/locales/toolbar/locales";
-
-classAppextendsReact.Component{
-
-constructor(){
-this.locale="en";
-// Create messages object once (here in constructor) - do not create messages
-// in the render method, otherwise unnecessary renders inside
-// common-canvas/common-properties will be performed.
-this.messages=this._getMessages(
-this.locale,
-[CommandActionsBundles,CommonCanvasBundles,CommonPropsBundles,
-PaletteBundles,ToolbarBundles]
-);
-}
-
-_getMessages(locale,bundles){
-constmessages={};
-for(constbundleofbundles){
-Object.assign(messages,bundle[locale]);
-}
-returnmessages;
-}
-
-render(){
-<IntlProviderlocale={this.locale}defaultLocale="en"messages={this.messages}>
-{Addyour<CommonCanvas/>or<CommonProperties/>elementhere.}
-</IntlProvider>
-}
-
To get correct and efficient display of fonts in Elyra Canvas, the build process for your application should copy the IBM Plex font files from /node_modules/@ibm/plexto a ./fonts folder and the following should be added to the .scss file for your application:
-
@use "@carbon/react" as * with (
- $font-path: "/fonts"
-);
-
-$font-prefix: './fonts';
-@import 'node_modules/@ibm/plex/scss/ibm-plex.scss';
-
-
You can see an example of this in the common.scss file for the Elyra Canvas Test Harness. The Test Harness is the equivalent of a host application.
-
The Gruntfile that builds the Test Harness contains the following, that ensures the fonts are copied from /node_modules/@ibm/plex to the <carbon fonts folder>:
-
Common Canvas is a React component. The <CommonCanvas> component is displayed in a <div> provided by your application. Here’s some sample code to show the minimum code needed to get a working canvas.
The “Tiny App” is available as part of the test harness function. Click here to see the app running. You can try: dragging a node, editing a comment (double click on it), drag a node from the palette, click a button on the toolbar, zoom in and out using the scroll gesture.
This app app-small.js, is more sophisticated and 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.
The only mandatory prop for the <CommonCanvas> component is a regular JavaScript class called the Canvas Controller.
-
The Canvas Controller handles calls from the host application and actions performed by the user. It then updates the internal object model which stores:
-
-
The data that describes the flow of nodes, links and comments (called a pipelineFlow);
-
The data that describes the definition of the palette which contains node templates that can dragged to add nodes to the canvas;
-
The set of currently selected objects.
-
Notification messages
-
Breadcrumbs that indicate which sub-flow is being viewed
-
Layout information
-
And more …
-
-
The Canvas Controller provides an API which allows the application to:
-
-
Set a new Pipeline Flow
-
Get the current pipelineFlow (after the user has edited it)
-
Update and edit objects in the canvas (for example, add node, delete link etc.)
-
Set the node definition data (for display of nodes in the palette)
-
Operate other aspets of the UI like opening panels, zooming, etc, etc.
Import the Common Canvas and Canvas Controller 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 application.
This is an optional step. If you want a previously saved flow to be shown in the flow editor, so the user can start to edit it, you will need to call the canvas controller with:
-The <div> should have the dimensions you want for your canvas to display in your page. For the canvasController prop, pass the instance of canvas controller 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.
-
See the Localization section of the Initial Setup page to see how <IntlProvider> can be configured.
The right flyout panel appears on the right of the canvas area. You can add whatever content you like to this panel. Typically, it is used to display properties of nodes on the canvas. There are two optional parameters to let you manage the right flyout panel 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.
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 panel which is a JSX object. Nothing is displayed by default.
The top panel appears below the toolbar 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 top panel. These are:
-
-
showTopPanel: This can be true or false to indicate whether the top panel is shown or not. The default is false.
-
topPanelContent: content to display in the top panel which is a JSX object. Nothing is displayed by default.
The canvas config object is optional. If it is not provided, or any of the properties within it are not provided, Common Canvas will use reasonable defaults. Here’s an example of a canvas config object:
-
This can be “Horizontal” or “Vertical”. “Horizontal” is the default. “Horizontal” will display a node with an image and the label to the right of the image. “Vertical” will display the node with the label underneath the image. See the node customization section for details on what this will do.
This is a simple Javascript object, the properties of which override the default node layout properties. For more details see the node customization section.
This is a boolean. The default is false. If set to true, the user can resize nodes by dragging the edges of the node to increase or decrease the width and/or height of the node. When hovering the mouse cursor over the edge of the node the user will see a sizing cursor to indicate the resize function is available. This option works best when the node has a background rectangle that shows the extent of the sizing area.
This is a boolean. The default is false. If set to true, the user is allowed to create a link that points to the node the link originated from: a loop-back link. This is created by the user by dragging from the output port on the node and dropping the new link onto the same node.
This can be “LeftRight”, “RightLeft”, “TopBottom”, or “BottomTop”. “LeftRight” is the default. This alters the default location for input and output ports on the node, as follows:
-
-
For “LeftRight” input ports will be on the left of the node and output ports will be on the right of the node
-
For “RightLeft” input ports will be on the right of the node and output ports will be on the left of the node
-
For “TopBottom” input ports will be on the top of the node and output ports will be on the bottom of the node
-
For “BottomTop” input ports will be on the bottom of the node and output ports will be on the top of the node
-
-
In addition to these positions, the port positions can be further customized using the nodeLayout options.
This is a boolean. The default is false. If set to true, the user can drag nodes from the palette or from the canvas and drop them onto existing links in the flow. This causes the dropped node to be inserted between the two nodes joined by the link, meaning new links are created that join the new node to the previously joined nodes and the old link is removed. When the user performs the drop Common Canvas will call the editActionHandler with one of two possible commands:
-
-
“createNodeOnLink” - when a node is being dragged from the palette leading to node creation & insertion
-
“insertNodeIntoLink” - when an existing node is dragged from the canvas leading to insertion of the existing node into the link
This can be a boolean or an object. The default is false. If set to true, when the right-side flyout is open the currently selected node (assuming there is one) will be automatically positioned in the center of the viewport (canvas area). Instead of true this field can also be set to a simple JavaScript object like this { x: 30, y: 40 } where x and y indicate the position where the node will be positioned as a percentage of the width and height of the viewport respectively.
This is a boolean. The default is false. If set to true Common Canvas will add the “data-new-link-over” attribute to the node’s group <g> element, when the end of a new link is dragged to be close to and over a target node. This allows applications to alter the appearance of the target node as a new link is dragged towards it.
This is a boolean. The default is false. If set to true, when the user begins to drag a new link line, Common Canvas will add a new class called d3-node-unavailable to all nodes which cannot accept the link as input. The class will be applied to each node’s group <g> element in the DOM. This class can be used for styling the unavailable nodes as desired using CSS. The default styling will ‘gray out’ the node label, node outline rectangle (if there is one) and the node icon (provided it is an SVG image). These styles can be overridden in the applications CSS if different styling is needed. This behavior also applies if the end of a partially or fully detached link is dragged.
This is a boolean. The default is true. If set to false the nodes will be left in their original place in the DOM. If set to true, when the user moves the mouse cursor over a node, that node will be moved in the DOM so that the node appears on top of all other nodes. This is only really noticeable if nodes, or parts of nodes, overlap other nodes. It can be useful if your nodes have protruding ports or decorations and your users sometimes position nodes very close to one another. Note: the ‘true’ setting can adversely affect the behavior of scroll areas in a node that are displayed using a React object (using the nodeExternalObject node layout option) because when the node is moved in the DOM the scroll area gets reset to its initial position. Set this to false if you are displaying nodes using React objects.
This is a boolean. The default is true. If true, nodes surrounding a supernode will be moved when the supernode is expanded or manually resized so that the supernode does not overlay them. When set to false, the nodes surrounding a supernode will stay in their current positions when the supernode is expanded or manually resized. This may result in the nodes being overlaid by the supernode.
This is a boolean. The default is false. If set to true, any abbreviated node label will be displayed in full when the pointer hovers over the label. If set to false, abbreviated node labels will remain the same when the pointer hovers over them.
This is a boolean. The default is false. If set to true, only the last of the ports from the array of output ports will be displayed for each node. This config property is only applicable to applications with very specialized styling and handling of ports. If set to true with regular applications, it may result in a confusing display to the user. The single port is displayed at a position specified by outputPortRightPosX and outputPortRightPosY layout properties. For exmaple:
-
This can be: “Ports” or “Freeform”. The default is “Ports”. When set to “Ports”, each link will be drawn from a specific output port on the source node to a specific input port on the target node. Note: With this option, links will be drawn to the port locations even if the port display has been switched off by the application. When set to “Freeform” links will be drawn from the source node to the taget node ignoring where ports have been positioned. Applications displaying freeform links usually choose not to display input and output ports.
This is a boolean. The default is true. If set to true then, when enableLinkType is set to “Straight”, enableLinkMethod will always be treated as if it is set to “Freeform”. If it is set to false, Common Canvas will use whatever value is specified in enableLinkMethod when enableLinkType is set to “Straight”.
-
This config field was introduced to enforce the earlier Elyra Canvas behavior, where “Straight” links are automatically displayed as “Freeform”.
-
-
enableStraightLinksAsFreeform - deprecated
-
This field is deprecated and will be removed in the next major Elyra Canvas version so it is recommeneded that applications using “Straight” links explicitely set enableLinkMethod to “Freeform” now because that will be mandatory when migrating to the next verion.
This can be: “None”, “LinkOnly”, “Handles” or “Detachable”. The default is “None”. These have the following affect on the canvas:
-
-
“None” - no selection of links is possible however user can right click on a link to get a context menu.
-
“LinkOnly” - a link may be selected and added to the set of currently selected objects (nodes and/or comments).
-
“Handles” - This includes the “LinkOnly” function. In addition, when a link is selected a handle (either a circle or an image) is displayed at the start and end of the link. The link handle can be dragged to a new node/port position to rewire the flow.
-
-
“Detachable” - This includes the “LinkOnly” and “Handles” function. In addition, this option enables detachable links for the canvas. This means a link can exist either:
-
-
between a source node and an arbitrary point on the canvas (semi-detached) OR
-
between an arbitrary point on the canvas and a target node (semi-detached) OR
-
between two arbitrary points on the canvas (detached)
-
-
Additionally, “Detachable” mode, allows:
-
-
semi-detached or fully-detached links to be stored in and retrieved from the pipeline flow document.
-
semi-detached or fully-detached links to be manipulated with link handles. The link handles can be used to drag the end of the link away from its connecting source or target nodes and onto the canvas. Or semi-detached or fully detached links can be reattached to nodes/ports.
-
a new detached link to be created by drawing out a new link from a node and dropping it onto the canvas.
-
palette and canvas nodes, when they are dragged, to be dropped onto the ends of detached links to automatically attach them to the node being dragged.
This is a boolean. The default is false. If set to true, the user can drag a new connection to a target node, and if the input port on the target node has a maximum cardinality of one AND there is currently a connection to that port, the existing connection will be removed and the new connection is created; essentially this gesture replaces the existing link with the new one. If set to false the new connection will not be completed and the existing link will remain in place.
-
When set to true and a link is replaced, Common Canvas will call the beforeEditActionHandler the editActionHandler callback functions, if either are provided by the host application, with a data object parameter with the editType field set to "linkNodesAndReplace".
This is a Boolean. The default is false. If set to true it changes the nature of links that are created between nodes as follows:
-
-
The user is able to pull out a link from either port on the node and drag it to another node
-
When a link is completed an association link is created rather than the regular data flow link that is created when this field is set to true. Association links describe an association between pairs of nodes and do not indicate any kind of data flow between those nodes.
This is a boolean. The default value is false. If set to true links are placed above nodes in the canvas. Hover over nodes/links would still have links above nodes if enableLinksOverNodes is set to true. This is useful if the ports are positioned within the boundaries of the node and the link lines need to be displayed to those positions.
This is a boolean. The default is false. When set to true the user may enter markdown syntax into comments on the canvas when in edit mode for the comment. When the editing ends, the comment is shown in presentation mode and the markdown syntax is converted to HTML which is displayed in the comment and is styled by CSS.
This can be: “Top” or “None”. The default is “Top”. “Top” displays a toolbar at the top of the canvas area. See the Toolbar Config docs for details on how to customize the toolbar. “None” stops the toolbar from appearing.
This is a simple JavaScript object that configures whether tips for palette items, nodes, ports, links, decorations or the state tag are enabled (value set to true) or disabled (value set to false). By default, all tips are enabled. The following would switch off tips for ports and links.
-
-The tips displayed by the palette can be further refined. For example, this would prevent tips for palette categories from being displayed, but would still display tips for node templates in the categories:
-
This is a boolean. The default is false. When set to true, Common Canvas will display a context toolbar instead of a context menu for performing actions on canvas objects. A context toolbar is a small toolbar that appears above nodes, links and comments as the mouse cursor is hovered over them. The toolbar shows icons for actions the user is most likely to want to perform on the object. An overflow icon is displayed which, when clicked, shows a menu of additional actions. A context toolbar for the canvas background can also be displayed by right-clicking on the background. Common Canvas will display default context toolbars for nodes, links comments and the canvas background however, the default actions can be customized by implementing the Context Menu Handler` callback.
This can be: “Modal” or “Flyout” or “None”. The default is “Flyout”. “Flyout” displays a panel on the left side of the canvas containing the palette icons and “Modal” shows the palette icons in a dialog window. “None” stops the palette from appearing.
This is a boolean. The default is false. When set to true the auto-add function (where double clicking a node in the palette automatically adds it to the canvas) will only link up nodes when a node is already selected on the canvas and then, only if the selected node can be linked to the node that was double clicked. If false, the auto-add function will make a best guess at which node the double-clicked node should be added to.
This is a JSX object that will displayed in an open, wide palette. It is positioned below the Seach bar and above the categories and nodes. The default is null, which means nothing will be displayed. This option can be used by the application to add application specific function into the palette, for example, a button could be added.
This is a boolean. true is the default. If true when the palette is closed the narrow palette will be shown. When false the palette completely closes.
-
-
paletteInitialState - deprecated
-
Deprecated – This option is deprecated and will be removed soon. Use CanvasController.openPalette() to display an opened palette at start-up. This openPalette() can be called immediately after creating the canvas controller.
-
paletteInitialState is a boolean. false is the default. If set to true the palette will be opened when Common Canvas first appears to its full (non-narrow) state.
This can be: “None”, “LocalStorage” or “Pipelineflow”. The default is “None”.
-
-
“None” - When the canvas is zoomed, the zoom (scale and x/y pan) are not saved anywhere so if the canvas is closed and reopened it reopens with the default zoom which is a scale of 1 and x/y pan values of 0.
-
“LocalStorage” - The zoom for the canvas is stored in the browser’s local storage and will be reapplied to the canvas each time that canvas is shown in that browser. This applies to sub-flows, when the user displays them full-screen, as well as the primary flow. Sub-flows and the primary flow each have their own zoom amounts stored in local storage. Note: Zoom amounts stored in local storage can be cleared from storage by calling the canvasController.clearSavedZoomValues() API method.
-
“Pipelineflow” - The zoom is serialized into the pipeline flow document and when a pipeline flow document is provided to Common Canvas through the API the zoom will be applied to the canvas display. Zoom amounts can be stored for both primary and sub pipelines. (See the pipelineFlow schema specification).
This can be either true or false. The default is false. If set to true, the canvas will be panned so as much of the canvas area (the area containing the nodes and comments) is visible in the viewport as possible. This will only happen when enableSaveZoom === “None” or if there is no saved zoom available either in local storage (when enableSaveZoom === “LocalStorage”) or in the pipelineFlow (when enableSaveZoom === “Pipelineflow”).
This is a boolean. The default is false. When set to true, Common Canvas will override the maximum zoom extent value which, by default is used for the entire canvas, to allow the user to zoom in on in-place sub-flows further than they can do on containing flows. This means the user can zoom in on multi-nested sub-flows so they are easier to view. To see this effect, the user must position the mouse pointer over the sub-flow before performing the zoom gesture.
This is a JSX or HTML snippet that contains some text or any elements (such as an image) that you want to display when the canvas is empty, that is, when it doesn’t have any nodes or comments. The default behavior if this config parameter is not provided is that Common Canvas will display an image and message saying: “Your flow is empty!”.
This is a JSX or HTML snippet that contains some text or any elements (such as an image) that you want to display when a data object is dragged from the desktop over the canvas. The default behavior if this config parameter is not provided is that Common Canvas will display an image and a message saying: “Drop to add to canvas and project”. The content will not be displayed unless the enableDropZoneOnExternalDrag configuration parameter (see above) is set to true.
This is a boolean. The default is false. If set to true a graphic overlay will be displayed over the canvas when a data object icon is dragged from the desktop over the canvas. The default graphic overlay will be an image and a message saying: “Drop to add to canvas and project” unless the dropZoneCanvasContent configuration parameter is provided.
This can be either “None”, “Locked” or “ReadOnly”. The default is “None”. When set to either “Locked” or “ReadOnly”, a ‘state tag’ object will be shown permanently over the top of the canvas. The state tag will be positioned in the center and towards the top of the canvas. The state tag consists of a black background rectangle with rounded corners overlaid with an icon and a text label. A tooltip is displayed when the mouse pointer is hovered over the state tag. The icon, label and default tooltip will be set appropriately based on the value (“Locked” or “ReadOnly”) for this setting. The host application can override the tooltip by implementing the Tip Handler callback.
This can be “Mouse”, “Carbon” or “Trackpad”. The default is “Mouse”.
-“Trackpad” has been deprecated and will be removed in the future.
-
-
-
With this set to “Mouse” the following interaction is enabled:
-
-
Zoom canvas = Rotate mouse wheel.
-(Can be simulated with a trackpad with two finger up and down scroll)
-
Pan canvas = Left mouse key down on canvas background + drag.
-(Can be simulated with a trackpad with press down on trackpad and drag.)
-
Region select on canvas = Shift key + left mouse key down on canvas background + drag.
-(Can be simulated with a trackpad with Shift + finger down on trackpad + drag across canvas background)
-
-
-
-
With this set to “Carbon” the following interaction is enabled:
-
-
Zoom canvas = Rotate mouse wheel.
-(Can be simulated with a trackpad with two finger up and down scroll)
-
Pan canvas = Press and hold space bar then left mouse key down on canvas background + drag.
-(Can be simulated with a trackpad by press and hold space bar then press down on trackpad and drag.)
-
Region select on canvas = Left mouse key down on canvas background + drag.
-(Can be simulated with a trackpad with press down on trackpad and drag.)
-
-
-
-
This setting is now deprecated With this set to “Trackpad” the following interactions are enabled:
-
-
Zoom canvas = Two finger pinch or two finger spread gesture.
-(Can be simulated with a mouse as follows: Ctrl + rotate mouse wheel.)
-
Pan canvas = Two finger horizontal or vertical scroll gesture.
-(Can be simulated with a mouse as follows: Vertical pan is rotate mouse wheel; Horizontal pan is Shift + rotate mouse wheel)
-
Region select on canvas = Finger down + drag.
-(Can be simulated with a mouse as follows: Left button down + drag on canvas background)
This is a string which is a class name. The default is empty string. If a class name is provided it is applied to the top-most DOM element for Common Canvas. This can be used to make you CSS override rules more specific which means they will be used in preference to any default styles. For example, if you specify “my-app-styles” for this field then CSS like this:
-
This can be either true or false. The default is false. If set to true, the user can drag and drop a single node or a single comment without that gesture removing selection on any other nodes or comments. If the node being dragged was selected prior to the drag gesture then it and any other objects that are currently selected will be moved. With this parameter set to false (or missing) a drag and drop gesture will select the node or comment being dragged and will deselect any currently selected objects.
This is a boolean. The default is true. If set to false, various editing actions on the canvas will be prevented, as follows:
-
-
-
Nodes cannot be created on the canvas using any of the following:
-
(a) dragging and dropping a node template from the palette onto the canvas or
-
(b) dragging and dropping an object onto the canvas from outside the canvas area, such as a file being dragged from the computer desktop onto the canvas (see note below), or
-
(c) double clicking a node in the palette to create a node
-
Note: It is not possible for Common Canvas to prevent an object being dragged from the computer desktop to the canvas so it is recommended the drop zone (which provides visual feedback about the drop) should be switched off by setting the enableDropZoneOnExternalDrag config field to false.
-
-
-
Nodes and comments cannot be dragged and moved.
-
-
The end points of Links, when enableLinkSelection is set to "Detachable" or "Handles", cannot be dragged and moved.
-
Links from nodes and comments cannot be created by dragging from the port object on the source node or comment to the target node.
-
Comments, node labels and text decorations cannot be edited, neither by clicking the edit icon (which does not appear) nor by double clicking the text.
-
-
Context menu options that alter the canvas objects will be removed from the context menu before it is displayed by Common Canvas. The options that will be removed are:
-
-
-
-
Option Text
-
Action Identifier
-
-
-
-
-
New Comment
-
createComment
-
-
-
Disconnect
-
disconnectNode
-
-
-
Edit->Cut
-
cut
-
-
-
Edit->Copy
-
copy
-
-
-
Edit-Paste
-
paste
-
-
-
Undo
-
undo
-
-
-
Redo
-
redo
-
-
-
Delete
-
deleteSelectedObjects
-
-
-
Create supernode
-
createSuperNode
-
-
-
Create external supernode
-
createSuperNodeExternal
-
-
-
Deconstruct supernode
-
deconstructSuperNode
-
-
-
Collapse supernode
-
collapseSuperNodeInPlace
-
-
-
Expand supernode
-
expandSuperNodeInPlace
-
-
-
Convert external to local
-
convertSuperNodeExternalToLocal
-
-
-
Convert local to external
-
convertSupernodeLocalToExternal
-
-
-
Delete
-
deleteLink
-
-
-
Save to palette
-
saveToPalette
-
-
-
-
If your application adds its own editing actions to the context menu your code must remove them if they are not needed in some situations (e.g. you are displaying a read-only canvas).
-
-
-
Any default toolbar actions (tools) that alter the canvas objects will be disabled regardless of their specified enablement status. These actions are:
-
-
-
-
Default Tooltip
-
Action
-
-
-
-
-
Undo
-
undo
-
-
-
Redo
-
redo
-
-
-
Cut
-
cut
-
-
-
Copy
-
copy
-
-
-
Paste
-
paste
-
-
-
Delete
-
deleteSelectedObjects
-
-
-
New comment
-
createAutoComment
-
-
-
Arrange Horizontally
-
arrangeHorizontally
-
-
-
Arrange Vertically
-
arrangeVertically
-
-
-
-
-
-
Keyboard shortcuts that alter the canvas will not work. These are:
-
-
-
-
Shortcut
-
Action
-
-
-
-
-
delete
-
delete
-
-
-
Ctrl/Cmd + x
-
cut
-
-
-
Ctrl/Cmd + c
-
copy
-
-
-
Ctrl/Cmd + v
-
paste
-
-
-
Ctrl/Cmd + z
-
undo
-
-
-
Ctrl/Cmd + Shift + z
-
redo
-
-
-
Ctrl/Cmd + y
-
redo
-
-
-
-
-
-
The browser’s Edit menu options (cut, copy, paste) will not work with the canvas objects regardless of the setting for enableBrowserEditMenu.
This can be set to: “SVGInline”, “LoadSVGToDefs” or “SVGAsImage”. The default is “SVGInline”. This field controls the display of SVG image files (that is, files with a .svg extension) on the canvas, such as those displayed for node icons or decoration images. This option can be useful to improve performance when images are repeated a large number of times on the canvas and particularly when the browser cache is disabled. Note: this does not affect the display behavior of non-SVG files which are always displayed inside an <image> tag. The behavior for SVG image files is as follows:
-
-
“SVGInline” - This is the default. With this setting, the image file is read in – from the server or cache (if available) – and the SVG tags within the file displayed in-line in the DOM. This means elements within the SVG can be customized using CSS on a node-by-node basis.
-
“LoadSVGToDefs” - With this option, each unique SVG file is read from the server (or cache) and written into a <symbol> element within the <defs> element of the canvas SVG area. A <use> element is then written to the place in the DOM for each place where the image should be displayed. Using this option means the SVG file for each image is only read once which should improve performance if images are repeated a lot on the canvas. However, it does limit the customization possibilities for the images on a node-by-node basis. Customization colors can be passed into the images using CSS inheritance, or the currentColor keyword, provided there are no internal classes applied to the elements in the SVG.
-
“SVGAsImage” - This option causes the SVG file to be displayed within an <image> element in the DOM. The file loading is handled internally by the browser. Again, with this option customization capabilities on a node-by-node basis are limited. Customization colors can be passed into the images using CSS inheritance, or the currentColor keyword, provided there are no internal classes applied to the elements in the SVG.
This is a boolean. The default is true. It is recommended you leave this set to true. If you set this to false your code will be responsible for handling the object model, which is NOT recommended. When set to false, changes are not automatically saved into the common-canvas object model and are not reflected in the canvas display. Consequently, the application is expected to listen to events and update the common-canvas object model using the canvas-controller API if it want visual changes to the canvas.
This is a boolean. The default is false. If set to true the right flyout panel, when opened, will appear below the toolbar and will not cause the toolbar to compress. The default behavior is that the right flyout panel, when opened, will appear at the side of the toolbar and will compress the space available for the toolbar to be displayed. Warning: the notifications panel which is tied to the notifications icon in the toolbar will appear over the top of the right-side flyout with this option set to true.
This is a boolean. The default is false. If set to true, the right flyout panel can be resized by dragging its left border. When hovering over the left border of the flyout, the cursor will change to indicate that resizing is possible. Users can drag the border to adjust the width of the flyout, allowing it to expand or collapse. This functionality offers more flexible layout options for the user. If set to false, the right-flyout panel, when open, will be displayed with a default width and cannot be resized by dragging its edge. The application can add its own sizing function if required.
This is a boolean. The default is false. If set to true the left flyout panel, when opened, will appear below the toolbar and will not cause the toolbar to compress. The default behavior is that the left flyout panel, when opened, will appear at the side of the toolbar and will compress the space available for the toolbar to be displayed.
This is a boolean. The default is false. If true, the context menu will include a Create External Supernode option when a set of objects are selected from which a supernode can be created.
-
Waring: The host application must implement some of the common-canvas callbacks for external pipeline flow support to work correctly. See the section on External Pipeline Flow support for more details.
This can be: “None”, “During” or “After”. The default is “None”.
-
-
“None” - there is no snap to grid and objects can be moved to any position on the canvas.
-
“During” - when nodes or comments are moved or sized, the objects snap to an imaginary grid while the objects are being dragged or sized. This gives a somewhat jerky effect as the move or size is happening but has the advantage of telling the user exactly where the object will be when they release the mouse button to end the action.
-
“After” - nodes or comments snap to a grid when the drag or size event ends. This gives a smooth dragging and sizing effect but the user does not see the final position until they release the mouse button at the end of the action. By default the canvas uses reasonable values for the grid increments.
This optional value overrides the default horizontal increment of the snap-to-grid grid. It can be either a numeric value which is a number of pixels or it can be a numeric value followed by a % sign (e.g. “25%”) which indicates the grid will be a percentage of the default node width. Its default is dependent on whatever is set for enableNodeFormatType. That is for “Horizontal” it will be “20%” and for “Vertical” it will be “25%”.
This optional value overrides the default vertical increment of the snap-to-grid grid. It can be either a numeric value which is a number of pixels or it can be a numeric value followed by a % sign (e.g. “25%”) which indicates the grid will be a percentage of the default node height. Its default is dependent on whatever is set for enableNodeFormatType. That is for “Horizontal” it will be “33.33%” and for “Vertical” it will be “20%”.
This is the spacing in pixels which is used to separate nodes horizontally when either the vertical or horizontal auto layout action is used. For horizontal auto layout, Common Canvas may override this value if it decides that more space is needed to prevent connecting lines from doubling back on themselves.
This is a boolean. true is the default. If true, the Cut/Copy/Paste items in the Browser’s Edit menu, including keyboard input for those actions, can be used for performing those actions on objects (e.g. Nodes) in the canvas. When false, those items in the Browser’s edit menu, including keyboard input for those actions, will not work for objects in the canvas. This will not prevent those actions working in the canvas when, say, invoked with the toolbar or canvas context menus, but this property can be used if the keyboard input for those actions into the canvas is disabled for Common Canvas using the Keyboard Config object.
This is a boolean. false is the default. It tells Common Canvas whether you want pipleineFlow and palette objects to be validated against the schema files when they are submitted to the canvas controller, using the setPipelineFlow(pFlow) or setPipelineFlowPalette(palette) methods. If any validation errors are found messages are displayed in the browser console. It is recommended this option be set to true during development and testing but switched off in production since schema validation can be somewhat slow for large objects.
The canvas toolbar config object is optional. If it is not provided Common Canvas will display a reasonable default toolbar.
-
-
If the toolbar config is provided, it configures which action buttons and dividers are shown in the toolbar. A toolbar will be displayed for Common Canvas if the canvas configuration field enableToolbarLayout is set to “Top” (which is the default).
-
The toolbar config object specifies actions for the left and right side of the toolbar. The application can also optionally tell the toolbar not to handle the enable/disable state for the standard toolbar buttons using overrideAutoEnableDisable.
-
When the user clicks one of the action buttons the action will be performed either by Common Canvas or by the application, if it is an applicaiton specific action. In both cases, Common Canvas will call the beforeEditActionHandler and editActionHandler callbacks.
The leftBar and rightBar fields contain an array of action objects: one element for each toolbar item. Here is an example, toolbar configuration object:
leftBar - an array of action items to specify what is displayed on the left side of the toolbar.
-
-
-
rightBar - an array of action items to specify what is displayed on the right side of the toolbar. If this is omitted, Common Canvas will automatically populate the right side of the toolbar with zoom-in, zoom-out, and zoom-to-fit actions. To suppress these right side actions, specify the rightBar field as an empty array or an array containing the actions required on the right.
-
-
-
overrideAutoEnableDisable - a boolean. The default is false. By default Common Canvas has an auto-enablement feature that controls the enablement of common tools in the toolbar based on user actions (e.g enable the Delete icon when items are selected). If overrideAutoEnableDisable set to true it will switch off the auto-enablement feature. This is useful if the host application wants to disable all the nodes under certain circumstances. If set to true, the enable property in the action items for each tool is used to decide whether to display the icon as enabled or disabled. If set to false or omitted, Common Canvas will handle the auto-enablement of common actions. (See the actionsection below for more details.)
-
-
-
The toolbar will display the objects in the same order they are defined in the leftBar and rightBar arrays.
action - a unique identifier string which is the name of the action to be performed. This action name will set in the editType field of the data parameter passed into the beforeEditActionHandler and editActionHandler callback methods. The application can use these callbacks to detect what action the user clicked in the toolbar.
-
The toolbar supports two types of action:
-
-
-
Internal actions - These are requested by the application by specifying one of the reserved internal actions names. These actions are performed internally by Common Canvas. A default icon will be provided by Common Canvas for the most popular actions. For example, if the deleteSelectedObjects action is specified a trash can icon will be displayed in the toolbar and any selected objects will be deleted from the flow editor when the action is clicked. The application can override the default icon by specifying the iconEnabled field.
-
Disablement of these built in actions is also handled by Common Canvas: “undo”, “redo”, “cut”, “copy”, “paste”, “deleteSelectedObjects”, “createAutoComment”, “arrangeHorizontally” “arrangeVertically”, “zoomIn”, “zoomOut”, “zoomToFit”.
-
For example, when no canvas objects are selected the deleteSelectedObjects action (trash can icon) will be automatically disabled.
-
The application can switch off this automatic enable/disable function by setting overrideAutoEnableDisable field in the toolbar config to true. When overrideAutoEnableDisable set to true, the enable field in each action object will set the enablement appearance of the item.
-
-
-
External actions - These are specified by the application and must be handled by the application in the beforeEditActionHandler and editActionHandler callbacks. An icon must be specified for these actions. The application can use icons imported from the Carbon Icon library. For example, in the sample code above myBookmrk has been specified as a external action with the Carbon Bookmark icon specified. Common Canvas will ignore this action when the button is clicked and pass it through in the data.editType field to the editActionHandler callback.
-
-
-
-
-
label - a short string or a JSX object that describes the action. This is used as the tooltip text or is (optionally) displayed next to the icon if incLabelWithIcon is specified.
-
-
-
enable - A boolean. The action button is clickable when set to true. If false, the button will be disabled. If not set, it will default to disabled (false). If overrideAutoEnableDisable is set to false, or omitted, this field is ignored for the standard action items (like cut, copy, paste) because Common Canvas handles their enable/disable appearance. If overrideAutoEnableDisable is set to true, this field will be used for standard action items.
-
-
-
-
-
iconEnabled - specifies the icon to display when enable is true. Common Canvas will provide icons for some of the reserved internal actions so the application doesn’t need to specify iconEnabled or iconDisabled for them:
-
It can be either:
-
-
a string containing the path to a custom SVG file to display or
-
a JSX expression, for example (<Edit32 />) where Edit32 is an icon imported from carbon icons. It is recommended to only pass very simple JSX expressions.
-
-
-
-
iconDisabled - specifies the icon to display when enable is false. If iconDisabled is not specified iconEnabled will be used instead. It can be omitted for any of the standard actions (see iconEnabled above).
-
It can be either:
-
-
a string containing the path to a custom SVG file to display or
-
a JSX expression, for example (<Edit32 />) where Edit32 is an icon imported from carbon icons. It is recommended to only pass very simple JSX expressions.
-
-
-
-
incLabelWithIcon - can be set to “no”, “before” or “after”. The default is “no”. This field specifies whether the label should be displayed in the toolbar with the icon and if so, where it is displayed with respect to the icon.
-
-
-
-
-
kind - can be set to “default”, “primary”, “danger”, “secondary”, “tertiary” or “ghost”. The default it “default”. These give the action the same styling as the equivalent kind’s of buttons in the carbon library.
-
-
-
-
tooltip - A string or JSX object. The tooltip that will be displayed for the action. If this is not provided the label will be displayed as the tooltip instead.
-
-
-
isSelected - A boolean. When set to true the toolbar button displays a selection highlight. This is displayed as either a blue bar along the bottom border of buttons in the toolbar
-
-
-
or a checkmark for items that appear in sub-menus.
-
-
When applied This is useful for implementing a button that switches on and off a mode, as opposed to a regular button which does not have any state.
-
This property can also be used to indicate a current state between a number of mutually exclusive settings. In this case, one button would be added to the toolbar for each setting and then the isSelected property would be set to true for the setting that is currently active. Then, when the user clicks a different option in the set, the application code would set isSelected to true for that button and set it to false for the previously selected button. (This would give behavior like a radio button set.)
-
-
-
className - This a string that will be appended to the class field for the top-level <div> that surrounds the action button. This can be used to set application-specific CSS for the button.
-
-
-
textContent - This is an additional string that will be displayed on top of the action button. It can be used to specify adittional information to enahance the icon. For example, a count of messages could be displayed over a icon that, when clicked, shows a messages panel.
Two toolbar items are automatically added to the toolbar:
-
-
A palette action which is used for opening and closing the palette. This is added to the left side of the toolbar if the enablePaletteLayout field is set to either “Flyout” (the default) or “Modal” in the canvas configuration.
-
A notification panel action which is used to open and close the notifications panel. This will be added to the right side of the toolbar if a notification configuration object is specified to the <CommonCanvas> react object.
-
-
The position and a subset of fields for these items can be customized by providing an appropriate object in either the leftBar or rightBar arrays. The action field for the items should be either “togglePalette” or “toggleNotificationPanel”. Any of the following fields can be optionally provided to override the default values: label, iconEnabled, incLabelWithIcon and tooltip.
-
For example, if the application provides the following in, say, the leftBar array:
-
The toolbar button can show a ‘sub-area’ below the button when the button is clicked. This can be either a sub-menu which is a list of text options or a sub-panel which is a small window that can show whatever the application wants such as settings or messages.
-
-
-
subMenu - Specify either this or the subPanel field. This is an array of action objects (the same as those specified for the toolbar) which will displayed as a menu of options that appears under the icon on the toolbar.
subPanel - Specify either this or the subMenu field. This is a React object that will render the contents of a panel that appears under the action icon.
subPanelData - This is a JavaScript object that will be passed as one of the props into the React object specified in the subPanel field. The application can use this to pass into the subPanel class any data or callback functions needed for the panel to do its job.
-
-
-
purpose - can be set to “single” or “dual”. The default is “single”. If set to “dual” the button will have two parts. The icon will be displayed to the left and to the right will be an up/down chevron icon. If the user clicks the icon on the left the action specified in the action field will be executed. If the user clicks the chevron a panel will be displayed below the chevron with the contents that are specified in the object specified in the subPanel field.
closeSubAreaOnClick - This is a boolean. The default is false. If set to true the sub-area will be close when sany element in it is clicked. This behavior might be useful if the sub-area displays a menu of options where only a single click on one of them is required.
Regular toolbar buttons, explained above, are displayed as set of Carbon Buttons. If the application needs to display something not wrappered in a button, you can provide your own JSX to display in the toolbar. Be aware however that, because of the way the toolbar is designed, there are restrictions on what the toolbar can do to display your JSX. For example, it cannot display anything with a height greater than the toolbar height.
-
If you provide your own JSX object it is displayed in a simple div in the toolbar. Some attributes are applied to the div to allow the action to work correctly within the toolbar - these cannot be changed. You are responsible for styling your JSX object to get it to appear the way you want.
-
Also be aware that, if the width of the toolbar reduces (maybe by the user sizing the page) your action may get moved into the overflow menu. It is also your responsibility to style the button so it appears as you want in the overflow menu as well as in the toolbar.
-
The JSX can be provided in the jsx field. Here is an example. The only other fields that are recognized with the jsx field are action and tooltip, all other fields will be ignored.
-
{
-action:"custom-loading",
-jsx:(<divstyle={{padding:"0 11px"}}><InlineLoading
-status="active"description="Loading..."/></div>),
-tooltip:"Loading the thing you wanted."
-}
-
-
-
-
action - a unique identifier and the name of the action to be performed.
-
-
-
jsx - A JSX object or a funciton returning a JSX object. This will be displayed as the action in the toolbar.
-
To make the JSX object accessible inside the toolbar this field should be provided as a function. The function will pass a tabIndex field which should be set into the tabIndex property of the display object being created (see expample below). Additionally, the display object should have the `className set to “toolbar-jsx-obj” (see example below).
-
-
-
tooltip - A string or JSX object. This will be displayed as the tooltip for the action in the toolbar. If tooltip is omitted no tooltip will be added to your action. If tooltip is specified the jsx will be inside a tooltip div which is in the toolbar div mentioned above.
-
-
-
For example, the following code that includes some Carbon React components:
-
The old toolbar configuration is still supported for now (but is deprecated). This allows the config to be provided as an array that defines just the left side of the toolbar. The right side will always show the zoom actions (zoomIn, zoomOut, zoomToFit) and a notifications panel icon (if a notification configuration object is provided in the <CommonCanvas> React object). These right side actions will always show on the right-hand side of the toolbar and are handled internally by the canvas. The entries in the array follow the same definition as described above. Note: there is no need to provide a palette action in the array because a palette icon and following divider will automatically be added to the toolbar when a palette is specified for the canvas.
-
An example of the toolbar config array should look like this:
-
The Notification Config object specifies the appearance of the notifications panel. If a Notification Config is passed to Common Canvas a notifications button will be shown on the far right of the canvas toolbar. When clicked, the button opens the Notificaiton Panel.
-
For information about the structure of notification messages, refer to the Notification Messages page. Messages can be added and removed from the notification panel by calling the notification methods in the canvas-controller..
-
The Notification Config object looks like this:
-
constnotificationConfig={
-action:"notification",
-label:"Notifications",
-enable:true,
-notificationHeader:"Notification Messages",
-notificationSubtitle:"subtitle",
-emptyMessage:"You don't have any notifications right now.",
-clearAllMessage:"Clear all",
-keepOpen:true,
-clearAllCallback:()=>{console.log("Clear All clicked");}
-};
-
-
-
-
action - “notification” enables the notifications button to appear in the far right of the toolbar.
-
-
-
label - the Tooltip label to display for the notifications button in the toolbar.
-
-
-
enable - Toolbar button will have hover effect and is clickable when set to true. If false, the button will be disabled and unclickable. If not set, it will default to disabled (enable: false)
-
-
-
notificationHeader - String to display in the notification panel header. If not set, it will default to “Notifications”.
-
-
-
notificationSubtitle - String to be displayed as a sub-title in the panel header. If not set, panel header will be sized to only contain the notificationHeader string.
-
-
-
emptyMessage - String to be displayed when there are no notification messages to display.
-
-
-
clearAllMessage - String to be displayed on a button displayed at the bottom of the panel. The button can be clicked to clear all the messages from the panel. If omitted the button, and the footer area of the panel it appears in, will not be displayed.
-
-
-
keepOpen - A boolean which indicates when the panel will close. The default is false. If set to false, the panel will close when the user clicks on the page somewhere outside the panel. If set to true the panel will remain open when the user clicks somewhere on the page outside of the panel. With the option the user must click the x icon in the top right of the panel, or click the notification toolbar icon, to close the panel.
-
-
-
clearAllCallback - An optional callback function that will be called every time the “clear all” button is clicked.
-
-
-
secondaryButtonLabel - Label for the optional secondary button to be displayed in the notification panel. Both secondaryButtonLabel and secondaryButtonCallback must be specified for the button to appear.
-
-
secondaryButtonCallback - A callback function that will be called when the secondary button is clicked.
-
secondaryButtonDisabled - Specify whether the secondary button is disabled or not.
enableCreateSupernodeNonContiguous - Allows the creation of supernodes from non-contiguous nodes. When set to true, the “Create supernode” menu item will be added to the default context menu when the currently selected nodes are contiguous or non-contiguous. When set to false, the “Create supernode” menu item is only added to the default context menu when the selected nodes are contiguous. The default value is false.
-
-
-
defaultMenuEntries - Controls what entries are generated in the default context menu generated by Common Canvas. This has the following properties:
-
-
‘saveToPalette’ - This is a boolean. The default is false. If set to true, Common Canvas will add a ‘Save to palette’ option to the default node context menu.
-
‘createSupernode’ - This is a boolean. The default is true. If set to false, Common Canvas will not show the ‘Create Supernode’ option in the default context menu for nodes.
-
‘displaySupernodeFullPage’ - This is a boolean. The default is true. If set to false, Common Canvas will not show the ‘Display full page’ option in the default context menu for supernodes. When true, the option will be displayed. Clicking that option navigates the user to the full page view of the supernode’s pipeline as if the user had clicked the expansion icon of the expanded in-place supernode view.
-
‘colorBackground’ - This is a boolean. The default is true. If set to false, Common Canvas will not show the ‘Color background’ option in the default context menu for comments. When true, the option will be displayed.
-
-
-
-
[Note: If any host app wants more control over the default context menu here, please open an issue.]
The keyboard config object configures whether certain actions are available from the keyboard when focus is on the flow editor.
-See the Keyboard Support section for what key combinations are supported.
You can optionally provide callback listeners. These will be called when the user interacts with the canvas and allows
-your application to perform processing specific to your application’s needs based on user interactions. If you don’t implement any of the callbacks, Common Canvas will perform appropriate actions if necessary.
Called for each edit action on the canvas. It is called before the internal object model has been updated and the edit action has completed, so this can be used to cancel user actions if necessary.
Called whenever something is clicked, double-clicked or right-clicked on the canvas. This can be used, for example,
-to open a properties window when a node is double clicked.
This callback is optional. You don’t need to implement anything for it. If implemented, it must return an array of actions that describe what options are displayed in the Context Menu or Context Toolbar.
-
If this callback is not provided Common Canvas will handle context menu/toolbars, and their actions, internally. You only need to implement this callback if you want to add or remove options to/from the context menu/toolbar or provide your own menus in place of the default ones.
This callback will be called if the enableContextToolbar canvas config option is set to false (which is the default) and when the user performs a context menu gesture, such as mouse ‘right click’ or clicking an ellipsis icon, on a:
-
-
Node
-
Link
-
Comment
-
Port
-
The canvas background or
-
Combination of objects - if a number of objects are selected
-
Note: With multiple selected objects, the convention is that a context menu/toolbar should display actions that are applicable to all the objects that are selected, rather than just the object for which the menu was requested.
This callback will be called if the enableContextToolbar canvas config option is set to true and when the mouse cursor is hovered over any of the objects mentioend above.
-type - Indicates the type of object for which the context menu was selected. Can be “node”, “input_port”, “output_port”, “link”, “canvas” or “comment”
-
targetObject - The object for which the context menu was requested. Not provided when type is “canvas”.
-
selectedObjectIds - An array containing the IDs of all currently selected nodes and/or comments and/or links.
-
mousePos - An object containing the coords of the mouse when the context menu was requested
This is an array describing the default menu that Common Canvas would usually display. If necessary, you can modify this array with your own elements or remove elements and then return the modified array. Alternatively, you can ignore this parameter and just return your own array.
The callback must return an array, that describes the context menu to be displayed. If the callback returns a null, then no menu/toolbar will be displayed.
-
There is one element in the array for each entry in the context menu. An entry can be either a context menu item, which consists of a label and an action, or a divider. An action can be disabled by setting the ‘enable’ field to false.
If you want to simply add your action to the default context menu provided by Common Canvas you can take the defaultMenu parameter provided to the callback, and add your menu item to it. Alternatively, you can provide a complete new context menu of your own.
-
Here is a sample implementation of contextMenuHandler, which takes a source object (described above) and the defaultMenu as parameters, and adds a custom action to the default menu when the user ‘right clicks’ the canvas background.
To display a context toolbar the same type of array is returned as described above for context menu. However, there are some extra fields for the action elements in the array. These are
-
isToolbarItem - This is a boolean. The default is false. If set to true the action will be added to the toolbar and if set to false the action will be displayed in the overflow menu.
-
icon - This is the icon to display for the action. If isToolbarItem is set to true you must provide an icon otherwise the action will show as an empty space in the toolbar. If an icon is specified and isToolbarItem is set to false, the icon will be displayed next to the action in the overflow menu. For many internal actions, Common Canvas will automatically display an appropriate Carbon icon. See the Internal Actions page for a list of actions that have associated icons.
-
Dividers can also be added to the context toolbar by specifying ‘toolbarItem: true’
The contents of the context toolbar is dependent on which object the mouse cursor is currently hovering over (which may be different to any of the currently selected objects). You should make sure the actions you return in the array are applicable to the object the mouse cursor is hovering over or, if it is hovering over a selected object and other objects are also selected, to the set of selected objects.
-
To help decide whether the mouse cursor is hovering over a selected object or not, the application can call the canvas controller’s helper function: ‘isContextToolbarForNonSelectedObj(source)’. This will return true if the mouse cursor is over a non-selected object.
Internal actions are implemented inside Common Canvas, like “deleteSelectedObjects” in the example above. Common Canvas supports a large number of internal actions.
External actions are custom actions you want Common Canvas to display for your application like “myApp_Action1”, in the example above.
-Tip: To avoid any future name clashes with internal actions that might be added it is recommended you should make sure you action names are unique. For example, by adding a prefix to your application specfic actions.
This callback is optional. It is called before user actions are completed, so it provides the opportunity for the application to alter or cancel an action before it is applied to the object model and reflected in the flow editor display.
-You don’t need to implement anything for it but if you do implement it you must return either a data object or null. This callback is called in all the same instances where the editActionHandler is called. The difference is that this callback is called before the internal object model is updated. This gives your application the opportunity to examine the action that is about to be performed and either: let it continue; modify it and let it continue; or cancel it.
-
This callback is provided with two parameters: data and command.
-
-
data parameter - this is the same as the data object described for editActionHandler (see above)
-
command parameter - typically this will be null but for undo operations (that is where data.editType === “undo”) this will be the command that is about to be undone. For redo operations (that is where data.editType === “redo”) this will be the command that is about to be redone.
-
-
This callback must return either the data object that was passed in or null. beforeEditActionHandler will behave as follows based on what is returned:
-
-
If the data object is returned unmodified: the action will be performed as normal.
-
If the data object is returned modified: the action will be performed based on the modified data object. This means your application can alter the behavior of the action that will be performed. For example, you could intercept a createNode command and change the label for the new node in the nodeTemplate to something different. Then when the node is created the new label will be used. It is recommended you be veryvery careful when updating this object since there is no error checking in Common Canvas to ensure you modified the object correctly.
-
If null is returned: the action will be cancelled and not performed on the internal object model nor will editActionHandler be called.
-
-
If you need to do any asynchronous activity in the beforeEditActionHandler callback you can:
-
-
Return null from the callback - which will cancel the current action
-
Do your asynchronous activity. While this is happening, the user ought to be prevented from modifying the canvas so you should display some sort of progress indicator or modal dialog to inform the user that some activity is occurring.
-
Then call CanvasController.editActionHandler(data) passing in the data object as a parameter with the modified properties. This will then execute the action as before. Note: This means the beforeEditActionHandler will be called a second time so be sure you put in a check to make sure you don’t get into a loop.
This callback is optional. You don’t need to implement anything for it and it doesn’t return anything. It is called whenever the user does the following gestures on the canvas:
-
-
Clicks a tool/icon in the toolbar.
-
Clicks an option in the context menu or context toolbar
-
Presses a key combination on the keyboard to cause the canvas to change.
-
Performs some direct manipulation on the canvas such as:
-
Create a node
-
Moves one or a set of nodes/comments
-
Edits a comment
-
Links two nodes together
-
etc
-
-
-
-
These is will either perform one of the many internal actions supported by Common Canvas or the application’s own external actions, if they have been added to the context menu/toolbar or the main canvas toolbar.
This callback is called after the common-canvas internal object model has been updated. This callback is provided with two parameters: data and command.
-
-
data parameter - This is the data for the initial request create by whatever action the user performed. The data fields can vary depending on the action. Here is an example:
-
editType - This is the action that originates from either the toolbar, context menu, keyboard action or direct manipulation on the canvas. If you specified your own action in the context menu or in the toolbar this field will be your action’s name.
-
-
-
editSource - This is the source of the action. It can be set to “toolbar”, “contextmenu”, “keyboard” or “canvas” (for an action caused by direct manipulation on the canvas).
-
-
-
selectedObjects - An array of the currently selected objects.
-
-
-
selectedObjectIds - An array of the IDs of currently selected objects. Included for backward compatibility.
-
-
-
Other fields - Numerous other fields which vary based on the action and the source of the action.
-
-
-
-
-
command parameter - This is a Javascript class which is the command object that was executed to run the action ‘requested’ by the user and added to the command stack. The command object may contain fields which are the result of executing the command. For example, when the user creates a new node on the canvas the ‘createNode’ action will be performed and the command parameter in editActionHandler will contain a field called newNode which is the node that was created on the canvas.
-
If the user performed an undo action this will be the command that has been undone. If the user performed a redo action this will be the command that was redone.
This is an optional handler you don’t need to implement anything for it unless you want to. The layoutHandler callback, when provided, is called for each node on the canvas and allows the application to customize the node layout properties on a
-node-by-node basis.
- The callback should return a JavaScript object whose properties will override the default properties for node layout. The callback is provided with a parameter data which is the node object. Your code can look at the node properties and decide which properties it needs to override. This can be used to change the node shape, styling and position and size of node elements like the image, main label etc.
-
Decorations are small images that can be displayed on or near to your nodes and links. They can be for display only or actionable (so the user can click on them). See the canvas JSON schema for information on how to define decorations for your nodes.
-
This callback is called when the user clicks on an actionable decoration. You don’t need to implement anything for this callback unless you added actionable decorations to your nodes. It doesn’t return anything. It is called whenever the user clicks on a decoration that you added to a node in the canvas JSON.
This optional callback can be implemented to override the tooltip content that is displayed by default for each canvas object. It is called before tips are shown for: palette categories, palette node templates, nodes, ports, links, decorations and the state tag.
-Note: The display of tooltips (or not) can be controlled using the tipConfig field of the canvas config object.
-
Common Canvas provides default implementations for all of the tips except for links and decorations, as follows:
-
-
-
-
Object
-
Default tip behavior
-
-
-
-
-
Palette category
-
Contains the category name and the category description.
-
-
-
Palette node template
-
Contains the category name, the node type and node description.
-
-
-
Node
-
Contains the name, description and status icon and optionally, if the name was modified from the original name, the original node type.
-
-
-
Port
-
The port label is shown
-
-
-
Link
-
No tip is shown by default
-
-
-
Decoration
-
No tip is shown by default
-
-
-
State tag
-
An appropriate explanation for the state displayed by the tag
-
-
-
-
To override the content, you can return either a string or JSX object. If your code returns null for a particular type of tip, Common Canvas will display the default tip for that object. See App.js in the test harness code for an example tipHandler.
-
Common Canvas calls the tipHandler callback with two parameters:
-
-
tipType - the type of the tip
-
data - an object that describes the canvas element for which the tip was requested
This is an optional callback. It is called when new objects are created in the canvas and allows the application to provide its own method to generate a unique id for the object.
- If no idGeneratorHandler is set or the method returns null, an appropriate UUID is generated by Common Canvas for each object. The callback is called with a two parameters:
- * An enumerated string to describe the action being performed (create_node, create_comment, create_node_link, create_comment_link, clone_node, clone_comment, clone_node_link or clone_comment_link) and
- * A JavaScript object with additional data to describe the object
-
The callback should return a string containing the application’s unique ID for the object.
-Here are more details about the different action and their parameters.
-Note that the link to be cloned has references to the original source and target nodes, while the sourceNodeId and targetNodeId are the new node ids for the copied nodes. The new nodes are not part of the model yet.
-
-
clone comment link: triggered when copying&pasting a comment and a node that are connected
-Note that the link to be cloned has references to the original comment and target node, while the sourceNodeId and targetNodeId are the new ids for the copied comment and node. The new node and comment are not part of the model yet.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
This callback is optional. You don’t need to implement anything for it and it doesn’t need to return anything to Common Canvas. It is called whenever the user clicks or double clicks on something on the canvas. You could use this callback to implement opening a properties dialog when the user double clicks a node.
The callback is called with a single source parameter which contain information about the object that was clicked.
-
Note: When handling selections, it is recommended the selectionChangeHandler be used in preference to this handler when possible. selectionChangeHandler will notify you of all selection changes regardless of how they occur, such as when the user presses Ctrl+A on the keyboard to select all objects.
-
At the moment only click/double-click/context-menu on nodes and the canvas background are returned. It is provided with one parameter that looks like this:
clickType - This can be either “SINGLE_CLICK”, “SINGLE_CLICK_CONTEXTMENU” or “DOUBLE_CLICK”
-
objectType - Can be either “node”, “comment”, “canvas” or “region”. “region” is specified when the user pulls out a selection rectangle around a set of objects that might include nodes and comments.
-
id - The ID of the node or comment clicked. Only provided when objectType is “node” or “comment”
-
selectedObjectIds - An array of the selected objects (after the click action was performed).
-
-
Note: “SINGLE_CLICK_CONTEXTMENU” indicates that the user performed a contextmenu gesture when doing the click such as pressing the right-side mouse button or a two finger tap on a trackpad.
This is an optional handler you don’t need to implement anything for it unless you want to. This callback allows your code to override the default tooltip text for the Undo and Redo buttons.
The actionLabelHandler callback, when provided, is called for each action that is performed in Common Canvas. The action object parameter, passed in to the callback, contains details of the action being performed. This callback should return either a string or null. If a string is returned it will be shown in the tooltip for the Undo button in the toolbar preceded by “Undo:” and the string will also appear in the tooltip for the Redo button (when appropriate) preceded by “Redo:”. If null is returned, Common Canvas will display the default text for the Undo and Redo buttons.
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.
// 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)
-
// 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)
-
// 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)
-
// 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()
-
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()
-
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:
// 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)
-
// 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)
-
// 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)
-
// 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)
-
// 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()
-
// 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)
-
// 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 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 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()
-
// 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()
-
// 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()
-
Your application can add Decorations – additional icons, text labels, shapes or JSX objects – to nodes or links in the canvas to indicate special status or attributes of the node or link. Decorations can be static (for display only) or interactive (a hotspot) so the user can click them to initiate some action.
Node decorations can be specified in the nodeLayout object in the canvas config. Decorations specified in this way are applied to all nodes on the canvas.
-
-
-
Decorations can be applied to, and retrieved from, nodes or links in the pipelineFlow in the app_data.ui_data section for the node or link. (Note: JSX objects are not supported in the pipelineFlow document).
-
-
-
Decorations can be returned in the layout information returned from the layoutHandler CommonCanvas callback method.
A reference to an image to display for the decoration. If an image is specified the image is displayed within an outline rectangle unless outline is set to false. The image should be a reference to your image like: “/images/decorations/zoom-in_32.svg”. Do not set label or path or jsx when this field is set.
An SVG shape that is displayed using this string as it’s SVG path. eg. “M 0 0 L 10 10 -10 10 Z” could be specified to draw a triangle. Do not set image or label or jsx when this field is set.
A JSX object that is is displayed at the specified decoration location. Do not set image or path or label when this field is set. Note JSX decorations are not supported in the pipelineFlow document.
A boolean that defaults to false. When set to true, if the mouse pointer is hovered over the label an edit icon is displayed next to the label which, when clicked, opens the label for editing. The label can also for double clicked to go to edit mode.
-
When editing is completed (by clicking outside the text area) an editDecorationLabel action is executed which results in calls to first the beforeEditActionHandler and then the editActionHandler callbacks.
Can be either “center” or “left”. When set to center the label will be centered on the point defined by the position, distance, x_pos and y_pos properties.
A boolean that defaults to false. When set to true the label is displayed on a single line and is truncated at the width of the label (specified in the width property for the decoration) and does not word wrap. If it is truncated an ellipsis (…) is displayed at the end of the truncated text.
-
If this property is set to false, long label text is displayed over a number of lines with word wrapping being controlled by the width set for the decoration. If the text extends beyond a second line an ellipsis (..) is displayed at the end of the second line. This is controlled by the -webkit-line-clamp: 2; CSS property. You can override this if you want the ellipsis to be displayed on a different line.
-
Note: For both single and multi-line labels you may need to set the height property for the decoration to show the text fully.
A number or null. Defaults to null. If set to a number the label will be restricted to that number of characters. If the label in the pipeline flow document is longer than the max number it will be displayed but when it is edited the user will not be able to do anything except delete characters until the label is shorter than the max number. If this property is set to null or omitted an unlimited number of characters may be entered by the user.
A boolean that defaults to false. When false, if the user presses the return key nothing will happen. This means multi-line labels will only word-wrap at the width of the decorator. Preventing newline insertion is useful if the label text appears elsewhere in the UI which is not able to show text with newline characters. When set to "save", if the user presses the return key, the editing will be completed and the label saved – this is the equivalent of clicking on the canvas background to complete the edit. If set to true, a new line character will be inserted in the label when the user presses return.
For a link, this can be one of these 3 enumerated values:
-
"source"
- "middle"
- "target"
-
-source will position the decoration at the start point of the line and target will position it at the end point of the line. If omitted it will default to middle.
-
A number of pixels. This is only applicable when the decoration is for a link line and then, only with straight connecting lines. That is, for node to node connections when the config property enableLinkType is set to "straight". When specified, it will move the anchor point for the decoration to a new position along the connecting line relative to the initial position specified in the decoration’s position property. A positive number moves the decoration along the line from the starting position towards the target of the link and a negative number backwards towards the source of the link. For example, if a straight link decoration has position of source and a distance of 20 the decoration’s anchor point will be 20 pixels along the link line from the source (start) point of the line. After the distance value has been applied to the anchor point of the decoration, any x_pos and y_pos adjustment will be applied to fine tune the decoration’s final position.
This is the number of pixels horizontally from the anchor point that the decoration is positioned. It can be positive or negative. If omitted it takes a default value from the node layout fields. x_pos is not applicable if you specify an SVG path using the path field, because the SVG path can be used to position the shape.
This is the number of pixels vertically from the anchor point that the decoration is positioned. It can be positive or negative. If omitted it takes a default value from the node layout fields. y_pos is not applicable if you specify an SVG path using the path field, because the SVG path can be used to position the shape.
This is the width for the decorator in pixels. For an image decorator, it is the width of the rectangle surrounding the image. For a label decorator it is the width allowed for display of the label text. If omitted it takes a default value from the node layout fields for Node decorations and from the canvas layout properties for Link properties.
This is the height for the decorator in pixels. For an image decorator, it is the height of the rectangle surrounding the image. For a label decorator it is the height allowed for display of the label text. If omitted it takes a default value from the node layout fields for Node decorations and from the canvas layout properties for Link properties.
A Boolean. It defaults to false. When set to true the decoration becomes clickable and when it is clicked the decorationCallbackHandler is called with the ID of the decoration passed as a parameter.
An optional class that will be applied to the decoration. You can add a style rule that references that class in your CSS to style the decoration and override the default styles.
A Boolean. It defaults to true. When a decoration is specified with an image field the image is typically displayed with a outline rectangle around it and with an offset within the rectangle to improve presentation. If outline is set to false the outline rectangle is not displayed and the image is displayed without any offset from its specified x_pos and y_pos.
A String. When specified, the string will be shown in a tooltip when the pointer is hovered over the decoration. No tip will be displayed if the tooltip property is omitted. Note: for decoration tooltips to be displayed on the canvas, the decorations property of the tipConfig object in the canvas config must be set to true (which is its default setting).
A Boolean. It defaults to false. When set to true the decoration object will not be saved in the pipelineFlow document returned by the CanvasController.getPipelineFlow() method. Typically, this should be set to true when adding decorations programmatically to the nodes and links on the canvas.
Using x_pos and y_pos, decorations can be displayed outside the node boundary.
-
If no image or label or path is provided, the default decoration is a rectangle displayed with the class_name provided.
-
You can specify as many decorations as you want by providing extra entries in the decorations array.
-
Images and labels are positioned differently. For images, the position defined for the decoration is the top left corner of the image. For labels it is anchor point for the label which is the base line of the string in the vertical direction and is dependent on the text-anchor CSS property applied to the text. So if you apply the text-anchor: middle CSS property to the label in the style related to class_name the label will be centered on the point calculated for the position of the decoration.
Because historically Common Canvas has had to deal with different external flow definitions, there are some differences between the nodes, comments and links that the canvas-controller API handles internally and those specified in the pipelineFlow schema. As follows:
For the API methods that involve nodes, comments and links, those objects are passed in and out by the API in their internal formats rather than the formats defined in the schema files.
-
The internal structure is a somewhat flattened version of that in the schema definition. That means, properties that are in <object>.app_data.ui_data are flattened out and appear as properties in the <object> itself. So for example a node that conforms to the schema might look like this:
-
-Note that, any properties in app_data, other than ui_data, are preserved in the internal format. So in the example, app_data.other_data in the schema format is preserved in the internal format.
-
The other difference between the API and the schema formats is with links.
-
In the pipeline flow schema, links are typically defined as properties within another object, for example, a node to node link is defined within a links array inside the inputs field of the target node and contains references to the node id and port of the source node. Also, links from comments to nodes are stored as an array in the comment object.
-
However, in the API and internally in Common Canvas, links are treated as a top level object; that is, there is an array of links stored internally which can be manipulated using the API methods. Each link has a unique ID. Consequently, links can be retrieved from the API by their ID field and properties of the links can be updated again by identifying the links using their ID. If you do not specify an ID for links in your pipelineFlow document a unique global ID will be generated for each link when the pipeline flow is loaded.
The host application code can programmatically create nodes on the canvas in two ways:
-
-
-
By calling CanvasController API methods to create and add the node to the canvas.
-
-
-
Creating and adding a node to the Pipeline Flow document
-
-
-
Creating and adding a node to the Canvas Controller API¶
-
The following code will programmatically add a node to the canvas. These commands will update the common-canvas object model directly and will not be added to the command stack so the user will not be able to undo / redo these actions. Also, the beforeEditActionHandler and editActionHandler callbacks will not be called for these actions.
-
First you can get a node template from the canvas by calling
-
-which returns the node template based on the node ID. This can be useful if you have supernodes in your palette because supernodes do not have an op field. After creating the node template your code can alter fields (for example, the label) within the template. If you do change any fields be careful because Common Canvas doesn’t do any error checking on your fields.
-
This method allows the host application to create a node, or supernode, from a palette template object by creating and executing a command which will be added to the command stack (so the user can undo / redo it) and will also cause the beforeEditActionHandler and editActionHandler callbacks to be called.
-
First your code retrieves a node template from the palette as described above and then calls this method:
-
Note: If pipelineId is omitted the node will be created in the current “top-level” pipeline.
-
Creating and adding a node using Pipeline Flow document¶
-
This approach works by your code adding one or more JSON objects directly to the pipeline flow object, either before the pipeline flow document is loaded into Common Canvas using CanvasController.setPipelineFlow(pFlow), or afterwards by retrieving the pipeline flow object from Common Canvas using CanvasController.getPipelineFlow() and then updating the nodes array of whichever pipeline you want to modify. This would require your code to navigate to the pipeline object (that you want to update) in the pipelines array of the pipeline flow and then add the node object to the nodes array in the pipeline object.
-
After updating the pipeline flow object your code would need to reload it into Common Canvas using CanvasController.setPipelineFlow(pFlow).
Notification messages are displayed in the notification panel which the user can access by clicking the Notifications button in the toolbar. The application specifies an array of messages using the notification methods in the canvas controller. The appearance of the panel is customized in the Notification Config.
-
The application passes to Common Canvas an array of messages each described by a simple JavaScript object like this:
-
id (string, required): this is a unique ID assigned to the notification message. This is passed as a parameter in the callback (see below) and is used to reference messages when deleting them through the CanvasController API.
-
-
-
type (string, required): this must be one of four values: “info”, “success”, “warning”, or “error”. If type is null, empty string, or undefined, the message type will be “unspecified”.
-
-
-
title (string or JSX object): the title of the notification message.
-
-
-
content (string or JSX object): the body of the notification message.
-
-
-
callback (function): an optional callback function that will be called when the notification message is clicked. Callback function is called with one parameter, id
-
-
-
timestamp (string or JSX object): an optional timestamp that will be rendered in a separate section with different formatting, if passed in
-
-
-
closeMessage (string or React object): an optional message that, if passed in, will display as clickable. Clicking on this will delete this individual message. If none is passed in, no delete option will be shown.
There are multiple was to specify the styles for the objects Common Canvas displays:
-
-
A class name can be provided for nodes either within the pipelineFlow document or
-
The common-canvas default styes can be overriden within your CSS or SCSS file
-
-
For more precise styling of objects the style specification object can be used to provide a number of styles to Common Canvas to set the inline styles on numerous elements of an object. For example, a node is made up of: a selection outline; a node body (rectangle); an image, a label etc.
-
Style specifications may be applied to common-canvas objects using the following Canvas Controller methods:
-
<css_snippet> - is a string containing any CSS code that can be added inline to an SVG object. That means, for example, you need to use fill and stroke for colors etc It is recommended NOT to change the sizes of text fonts.
-
-
The CSS will be applied to the element of the object specified, either as the default inline style or as the style when the pointer hovers over the object.
-
When a hover style is applied to a graphical element it is applied in addition to the default style so there is no need to repeat styles in the hover <css_snippet> because they will augment the default style.
-
Because styles are applied as in-line styles they will override any styles provided in your application’s CSS and specified to Common Canvas through the class_name field of canvas objects.
-
If the <css_snippet> is specified as null the current style will be removed from the specified element of the object.
-
Finally, styles can be applied to your nodes, comments and links as either temporary or permanent styles by specifying the temporary boolean in the API methods. A temporary style is just applied for the duration of the session and are not persisted. You should use temporary=true styles that represent transient attributes of an object that should not be persisted in the pipelineFlow document. Use temporary=false styles for styles that you want to persist in the pipelineFlow document.
Paste objects from the clipboard. If the mouse cursor is over the canvas, objects will be pasted at the cursor position or, if not, at a default position
-
-
-
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”.
Node layout properties define how all the elements of a node are displayed such as: the position and size of the icon image; the position of the main label; even the shape of the node itself.
-
There are two possible sets of node layout properties provided by Common Canvas, these are controlled by the enableNodeFormatType canvas configuration property which can be set to either “Horizontal” or “Vertical”.
The possible node layout properties are shown below with the values they have when enableNodeFormatType = "Horizontal". You can see the values for both sets of properties by looking at the layout-dimensions.js program
-
-Default node layout fields for Horizontal node format
-
// Default node sizes. These dimensions might be overridden for nodes that have
-// more ports than will fit in the default size if inputPortAutoPosition is.
-// set to true and outputPortAutoPosition is set to true. (See below).
-defaultNodeWidth: 160,
-defaultNodeHeight: 40,
-
-// A space separated list of classes that will be added to the group <g>
-// DOM element for the node.
-className: "",
-
-// Displays the node outline shape underneath the image and label.
-nodeShapeDisplay: true,
-
-// Default node shape. Can be "rectangle" or "port-arcs". Used when nodeOutlineDisplay is true.
-nodeShape: "port-arcs",
-
-// An SVG path or a function that returns an SVG path. The paths define the node
-// shape and its selection highlighting respectively. If set to null, the paths
-// will be set by default based on the nodeShape setting.
-// If these fields are set to functions they will be called in real-time as the node
-// is being sized (provided enableResizableNodes config field is set to true).
-bodyPath: null,
-selectionPath: null,
-
-// Displays the external object specified, as the body of the node
-nodeExternalObject: false,
-
-// Display image
-imageDisplay: true,
-
-// Image dimensions
-imageWidth: 26,
-imageHeight: 26,
-
-// Image position
-imagePosition: "topLeft",
-imagePosX: 6,
-imagePosY: 7,
-
-// Display label
-labelDisplay: true,
-
-// Label dimensions
-labelWidth: 112,
-labelHeight: 19,
-
-// Label position
-labelPosition: "topLeft",
-labelPosX: 36,
-labelPosY: 12,
-
-// Label appearance
-labelEditable: false,
-labelAlign: "left", // can be "left" or "center"
-labelSingleLine: true, // false allow multi-line labels
-labelOutline: false,
-labelMaxCharacters: null, // null allows unlimited characters
-labelAllowReturnKey: false, // true allows line feed to be inserted into label, "save" to make the return key save the label.
-
-// An array of decorations to be applied to the node. For details see:
-// https://elyra-ai.github.io/canvas/03.04.01-decorations/
-// These are added to the node at run time and will not be saved into
-// the pipeline flow.
-decorations: [],
-
-// Positions and dimensions for 9 enumerated default decorator positions.
-// decoratorWidth and decoratorHeight are the dimensions of the outline
-// rectangle and decoratorPadding is the padding for the image within the
-// outline rectangle.
-decoratorTopY: 2,
-decoratorMiddleY: -8,
-decoratorBottomY: -18,
-
-decoratorLeftX: 2,
-decoratorCenterX: -8,
-decoratorRightX: -30,
-
-// Width, height and padding for image decorators
-decoratorWidth: 16,
-decoratorHeight: 16,
-decoratorPadding: 2,
-
-// Width and height for label decorators
-decoratorLabelWidth: 80,
-decoratorLabelHeight: 30,
-
-// Display drop shadow under and round the nodes
-dropShadow: true,
-
-// The gap between a node and its selection highlight rectangle
-nodeHighlightGap: 1,
-
-// The size of the node sizing area that extends around the node, over
-// which the mouse pointer will change to the sizing arrows.
-nodeSizingArea: 10,
-
-// Error indicator dimensions
-errorPosition: "topLeft",
-errorXPos: 24,
-errorYPos: 5,
-errorWidth: 10.5,
-errorHeight: 10.5,
-
-// When sizing a supernode this decides the size of the corner area for
-// diagonal sizing.
-nodeCornerResizeArea: 10,
-
-// What point to draw the data links from and to when enableLinkType is set
-// to "Straight" and enableLinkMethod is set to "Freeform".
-// Possible values are "image_center" or "node_center".
-drawNodeLinkLineFromTo: "node_center",
-
-// What point to draw the comment to node link line to. Possible values
-// are "image_center" or "node_center".
-drawCommentLinkLineTo: "node_center",
-
-// This is the size of the horizontal line protruding from the
-// port on the source node when drawing an elbow or straight connection line.
-minInitialLine: 30,
-
-// For the elbow connection type with nodes with multiple output ports,
-// this is used to increment the minInitialLine so that connection lines
-// do not overlap each other when they turn up or down after the elbow.
-minInitialLineIncrement: 8,
-
-// This is the minimum size of the horizontal line entering the
-// target port on the target node when drawing an Elbow connection line.
-minFinalLine: 30,
-
-// Display input ports.
-inputPortDisplay: true,
-
-// Object for input port can be "circle" or "image".
-inputPortObject: "circle",
-
-// If input port object is "image" use this image.
-inputPortImage: "",
-
-// If input port dimensions for "image".
-inputPortWidth: 12,
-inputPortHeight: 12,
-
-// Indicates whether multiple input ports should be automatically
-// positioned (true) or positioned based on the contents of
-// inputPortPositions array (false).
-inputPortAutoPosition: true,
-
-// An array of input port positions. Each element is structured like
-// this: { x_pos: 5, y_pos: 10, pos: "topLeft" }. x_pos and y_pos are
-// offsets from the pos point on the node.
-// The order of the elements corresponds to the order of ports in the
-// inputs array for the node.
-inputPortPositions: [
- { x_pos: 0, y_pos: 20, pos: "topLeft" }
-],
-
-// The 'guide' is the object drawn at the mouse position as a new line
-// is being dragged outwards.
-// Object for input port guide can be "circle" or "image".
-inputPortGuideObject: "circle",
-
-// If input port guide object is "image" use this image.
-inputPortGuideImage: "",
-
-// Display output ports.
-outputPortDisplay: true,
-
-// Object for output port can be "circle" or "image".
-outputPortObject: "circle",
-
-// If output port object is "image" use this image.
-outputPortImage: "",
-
-// Output port dimensions for "image".
-outputPortWidth: 12,
-outputPortHeight: 12,
-
-// Indicates whether multiple output ports should be automatically
-// positioned (true) or positioned based on the contents of
-// outputPortPositions array (false).
-outputPortAutoPosition: true,
-
-// An array of output port positions. Each element is structured like
-// this: { x_pos: 5, y_pos: 10, pos: "topRight" }. x_pos and y_pos are
-// offsets from the pos point on the node.
-// The order of the elements corresponds to the order of ports in the
-// outputs array for the node.
-outputPortPositions: [
- { x_pos: 0, y_pos: 20, pos: "topRight" }
-],
-
-// The 'guide' is the object drawn at the mouse position as a new line
-// is being dragged outwards.
-// Object for output port guide can be "circle" or "image".
-outputPortGuideObject: "circle",
-
-// If output port guide object is "image" use this image.
-outputPortGuideImage: "",
-
-// Automatically increases the node size to accommodate its ports so both
-// input and output ports can be shown within the dimensions of
-// the node.
-autoSizeNode: true,
-
-// Radius of the either the input or output ports when they are set to "circle"
-portRadius: 3,
-
-// Size of an offset above and below the set of port arcs.
-portArcOffset: 3,
-
-// Radius of an imaginary circle around the port. This controls the
-// spacing of ports and the size of port arcs when nodeShape is set to
-// port-arcs.
-portArcRadius: 6,
-
-// Spacing between the port arcs around the ports.
-portArcSpacing: 3,
-
-// Position of the context toolbar realtive to the node. Some adjustment
-// will be made to account for the width of the toolbar.
-contextToolbarPosition: "topRight",
-
-// Display of vertical ellipsis to show context menu
-ellipsisDisplay: true,
-ellipsisPosition: "topLeft",
-ellipsisWidth: 10,
-ellipsisHeight: 22,
-ellipsisPosX: 145,
-ellipsisPosY: 9,
-ellipsisHoverAreaPadding: 2
-
Node elements are positioned on the node as an x/y offset from one of nine positions:
-
-
The default for most elements is topLeft. The position is useful when nodes are resizable because, as a node is resized, the element will remain tied to its position. So if, for example, an element is tied to topRight and the node is resized to be wider the element will move to remain at the same offset from the topRight position.
-
The PosX and PosY properties for each element is an offset from the associated anchor position where PosX is the number of pixels to the right of the anchor position and PosY is a number of pixels down from the anchor position. Negative values can be provided to specify an offset to the left and up from the anchor position.
-would position the image 10 pixels left and 10 pixels above the very center of the node. Since the image is 20 x 20 pixels this would position the center of the image at the center of the node. If you have enabled re-sizeable nodes, this would keep the image centrally positioned while the node is being resized by the user. Like this:
-
-
Overriding the node layout properties for all nodes¶
-
If you want to change the appearance of all nodes on your canvas you can specify the enableNodeLayout configuration parameter in the canvas configuration object. The properties from this object will replace any properties in the default set, which was chosen based on the settings of enableNodeFormatType. So you don’t need to provide all of the properties; just the ones you want to replace.
-
Let’s say you want your nodes to be displayed as ellipses. You could provide the following settings in enableNodeLayout in the canvas config:
-
Overriding the node layout fields for individual nodes or groups of nodes¶
-
If you want each node, or category of nodes, to have a different layout based on some criteria you can use the layoutHandler callback method. When you specify this callback method to Common Canvas, it will be called for each node on the canvas, during initialization and, occasionally, at other times.
-
The method should return a simple JavaScript object that contains any node layout properties you want to override from the defaults and the ones specified in the enableNodeLayout field in the canvas config.
-
-
Info
-
There are three levels of properties provided where each overrides the previous set:
-
-
First Common Canvas takes the full default set of node layout fields based on the value for enableNodeFormatType.
-
Next Common Canvas overrides these with the fields from the enableNodeLayout object in the canvas config, if any are provided.
-
Finally, Common Canvas overrides the combined set with any fields from the object returned from the layoutHandler method if one is specified, for the node in question.
-
-
-
The callback is provided with a data parameter which is the node object from the pipelineFlow so your code can examine the node object and return node layout properties as appropriate.
-
-
Tip
-
The layoutHandler callback is called while the canvas is being displayed, therefore it must return very quickly each time it is called otherwise your canvas display speed will be slowed down.
-
-
Here is a simple example of a layoutHandler callback method which will override the width of the node based on the width of the main label for any node where the node’s op field is set to Sort:
-
layoutHandler(data){
-letcustomNodeLayout={};
-if(data.op==="Sort"){
-constlabLen=data.label?data.label.length:0;
-constwidth=(labLen*9)+30;// Allow 9 pixels for each character and a bit extra for padding
-customNodeLayout={
-defaultNodeWidth:width// Override default width with calculated width
-};
-}
-returncustomNodeLayout;
-
The four options for enableLinkDirection in the canvas config are “LeftRight”, “RightLeft”, “TopBottom” and “BottomTop”. These will control the default position of the input and output ports at the boundaries of the nodes as follows:
-
-
For “LeftRight” input ports will be on the left of the node and output ports will be on the right of the node
-
For “RightLeft” input ports will be on the right of the node and output ports will be on the left of the node
-
For “TopBottom” input ports will be on the top of the node and output ports will be on the bottom of the node
-
For “BottomTop” input ports will be on the bottom of the node and output ports will be on the top of the node
-
-
The application can customize these port default positions using the enableNodeLayout object in the canvas config. This object has these fields for port placement customization:
-
-
inputPortAutoPosition and inputPortPositions to customize input ports and
-
outputPortAutoPosition and outputPortPositions to customize output ports.
If nodes are set to be resizeable (enableResizableNodes set to true) and the nodes is resized it will look like this, because the second port is tied to the “bottomLeft” position:
-
-
When ports are positioned on the node, regardless of whether they are positioned by default or have customized positions, they are assigned one of four ‘directions’ that links will be drawn to/from. These directions are dependent on the diagonal quadrant of the node the port is positioned within.
-
As an extreme example, if these fields are used to customize a node with four input ports (black circles) and four output ports (blue arrows) like this:
-
-
Common Canvas will assign a direction to the input and output ports are follows:
-
-
If the config field enableLinkMethod is set to “Ports”, and enableLinkType is set to “Curve”, the links will be drawn as follows:
-
-
This means an application like the one shown below can be built, where the links exit from the left of the ‘Inp_1’ node and point to the ‘Stage Variables’ node below it. Meanwhile, other links exist the ‘Inp_1’ node on its right and point to the ‘Out_2’ node. This is achieved by positioning some (invisible) output nodes on the left of ‘Inp_1’ and some on the right of ‘Inp_1’. Common Canvas takes care of drawing the links in the appropriate direction based on the port positions.
For most flows, nodes are defined with an image (icon) that conveys the purpose of the node. They are displayed for the nodes in the flow and the palette. The nodes image can be provided as a URL or JSX object. Images can also be customized using node layout fields.
Typically, the image field of a node object in the pipeline flow (or palette) is a URL that references an image file on the server. This can be any type of image that can be displayed in an <image> tag however, if the file is recognized as an SVG file by having the .svg extension, the contents of the file will be loaded as inline SVG in the DOM. This allows more image customization using CSS.
-
The loading and management of images can be controlled using the enableImageDisplay canvas config field.
-
-
Data URLs
-
Data URLs can be used to embed an image file within the pipeline flow JSON however, this is not recommended for production use since it leads to bloated pipeline flow files because of the amount of data stored for each image and the repetition of images across multiple nodes of the same type.
-
-
-
Alternative palette image
-
The node definition contains a palette image field which, if specified, will be displayed as the node’s image only on the palette.
Images can also be provided to Common Canvas as JSX objects. This means, for example, that the application can provide Carbon icons as node images in the palette and on the canvas. Since JSX objects cannot be stringified, the application must programmatically set the node image field to reference the appropriate JSX object.
-
Also, when data is retrieved from Common Canvas using either canvasController.getPipelineFlow() or canvasController.getPaletteData(), the returned node object will not contain any image information.
-
The node image can be set something like this (where “123” is the node Id):
-Alternatively, JSX images can be injected directly into the pipeline flow object or palette object before it is provided to Common Canvas.
-
-
Size prop
-
Note, the size prop is used when the icon is displayed in the palette however for a node in the flow the icon will be sized based on the imageHeight and imageWidth fields in the nodeLayout object specified in the enableNodeLayout field of the canvas config object.
-
-
Also, when nodes are pasted into the canvas the application will need to ensure the image fields of those nodes are set appropriately.
-
A new sample application called ‘JSX Icons’ has been added to the test harness to show Carbon icons being used as node images.
Node elements are drawn as SVG elements in the SVG area provided by the Flow Editor and are grouped together using a group <g> element.
-
-
The DOM elements that make up a node can be customized using CSS styles. This is done by either overriding the common-canvas CSS directly or, if customization is needed on a node-by-node basis, by assigning a class name to the group <g> element that is the container for all the node elements. The class can be applied to the group object in a number of different ways:
-
-
By specifying it in the app_data.ui_data.class_name field of the node in the pipeline flow document that is provided to Common Canvas using CanvasController.setPipelineFlow(pFlow)
By specifying a class name in the className field of the node layout properties returned from the layoutHandler.
-
-
You can see the svg-canvas-d3.scss file for full details about what elements in the node can be styled but here are a list of some basic parts of the node:
Classes specified for the node in the class_name field of the node object will be added here.
-
-
-
⮕ Selection area
-
path
-
d3-node-selection-highlight
-
-
-
-
⮕ Outline shape
-
path
-
d3-node-body-outline
-
-
-
-
⮕ Image
-
svg
-
d3-node-image
-
-
-
-
⮕ Label
-
foreignObject
-
d3-foreign-object-node-label
-
Will contain a div that contains the label text
-
-
-
⮕ Input port
-
g
-
d3-node-port-input
-
-
-
-
⮕ Output port
-
g
-
d3-node-port-output
-
-
-
-
⮕ Decorations
-
g
-
d3-node-decorations-group
-
Will contain decoration elements, for example, image, path etc
-
-
-
-
So for example if you want the node body (the rectangle) to be colored orange you would provide a class name to the group element using one of the techniques mentioned above and then put this in you CSS:
-Note: You can use the enableParentClass canvas config field to make you CSS rulesets specific so your styles are picked up in preference to the common-canvas default styles.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
Comment elements are drawn as SVG elements in the SVG area provided by the Flow Editor and are grouped together using a group <g> element.
-
-
The DOM elements that make up a comment can be customized using CSS styles. This is done by either overriding the common-canvas CSS directly or, if customization is needed on a comment-by-comment basis, by assigning a class name to the group <g> element that is the container for all the comment elements. The class can be applied to the group object in a number of different ways:
-
-
By specifying it in the app_data.ui_data.class_name field of the comment in the pipeline flow document that is provided to Common Canvas using CanvasController.setPipelineFlow(pFlow)
You can see the svg-canvas-d3.scss file for full details about what elements in the comment can be styled but here are a list of some basic parts of the comment:
Classes specified for the comment in the class_name field of the node object will be added here.
-
-
-
⮕ Sizing area
-
path
-
d3-comment-sizing
-
-
-
-
⮕ Selection area
-
path
-
d3-comment-selection-highlight
-
-
-
-
⮕ Background
-
path
-
d3-comment-rect
-
-
-
-
⮕ Text
-
foreignObject
-
d3-foreign-object-comment-text
-
Will contain a div that contains the comment text
-
-
-
⮕ Decorations
-
g
-
d3-comment-decorations-group
-
Will contain decoration elements, for example, image, path etc
-
-
-
-
Note: You can use the enableParentClass canvas config field to make you CSS rulesets specific so your styles are picked up in preference to the common-canvas default styles.
Overriding node port locations to customize link drawing direction¶
-
When enableLinkMethod is set to “Ports”, the positions of ports on nodes affect the direction that links are drawn to/fom the ports. See this overriding port positions section in the node customization page for more details.
Links are drawn on the canvas using SVG elements in the DOM. Each link has a top level group <g> element and inside it some SVG paths. The first displayed path is the selection area. This is invisible but provides a selection/hover area for mouse interactions on the link. The second is a path to represent the link itself which is drawn over the top of the selection area path:
-
-
The DOM elements that make up a link can be customized using CSS styles. This is done by either overriding the common-canvas CSS directly or, if customization is needed on a link-by-link basis, by assigning a class name to the group <g> element that is the container for all the link elements. The class can be applied to the group object in a number of different ways:
-
-
By specifying it in the app_data.ui_data.class_name field of the link in the pipeline flow document that is provided to Common Canvas using CanvasController.setPipelineFlow(pFlow)
You can see the svg-canvas-d3.scss file for full details about what elements in the comment can be styled but here are a list of some basic parts of the comment:
Classes specified for the link in the class_name field of the link object will be added here.
-
-
-
⮕ Selection area
-
path
-
d3-link-selection-area
-
-
-
-
⮕ Link line
-
path
-
d3-link-line
-
-
-
-
⮕ Arrow head
-
path
-
d3-link-line-arrow-head
-
Only when enableLinkType is set to “Straight”
-
-
-
⮕ Decorations
-
g
-
d3-link-decorations-group
-
Will contain decoration elements, for example, image, path etc
-
-
-
-
Note: The main link group will also have one of these classes: d3-node-link (for data links), d3-object-link (for association links) or d3-comment-link (for comment links).
-
Note: You can use the enableParentClass canvas config field to make you CSS rulesets specific so your styles are picked up in preference to the common-canvas default styles.
If a data link is retrieved from the canvas controller API it will have the following important fields:
-
-
id - the unique identifier for the link.
-
type - set to “nodeLink”.
-
srcNodeId - the ID of the node the link is connected from.
-
srcNodePortId - the ID of the output port on the source node the link is connected from. Note: If this is undefined it indicates the node is connected to the first output port of the source node.
-
trgNodeId - the ID of the node the link is connected to.
-
trgNodePortId - the ID of the input port on the target node the link is connected to. Note: If this is undefined it indicates the node is connected to the first input port of the target node.
-
decorations - an array of decorations specified for the link.
-
app_data - any application specific data that was previously specified for the link in the pipeline flow or through the canvas controller API.
-
-
Note: Typically data links must be drawn between nodes however, if the config field enableLinkSelectionType is set to Detachable, the links are allowed to be drawn to and/or from arbitrary points on the canvas. If a link is drawn either semi-detached (from one node) or fully-detached (from both nodes) the following fields will be in the link object:
-
-
srcPos - this is an object with two fields x_pos and y_pos. These provide the coordinates of the point on the canvas that the link is drawn from. If this exist then srcNodeId and srnNodePortId are not specified in the link object.
-
trgPos - this is an object with two fields x_pos and y_pos. These provide the coordinates of the point on the canvas that the link is drawn to. If this exist then srcNodeId and srnNodePortId are not specified in the link object.
(Note : internally, association links do have a srcNodeId and trgNodeId but that is just to keep the field names consistent with the data links.) Association links do not reference ports.
-
If an association link is retrieved from the canvas controller API it will have the following important fields:
-
-
id - the unique identifier for the link.
-
type - set to “associationLink”.
-
srcNodeId - the ID of one of the nodes in the association.
-
trgNodeId - the ID of the other node in the association.
-
decorations - an array of decorations specified for the link.
-
app_data - any application specific data that was previously specified for the link in the pipeline flow or through the canvas controller API.
Common Canvas supports the ability for an object from the your browser page to be dragged onto the canvas to initiate the creation of a node on the canvas. To do this you need to set the object you want to drag into the canvas to be draggable:
data - is the object that will be passed to the editActionHandler callback
-
editType - this is the type of editing operation. You can set it to anything except any of the reserved settings which are: ‘createNode’, ‘createNodeOnLink’, ‘createAutoNode’ and ‘createFromExternalObject’.
-
fields - an optional number of fields can be provided that describe the object you are dragging onto the canvas. For example, if it is a data object the fields might describe the data source details.
-
-
After the object has been dropped on the canvas your editActionHandler() callback method will be called with a parameter data object that contains the fields you specified in data in the drag data along with three additional fields, called pipelineId, offsetX and offsetY, containing the x,y co-ordinates of where the drop occurred. In your editActionHandler() method you can use the CanvasController API to add a node to the pipeline flow and get Common Canvas to display it.
-
Dragging object from the desktop or another application¶
-
If an object from the desktop or another application is dropped on the canvas your editActionHandler(data) method will be called with the data parameter set to an object like this:
-
-Your code can examine the dataTransfer object to see what object was dragged onto the canvas and then take appropriate action.
-
If you want a new node to appear on the canvas as a result of the object being dropped your code will need to create that node at the point where the drop occurred, using the Canvas Controller API. Here is some sample code that will
-
-
create a new node template based on the “variablefile” node in the palette data
-
set the label of the node to be created to the name of the file being dropped
-
create a new node on the canvas at the offsetX, offsetY position
-
the command will be added to the command-stack so the user can click undo to undo the addition of the node
-
-
data is the parameter passed into your editActionHandler method.
-
Tip: You can optionally instruct Common Canvas to display a graphic over the canvas as the external object is being dragged over it. To do this you need to specify the enableDropZoneOnExternalDrag configuration parameter.
The pipeline flow schema describes two ways of storing a sub-flow pipelines for a supernode: local or external. Local sub-flows are stored within the pipeline flow document whereas external pipelines are stored in a separate pipeline flow document (usually as the primary pipeline in that pipeline flow). The supernode that references an external pipeline contains a url property (in <node>.subflow_ref.url) and a pipeline ID property (in <node>.subflow_ref.pipeline_id_ref) to identify the external pipeline flow and the pipeline within it.
-
Common Canvas supports external pipelines but the host application UI code needs to manage the storage and retrieval of any external pipeline flows. To do this the app UI code needs to:
-
-
Manage the storage of newly created external pipeline flows.
-
Respond to calls from Common Canvas to provide the external pipeline flow(s) when requested.
-
Respond to call from Common Canvas when a local pipeline is changed to external or an external is changed to local.
-
-
Common Canvas supports lazy loading of external pipeline flows so they will only be requested from your code when the user performs some gesture that requires the pipeline (from within the external pipeline flow) to be displayed.
When the common-canvas config property enableExternalPipelineFlows is set to true (the default) and, when a set of objects are selected from which a super node can be created, the default common-canvas context menu will include a Create External Supernode option.
-
When the Create External Supernode option is clicked the createSuperNodeExternal action is executed.
-
If your application doesn’t use the default context menu you can define your own context menu (returned from contextMenuHandler) to contain an option which maps to the createSuperNodeExternal action. See the section on the contextMenuHandler for details on how to do this.
-
When the createSuperNodeExternal action is executed, the beforeEditActionHandler callback is called before the external sub-flow is created. The beforeEditActionHandler is called where the first parameter data has two properties externalUrl and externalPipelineFlowId which will both be set to empty string. Your code must set these to whatever values you want for the url and pipeline flow ID. The url will be assigned to the subflow_ref.url property of the supernode that is being created. The pipeline flow ID will be assigned to the newly created pipeline flow.
-
Your code must return the data parameter from the beforeEditActionHandler callback if you want the action to proceed and create the sub-flow. If you need to do any asynchronous activity at this point see the documentation on the beforeEditActionHanlder for details on how to do that.
-
When the sub-flow has been created, Common Canvas will call the editActionHandler callback with the createSuperNodeExternal action. In this callback you can, if you wish, retrieve the pipeline flow document that has been created internally in Common Canvas using CanvasController.getExternalPipelineFlow(url). Your code can then save it to your repository. Alternatively, you can wait until some later time, like perhaps during an auto-save, to retrieve and store the pipeline flow externally in your repository.
When the main pipeline flow, displayed by Common Canvas, contains a super node that references an external sub-flow it will need to be loaded whenever the user performs a gesture that causes it to be displayed or processed in some way - for example displaying it ‘in-place’ or converting it from an external to a local supernode. An external sub-flow will also need to be loaded if the top-level pipeline being displayed has a supernode, that refers to an external pipeline, that is already expanded in-place in the saved pipeline flow JSON document being displayed. So, actions that can cause the external pipeline to be loaded are:
-
-
loadPipelineFlow
-
expandSuperNodeInPlace
-
displaySubPipeline
-
convertSuperNodeExternalToLocal
-
deconstructSuperNode
-
-
When any of these actions are performed Common Canvas will call the beforeEditActionHandler callback with the data parameter as the first parameter. The data object will have the following properties:
-
-
editType - The name of the action being performed.
-
externalPipelineFlowLoad - This is a boolean which indicates whether the pipeline flow needs to be provided by your code.
-
externalUrl - This is the string which identifies the external pipeline flow document.
-
externalPipelineId - This is the ID of the pipeline being loaded
-
externalPipelineFlow - If externalPipelineFlowLoad if true this will be undefined. Otherwise it will be contain the previously loaded external pipeline flow.
-
-
You need to implement the beforeEditActionHandler so that:
-
-
when the actions above are being performed and externalPipelineFlowLoad is true, you retrieve the external pipeline flow from your repository
-
you then assign it to the externalPipelineFlow property of the data object
-
you then return the data object from the callback.
-
-
Your code must return the data parameter from the beforeEditActionHandler callback if you want the action to proceed and load the external pipeline flow. If you need to do any asynchronous activity at this point see the documentation on the beforeEditActionHanlder for details on how to do that.
-
Converting a local supernode to an external supernode¶
-
When the common-canvas config property enableExternalPipelineFlows is set to true, and a local supernode’s is right clicked, the default common-canvas context menu will include a Convert local to external option. This will execute the convertSuperNodeLocalToExternal action.
-
The convertSuperNodeLocalToExternal action is similar to the createSuperNodeExternal action in that a new external pipeline flow is being created. Consequently, you can follow the instructions in the Creating an external sub-flow section for providing the appropriate properties of the data object in the beforeEditActionHandler and editActionHandler callbacks.
-
Converting an external supernode to a local supernode¶
-
When the common-canvas config property enableExternalPipelineFlows is set to true, and an external supernode’s is right clicked, the default common-canvas context menu will include a Convert external to local option. This will execute the convertSuperNodeExternalToLocal action.
-
The convertSuperNodeExternalToLocal action is similar to the expandSuperNodeInPlace action in that an external pipeline flow may need to be retrieved from your repository. Consequently, you can follow the instructions in the Loading an external sub-flow section for providing the appropriate properties of the data object in the beforeEditActionHandler callback.
When the user deletes an external supernode/sub-flow the supernode will be removed from the canvas. You code does not need to do anything unless you want to also remove the external pipeline flow from your repository.
When a supernode, that refers to an external pipeline, is cut/copied and pasted, the pasted supernode refers to the same external pipeline as the supernode that was cut or copied. This means that if an external supernode is copied to the clipboard and then pasted into the same canvas the result will be two supernodes that refer to the same external pipeline.
-
The same situation can occur if a supernode, that refers to an external pipeline, is in the palette and that node is dragged multiple times from the palette onto the canvas.
-
Manipulating objects in external pipelines using the Canvas Controller API¶
-
Objects (nodes, links comments, etc.) in an external pipeline can be updated by the host application calling the CanvasController API. However, such changes are only effective within Common Canvas. It is the host application’s responsibility to make sure these changes are persisted in the external pipeline flow document (if that is the behavior that is required). This can be done by the host application calling CanvasController.getExternalPipelineFlow(url) and then saving the returned document to the appropriate repository.
-
External pipelines in the Elyra Canvas Test Harness¶
-
The Test Harness supports external pipeline flows but will only persist any saved flows for the current session. (It just stores them in memory). You can examine the beforeEditActionHandler and editActionHandler in App.js in the test harness to see how it handles the different actions for managing external pipeline flows.
Some host applications need to display flows that cannot be edited by the user. This might be because the flow artifact is currently being edited by another user (locked) or because the user does not have authority to edit the flow (read-only) or some other reason. We’ll use the term ‘read-only’ below to refer to both locked and read-only canvases.
-
There are many aspects of common-canvas components that need to be considered for a read-only canvas. Since Common Canvas is highly customizable it is not possible for the common-canvas code to manage components of the canvas that have been customized by the host application. For example, if the host app code added tools to the toolbar, Common Canvas does not know whether those tools should be disabled when displaying a read-only canvas or not. So the host application code will need to manage that. Let’s look at each element of Common Canvas and see what needs to be done.
There is one main canvas configuration property that will change the common-canvas behavior to implement a read-only canvas. This is enableEditingActions which defaults to true and needs to be set to false for read-only canvases. The sections below will cover what effect this will have on the different components of Common Canvas and what you need to do for any customizations you have made.
Setting enableEditingActions to false will prevent nodes and comments (and detachable links) from being moved relative to one another. It will also prevent new links from being created and prevent text (like comments or node labels) from being edited.
-
With enableEditingActions set to false, the canvas can still be panned (left/right and up/down) and also zoomed in and out. Nodes, comments and links can still be clicked (to select) and right clicked (to display a context menu) and double clicked (usually to show properties). If you implemented any behavior for these interactions, using the clickActionHandler, you’ll need to review what your code is doing and make sure it is appropriate when a read-only canvas is being displayed.
-
Common Canvas allows objects from outside the canvas to be dropped onto the canvas to create a new node. For example, a file can be dragged from the operating system desktop onto the canvas to create a data node. With enableEditingActions set to false, the drag/drop gesture (which Common Canvas cannot prevent) will prevent a new node from being created. It is recommended you switch the enableDropZoneOnExternalDrag config property to false when displaying a read-only canvas. This will prevent a ‘drop zone’ graphic from appearing over the canvas when the object is dragged over the top of the canvas.
-
Some applications need to show a tag (called a ‘state tag’) over the canvas to emphasize the ‘read-only’ or ‘locked’ state of the canvas. This can be displayed using the enableStateTag canvas config property. The tooltip of the ‘state tag’ can be provided by implementing the tipHandler callback function.
-
Since there are numerous possible styles for nodes and links when displaying a read-only canvas, it isn’t possible for Common Canvas to style the canvas objects appropriately for all different designs. You will need to override any styles for nodes and links to fit your design. To help with this, Common Canvas sets a class called config-edit-actions-false on the top-level div that contains the common-canvas components. You can use this to build specific selectors in your CSS/SCSS that will override the styles applied to nodes and links by default. For example, to override node icon and label colors you could specify the following in your SCSS file:
-
Setting enableEditingActions to false will prevent any options, that would edit the canvas objects, from being displayed in the common-canvas default context menu. For example, Delete will not show up in the context menu. See the enableEditingActions documentation for a list of options that are disabled.
-
Your application code can add your own options to the context menu by implementing the contextMenuHandler callback function. If you have added your own options, you should review your code and ensure options that might change the canvas objects are not added to the context menu when you are displaying a read-only canvas.
-
Note: The common-canvas default menu, passed as the second parameter to the contextMenuHandler callback, will still contain editing options. This means, if your code relies on them for some reason, (for example for calculating the position of your added options) your application code will still work OK. The editing options will be removed after your code returns the array of items that describe the desired menu from the contextMenuHandler callback.
The toolbar can display buttons for standard common-canvas actions and also buttons for any application-specific actions added by your code. Setting enableEditingActions to false will cause buttons for any standard common-canvas actions, that edit the canvas objects, to be disabled regardless of the setting for the enable property for each action. See the enableEditingActions documentation for a list of actions that are disabled.
-
You should review any application-specific action buttons you have added to the toolbar and decide if they need to be disabled or removed from the toolbar when displaying a read-only canvas.
-
If you decide you want to hide the toolbar, this can be achieved using the enableToolbarLayout canvas config field.
Common Canvas supports a number of keyboard shortcuts. Setting enableEditingActions to false, disables any keyboard shortcuts that edit the canvas objects (such as Delete). See the enableEditingActions documentation for a list of keyboard shortcuts that are disabled.
prevents node templates from being dragged from the palette and
-
disables the double-click action on node templates which automatically adds a node to the canvas.
-
-
You should decide if your application should display the palette when displaying a read-only canvas or not. The palette can be hidden by setting the canvas config property enablePaletteLayout to “None”.
Common Canvas allows the application to display a state tag, which is a label displayed directly on top of the canvas to allow the application to indicate what state (read-only or locked) the flow is in. The state tag can be switched on using the enableStateTag canvas configuration field.
The test harness contains a sample application called “Read-Only” which shows how a read-only canvas can be built using the enableEditingActions config option. In the application there are three toolbar buttons which can be used to navigate between Editable state, Read-Only state and Locked state. You can review the .jsx and .scss files in the application code to see how the application is implemented and styled.
The Command Stack is built into Common Canvas and automatically provides functionality to support do/undo/redo of commands performed in the flow editor. In addition, if needed, applications can add their own commands to the command stack.
-
The Command Stack maintains an internal stack of commands with a cursor that moves up and down when commands are undone or redone. Commands are JavaScript classes that implement a simple interface.
-
The canvas controller automatically creates an instance of the command stack. Common Canvas provides command objects for each of the commands that are performed by the user, such as: create node, delete comment, link nodes together, etc. which it adds to the command stack.
-
To allow the user to activate the undo and redo actions, Common Canvas provides:
-* undo/redo buttons on the default toolbar and
-* undo/redo options in its default context menu for the flow editor background,
-* keyboard shortcuts: ctrl+z (undo) and ctrl+shift+z (redo) when keyboard focus is on the canvas.
-
If the applicaiton specifies its own canvas toolbar or its own context menu/toolbar for the flow editor canvas and it must include defintions for the undo and redointernal actions.
- Note that the command has to keep a reference to the new node to allow the node to be added back
- to the canvas in redo() even though it was deleted in undo().
-
Here is an example showing how to create a command action and push it on the stack using the canvas-conttoller:
Some of the internal action classes have been exported from Common Canvas and can be extended with additional
-functionality, if necessaey. The classes that are exported are:
-
-
CreateAutoNodeAction
-
CreateNodeAction
-
CreateNodeLinkAction
-
DeleteObjectsAction
-
DisconnectObjectsAction
-
PasteAction
-
-
The constructors for these classes all take the same two parameters. The data object that descrbes the command
-and a reference to the canvas controller.
-
Applications can extend these classes to augment their basic behavior with application specific behavior. It is the application’s responsibility to add the extended object to the command stack when the user performs the corresponding action.
-
Although there are no plans to alter the internal workings of these six command action classes, there is always the chance that a change in the future might alter a field name or two. If you extend these classes, it is therefore recommended that you have sufficient regression tests for your extensions that would highlight such a problem, should it occur.
Internal actions can be generated by the user either:
-
-
Clicking a toolbar button or
-
Clicking an option in a context menu or context toobar or
-
Pressing a keyboard shortcut key(s) or
-
Doing some direct manipulation like dragging one or more objects
-
-
Some actions can be generated from different sources. For example, the deleteSelectedObjects action can be generated by the user:
-
-
Clicking the trash can icon in the toolbar or
-
Pressing the Delete key or
-
Clicking the Delete option in a context menu.
-
-
In each case, the action generates calls to the beforeEditActionHandler callback and then the editActionHandler callback. For each callback, the editType field of the first parameter will be set to one of the actions listed below.
-
These are the intenal actions:
-
-
-
-
Action Name
-
Notes
-
-
-
-
-
Nodes
-
-
-
-
createNode
-
Create a new node on the canvas at a location identifed by the user
-
-
-
createNodeOnLink
-
Creates a new node and inserts it into a link the palette node was dropped on
-
-
-
createNodeAttachLinks
-
Creates a new node and attaches it to the detached link the palette node was dropped on
-
-
-
createAutoNode
-
Creates a node at an appropriate position and, if possible, make a connection to an adjacent node
-
-
-
insertNodeIntoLink
-
Inserts a node from the canvas into the link it was dropped on
-
-
-
attachNodeToLinks
-
Attaches a node to one or more detached links it was dropped on
-
-
-
setNodeLabel
-
Sets the node label
-
-
-
setNodeLabelEditingMode
-
Puts a node label into eiting mode
-
-
-
disconnectNode
-
Removes all links to the selected node
-
-
-
Supernodes
-
-
-
-
createSuperNode
-
Creates an internal supernode
-
-
-
createSuperNodeExternal
-
Creates an external supernode
-
-
-
deconstructSuperNode
-
Removes a supernode and puts its contents into the canvas in its place
-
-
-
expandSuperNodeInPlace
-
Expands a supernode to view the sub-flow in-place
-
-
-
collapseSuperNodeInPlace
-
Collapses an in-place supernode to a regular node size
-
-
-
convertSuperNodeExternalToLocal
-
Converts an external supernode to an internal one
-
-
-
convertSuperNodeLocalToExternal
-
Converts an internal supernode to an external one
-
-
-
displaySubPipeline
-
Displays a sub-flow in full-page mode so it fills the viewport
-
-
-
displayPreviousPipeline
-
Displays the parent flow from the one currently being viewed
-
-
-
loadPipelineFlow
-
Loads a pipeline from an external source
-
-
-
Comments
-
-
-
-
createComment
-
Creates a new comment on the canvas at a location identifed by the user
-
-
-
createAutoComment
-
Creates a node at an appropriate position on the canvas
-
-
-
commentsToggle
-
Toggles the comments between hide and show
-
-
-
commentsHide
-
Hides all comments on the canvas
-
-
-
commentsShow
-
Shows all comments on the canvas
-
-
-
setCommentEditingMode
-
Puts a comment into eiting mode
-
-
-
Canvas Objects
-
-
-
-
moveObjects
-
Moves one or more selected objects to a new position on the canvas
-
-
-
resizeObjects
-
Resizes a node or comment
-
-
-
setObjectsStyle
-
Sets the style property of one or more nodes/comments
-
-
-
colorSelectedObjects
-
Colors the background of the selected objects
-
-
-
deleteSelectedObjects
-
Deletes the selected objects
-
-
-
selectAll
-
Selects all canvas objects
-
-
-
Links
-
-
-
-
updateLink
-
Updates the link info for detached links
-
-
-
editComment
-
Changes the comment text, position and dimension info
-
-
-
linkNodes
-
Creates a link between two nodes
-
-
-
linkNodesAndReplace
-
Creates a link between two nodes and relaces any exiting link to the target node
-
-
-
linkComment
-
Creates a link from a comment to a node
-
-
-
createDetachedLink
-
Create a link from a node to a point on the canvas
-
-
-
setLinksStyle
-
Sets the style property of one or more links
-
-
-
deleteLink
-
Deletes a link
-
-
-
Decorations
-
-
-
-
editDecorationLabel
-
Puts a label decoration into edit mode
-
-
-
Arrange nodes
-
-
-
-
arrangeHorizontally
-
Arranges the nodes across the page from left to right
-
-
-
arrangeVertically
-
Arranges the nodes down the page from top to bottom
-
-
-
Palette
-
-
-
-
paletteToggle
-
Toggles the palette between opened and closed
-
-
-
paletteOpen
-
Opens the palette (left flyout)
-
-
-
paletteClose
-
Closes the palette (left flyout)
-
-
-
saveToPalette
-
Saves the selected object into the palette
-
-
-
Notifications
-
-
-
-
toggleNotificationPanel
-
Toggles the notification panel between opened and closed
-
-
-
openNotificationPanel
-
Opens the notification panel
-
-
-
closeNotificationPanel
-
Closes the notification panel
-
-
-
Clipboard
-
-
-
-
cut
-
Cuts the selected canvas objects onto the clipboard
-
-
-
copy
-
Copies the selected canvas objects onto the clipboard
-
-
-
paste
-
Pates the contents of the clipboard onto the canvas
-
-
-
Command Stack
-
-
-
-
undo
-
Undoes the previous command on the command stack
-
-
-
redo
-
Redoes the next comment on the command stack
-
-
-
Highlighting
-
-
-
-
highlightBranch
-
Highlights all upstream and downstream nodes from the one selected
-
-
-
highlightDownstream
-
Highlights all upstream and downstream nodes from the one selected
-
-
-
highlightUpstream
-
Highlights all upstream and downstream nodes from the one selected
-
-
-
unhighlight
-
Unhighlights all previously highlighted nodes
-
-
-
Zoom
-
-
-
-
zoomIn
-
Zooms the canvas in by one step
-
-
-
zoomOut
-
Zooms the canvas out by one step
-
-
-
zoomToFit
-
Zooms so all the canvas objects are visible in the viewport
-
-
-
setZoom
-
Sets the zoom based on the enableSaveZoom config setting
If you use any of the following action names, Common Canvas will automatically display an appropriate Carbon icon for that action either if it appears as a button in the toolbar or if it appears in the overflow menu.
This function is deprectated and will be removed in future release¶
-
Carbon 11 has a context menu component if your applications needs a context menu.
-
The context menu in Common Canvas can be used in your application by importing the ContextMenuWrapper React component. Aside from providing a standard context menu to allow users to select different actions, this context menu also allows for configuration of submenus as a menu item, as well as a visual dividers.
To use Context Menu Wrapper in your React application you need to import the ContextMenuWrapper React component from the common-canvas library. It’s recommended to use All Components if Common Canvas is also being imported, otherwise use ContextMenuWrapper only option.
containingDivIdstring (required): the id of the element that the context menu will be absolutely positioned inside. typically, the page element is used.
-
-
contextMenuPosobject (required): the position of the context menu within the containing div.
-
constmenuPos={x:500,y:300};
-
-
-
-
contextMenuActionHandlerfunc (required): this handler is where context menu actions are defined.
-
closeContextMenufunc (required): this handler will be called when the context menu is closed.
-
stopPropagationbool (optional): this is optional and only for very specific, uncommon use cases. When this flag is set, if a user clicks outside the context menu, the event will not bubble to parent elements, preventing parent event handlers from being called.
This function is deprectated and will be removed in future release¶
-
The Flow Validation API allows application code to programmatically validate the nodes in the flow against it’s property values. The API can be invoked after setting the Canvas Controller pipeline flow, when opening a new flow, or associated with a canvas context menu item. To use the Flow Validation API import the FlowValidation object from Common Canvas:
-
import { FlowValidation } from "@elyra/canvas";
-
-then call the API on the object, for example:
-
FlowValidation.validateFlow( ... );
-
-
The Flow Validation object provides the following API:
-
validateFlow(canvasController, parameterDataCallback, setNodeMessagesCallback, includeMsgTypes)
- canvasController - an instance of the canvas controller
- parameterDataCallback – function to get the parameter data or form data for a node
- setNodeMessagesCallback – function to set the validation messages for a node. (optional)
- includeMsgTypes - array[strings] Return invalid only if messages are found of types contained
- in the array. If not specified then any message type causes invalid return. (optional)
- return - boolean If flow is valid returns true, otherwise returns false.
-
-where the two callbacks are defined as follows:
-
parameterDataCallback(nodeId)
- nodeId – string node Id.
- function must return this object:
- {
- type: “parameterDef” | “form”,
- data: Json_object
- }
-
-/* The setNodeMessagesCallback is optional and only useful if not using internal object model.
-setNodeMessagesCallback(nodeId, messages)
- nodeId – string node Id.
- an array of message objects generated from the validation of the node.
-
-
The validateFlow() API will traverse the current flow and for each node invoke the parameterDataCallback() to get with a form data JSON or a parameterDef JSON. It will validate the JSON for the node and store any messages in the node objects within the model. The setNodeMessagesCallback() function will be called with all the messages generated for the node. This is only useful if the application is not using the internal object model.
-The format of the message object is described in Pipeline Flow UI schema
-
Here is an example of using the FlowValidation API to validate a flow on opening:
-
import { CanvasController, FlowValidation } from "@elyra/canvas";
-
-getNodeForm(nodeId) {
- const parameterDef = getParameterDefJSON(nodeId);
- return { type: "parameterDef", data: parameterDef };
-}
-
-setNodeMessages(nodeId, messages) {
- // code to persist messages in a store in addition to the internal model.
-}
-
-openCanvas(canvasJson) {
- const canvasController = new CanvasController();
- canvasController.setPipelineFlow(canvasJson);
- FlowValidation.validateFlow(canvasController, this.getNodeForm, this.setNodeMessages);
-}
-
Common Properties is directed by a JavaScript object called the Parameter Definition. The ‘paramDef’ object describes the properties to be displayed as controls in the <CommonProperties> React object.
-
You can look at the harness/src/client/App.js file to see examples of code that uses the common-properties component.
-
Building a properties panel in a React application¶
-
To use Common Properties in your React application complete the following steps:
Import the Common Properties React component 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 application.
-
import{CommonProperties}from"@elyra/canvas";
-
-Properties Only
-
To import only Common Properties functionality in cjs format use:
Next, you’ll need to populate propertiesInfo, which is a required prop, with:
-
this.propertiesInfo={
-parameterDef:this.parameterDef,// Required - Parameter definitions/hints/conditions
-appData:"{user-defined}",// Optional - User data returned in applyPropertyChanges
-additionalComponents:"{components}",// Optional - Additional component(s) to display
-messages:"[node_messages]",// Optional - Node messages array
-expressionInfo:this.expressionInfo,// Optional - Information for expression builde
-initialEditorSize:"{size}",// Optional - This value will override the value of
-// editor_size in uiHints. This can have a value of
-// "small", "medium", "large", or null
-id:"{id}"// Optional - Unique parameter definition ID
-}
-
-See the Common Properties Parameter Definition page for more details about ‘paramDef’.
-
The optional messages attribute can be used to set validation messages associated with a node. The format of the message objects is defined in Pipeline Flow UI schema
customPanels array: An array of custom panels. See Custom Panels section of the Common Properties Custom Components page.
-
customControls array: An array of custom controls. See Custom Controls section of the Common Properties Custom Components page..
-
customConditionOps array: An array of custom condition operators. See Custom Condition Operators section of the Custom Components page.
-
light boolean: Carbon controls in Common Properties will use light mode. When the light option is disabled, the background color will be the same as the Carbon theme background. When the light option is enabled, the background color is set to $ui-01. Defaults to true
Pass the <CommonProperties> object into the rightFlyoutContent prop of Common Canvas. Also, set the showRightFlyout boolean to tell Common Canvas the rightFlyout should be displayed (true) or hidden (false).
-
The parameter definition object provides input for controlling the common-properties dialog. It consists of information that is available in the operator object combined with UI hints, information on data sets, and resources.
-
The parameter definition has a defined schema and set of examples located here:
-schema and examples
-
The parameter definition consists of the following sections:
A list of input parameters and initial values upon input. The list is a set of key/value pairs with the key being the field name and the value is the initial value.
The list of parameters definitions for this property dialog. The list contains the name of the parameter, the data type of the parameter, the role and the default value. The information provided is as needed by the backend engine, i.e. the parameter name should be the name of the parameter that is expected for the backend engine.
-
The list of parameter definitions has the following attributes:
-
-
id (string) Required Parameter identifier as consumed by the backend engine.
-
default (any) The default value of the parameter.
-
enum (array[string]) A restricted list of string values that are valid for the field.
-
type (string) Parameter type as consumed by the backend engine.
-
role (string) Parameter role, which is an optional specialization of the type.
-
required (boolean) Indication whether parameter is required or optional.
-
-
Parameter types have one of a fixed set of basic types. These are:
-
-
integer
-
double
-
string
-
date
-
time
-
timestamp
-
custom
-
-
These can be used as maps or arrays e.g.:
-
array[<value-type>]:asequenceorlistofvalues
-
-
-
Parameter roles defined by the role attribute can be one of:
-
-
expression: an expression assumed to be in the expression language for the run time
-
column: value represents one or more columns from the data model visible to this operator
-
new_column: value represents the name of a new column to be added to the data model and must therefore not match an existing column and conform to existing syntactic restrictions.
A list of input parameters and initial values upon input. This set of parameters are separated from the backend parameters (current parameters). The idea is that these parameters are not passed into the backend engine by the common-properties consumer.
UI-only parameters require information about the parameters same as the parameter definition information used for the backend parameters. The UI-only parameter definition information is stored in the UI-hints section in the sub-section named ui_parameters. A description of the UI hints specifications can be found on the UI Hints page.
-
UI-only properties are returned to the consuming application via a separate parameter on the applyPropertiesChanges callback. See the Callbacks page.
id (string) Required Identifier of complex type, can be referenced in other places.
-
type (string) If object is specified, Common Properties will return the values as an array of objects consisting of key value pairs. This defaults to array.
-
key_definition (object) A parameter definition attribute on the key parameter field.
-
parameters (object) Required List of parameters fields. Each parameter can be defined as a parameter definition attribute or a complex type attribute.
Note that both parameter and complex type definitions are in the exact same format as defined in the operator schema. Therefore the contents of operator JSON files can be used for these two sections.
A set of specifications for controlling the layout and flow of Common Properties. A description of the UI hints specifications can be found on the UI Hints page.
A set of specifications for controlling validation checking of parameters during the common-properties dialog. A description of the Conditions specifications can be found here on the Conditions page.
The data set metadata is an array of datarecord-metadata objects as defined in the datarecord-metadata JSON schema. Each datarecord-metadata object contains and array of fields that provide column information on the input data set. schema and examples
-
The fields have the following attributes:
-
-
name (string) Required Field name. Must be unique within the dataset.
-
type (string) Required Field type. Can be a primitive type (string, integer, double, date, time, timestamp), or a vector, map, or struct containing those types. Required.
-
nullable (boolean) Indicates whether or not one can place null values into the field. Default: False.
-
metadata (object) A set of additional metadata attributes.
-
-
The additional metadata attributes are as follows:
-
-
description (string) A description of the field.
-
measure (string) The field measurement type. The value can be one of the following. range, discrete, flag, set, ordered-set, typeless, collection, geospatial, default
-
role (string) Field role for modeling. The value can be one of the following.
-input,
-target,
-both,
-none,
-partition,
-split,
-frequency,
-record-id
-
max_string_length (number) Maximum character length for string fields. Length is unlimited when not present.
-
values (array[string]) Array of unique categorical values for the column.
-
ranges (object) Minimum and maximum discovered values for scalar data.
"resources":{
-"org.apache.spark.ml.classification.DecisionTreeClassifier.label":"Random Forest Classifier",
-"org.apache.spark.ml.classification.DecisionTreeClassifier.desc":"Fitted Random Forest Classification Model",
-"inputFieldList.label":"Input columns",
-"inputFieldList.desc":"Select one or more input columns",
-"targetField.label":"Target column",
-"targetField.desc":"Select a target column",
-"max_depth_not_valid":"The max depth parameter must be greater than or equal to zero",
-"max_iter_not_valid":"The max iterations parameter must be greater than or equal to zero",
-"min_instances_per_node_not_valid":"The minimum instances per node value must be >= 1",
-"subsampling_rate_not_valid":"The subsampling rate value must be > 0 and <= 1"
-}
-
Executes when user clicks Save or Cancel in the property editor dialog. This callback is used to control the visibility of the property editor dialog. closeSource identifies where this call was initiated from. It will equal “apply” if the user clicked on “Save” when no changes were made, or “cancel” if the user clicked on “Cancel”
Called when the edit button is clicked on in a readonlyTable control, or if a custom table button is clicked. The callback provides the following data:
-
-
data: an object that consists of
-
type: of button the click was invoked from.
-
edit is returned from the edit button click of a readonlyTable control.
-
custom_button is returned from the custom button click of a complex type control.
-
-
-
propertyId: of the control that was clicked.
-
buttonId: of the button that was clicked from a custom table button.
Called when there is a buttons uihints set in the complex_type_info section of the parameter definition. This buttonIconHandler expects a Carbon Icon jsx object as the return value from the callback. This is used to display the Carbon icon in the custom table button. The buttonIconHandler provides the following data:
-
-
data: an object that consists of
-
type: customButtonIcon
-
propertyId: of the control that was clicked.
-
buttonId: of the button that was clicked from a custom table button.
-
carbonIcon: The name of the Carbon icon specified in the uihints. The corresponding jsx object is expected to be returned in the callback.
Called when a user wants to pass in a specific object to a dropdown menu. The propertyIconHandler expects a jsx object as the return value from the callback. This is used to display the jsx object in the dropdown menu. The propertyIconHandler provides the following data:
-
-data: an object that consists of
- - propertyId: of the dropdown that was selected
- - enumValue: of the dropdown that was selected
Called on properties title change. This callback can be used to validate the new title and return warning or error message if the new title is invalid. This callback is optional.
-
In case of error or warning, titleChangeHandler should call callbackFunction with an object having type and message. If the new title is valid, no need to call the callbackFunction.
-
titleChangeHandler(title,callbackFunction){
-// If Title is valid. No need to send anything in callbackFunction
-if(title.length>15){
-callbackFunction({
-type:"error",
-message:"Only 15 characters are allowed in title."
-});
-}
-}
-
-where:
-
-
type (string, required): This must be one of two values: “warning” or “error”.
-
message(string, required): Error or warning message. There is no restriction on length of the message.
-This is an optional handler you don’t need to implement anything for it unless you want to. This callback allows your code to override the default tooltip text for the Undo and Redo buttons.
-The propertiesActionLabelHandler callback, when provided, is called for the save properties action that is performed in Common Properties. This callback should return a string or null. If a string is returned it will be shown in the tooltip for the Undo button in the toolbar preceded by “Undo:” and the string will also appear in the tooltip for the Redo button (when appropriate) preceded by “Redo:”. If null is returned, Common Properties will display the default text Save {node_name} node properties for the Undo and Redo buttons.
-
Optional callback used for adding a link in properties tooltips. link object must be defined under description in uiHints parameter info. Common Properties internally pass the link object to tooltipLinkHandler callback.
-This callback must return an object having url and label.
UI hints is a section of the property definition JSON. It contains specifications to assist in the presentation and flow of the property dialog. The specifications indicate which controls to use to display and gather input on the fields.
-UI hints schema
-
The UI Hints section consists a set of simple and complex attributes.
editor_size (string) The width of the properties editor panel. This can have a value of "small", "medium", "large" or "max". The default is "small".
-
When "small" is specified the properties panel is displayed with a default width of 320px and with a resize button that allows the panel to be increased in size up to the "medium" size which is 480px.
-
When "medium" is specified the properties panel has a width of 480px and with a resize button that allows the panel to be increased in size up to the "large" size which is 640px.
-
When "large" is specified the properties panel has a width of 640px and with a resize button that allows the panel to be increased in size up to the "max" size which is 900px.
-
When "max" is specified the properties panel has a width of 900px and no resize button is displayed.
-
-
-
pixel_width (object) This optional property gives finer control over the minimum and maximum sizes of the properties editor panel. If this is omitted the properties editor width is controlled by the editor_size property. pixel_width is an object with two properties min and max which are both numbers.
-
If min is specified it overrides the default size of the shrunken panel and max is based on the editor_size value.
-
If max is specified it overrides the default size of the expanded panel and min is based on the editor_size value.
-
If editor_size is set to "large" only the max value will be used to specify the size of the panel and no resize button will be displayed.
-
-
-
-
A warning will be displayed in the console if you specify an invalid value for either min or max such as making min greater than max.
-
Example of the simple attributes:
-
"uihints":{
-"id":"org.apache.spark.ml.ibm.transformers.Distinct",
-"icon":"images/transformationspark.svg",
-"label":{
-"default":"Distinct"
-},
-"editor_size":"medium",
-"pixel_width":{
-"min":400,
-"max":800
-},
-"description":{
-"default":"Remove rows to leave only rows with distinct combinations of rows"
-}
-
-
The complex attributes of the UI hints section are:
link (object) Optional link in the description. tooltipLinkHandler callback must be defined whenever link object is added in uiHints..
-
id (string) Required unique link id.
-
data (object) Data passed to the tooltipLinkHandler callback.
-
-
-
-
-
parameter_refs (array[string]) List of parameter to be displayed.
-
action_refs (array[string]) List of action to be displayed. Used with actionPanel only.
-
group_info (object) List of additional group information.
-
data (any) Returned in custom panel constructor without any changes.
-
insert_panels (boolean) Indicates whether panels, contained with a panelSelector, should be inserted between the radio buttons of a radio button set indicated by the depends_on_ref parameter.
-
nested_panel (boolean) Indicate whether panel should be nested. Nested panels are indented by 16px from the left and display left border. Default is false.
-
class_name (string) Optional classname for this group
-
open (boolean) Optional used to determine if a panel should be open or not by default. Used with twistyPanel only. Default is false.
UI-only parameters require information about the parameters same as the parameter definition information used for the backend parameters. The UI-only parameter definition information is stored in the UI-hints section in the sub-section named ui_parameters. The format of the information in the ui_parameters sub-section is documented in the Parameter Definition section of Parameter Definitions page.
The UI-only parameters need to be added to other UI Hints sections (for example Group Info and canbe refered to by the parameter_ref field just like backend parameters.
The parameter info section contains the list of parameters to gather values on through the property dialogs and UI hints about each parameter. The UI hints provide information to facilitate the UI controls used to display the parameter in the property dialogs.
placement (string) Placement context for the text. Valid values are as_tooltip, on_panel.
-
link (object) Optional link in the description. tooltipLinkHandler callback must be defined whenever link object is added in uiHints..
-
id (string) Required unique link id.
-
data (object) Data passed to the tooltipLinkHandler callback.
-
-
-
-
-
control (string) Which control to use. See Parameter Controls section of the Controls page.
-
increment (number) Determines the increment/decrement value for the spinner control only. The default value is 1.
-
orientation (string) Determines how the control is displayed. Valid values are vertical, horizontal.
-
width (number) Column width for tables. The widths provided for table columns are used to calculate relative widths for each table column. So for example a 3 column table with widths of 20, 30, and 50 would use 20%, 30%, and 50% of the overall table width, respectively.
-
char_limit (number) Limits the number of characters a user can enter into the control for string parameters only.
-
display_chars (number) This has been deprecated and is subject to removal. Limits the number of characters displayed for a text field in a column in a table. The text will have an ellipsis appended at this limit. Defaults to 64 characters.
-
separator (string) Determines where to put a separator relative to the current control. Valid values are after, before.
-
visible (boolean) Determines whether to display control in a table cell. Used in complex types only.
-
read_only (boolean) Determines whether the control should be immutable or can be edited.
-
place_holder_text (object) Text hint for the user displayed input controls.
resource_key (string) Used as a key for enum value labels in the resources section of property definition.
-
edit_style (string) Editing style of elements in a table. Valid values are subpanel, inline, on_panel.
-
value_icons (array[string]) For enumerated types, this defines the set of icons for the valid values. The ordering must be consistent with the order in the parameter enum attribute.
-
filterable (boolean) Determines if this column values can be filtered so that only rows that match the filter in column values are shown in the table. Applies to complex parameters only.
-
sortable (boolean) Determines if this column values can be sorted into ascending/descending order in a table. Applies to complex parameters only.
-
number_generator (object) Describes a number generator button beside numeric control. The ‘label’ element is a standard resource item, and the ‘range’ element contains ‘min’ and ‘max’ attributes to constrain the range of generated numbers.
-
dm_default (string) Data record metadata field to be used for default values in table cell columns. Typically this is used with parameters in complex structures in which the key field is a column name. Valid values are type, description, measure, and modeling_role.
-
dm_image (string) This can be set to display an icon of the corresponding dm type in the role:column field of a table. Valid values are measure, type, none
-
summary (boolean) Determines if parameter should be shown in the summary when using a summaryPanel.
-
text_before (object) Text to be displayed before the control
custom_control_id (string) Id that is used to determine which custom control to use when control=custom
-
data (any) Returned in custom control constructor without any changes.
-
rows (integer) Number of rows to show in a table before scrolling starts. If one table in a panel is set to -1, that table will use the remaining available vertical space, down to a minimum of 2 rows. Used in expression and code controls to determine the number of rows to show for those controls.
-
moveable_rows (boolean) Determines if rows can be moved up or down in a table or array of strings.
-
action_ref (string) An action to be displayed.
-
date_format (string) A format string such as YYYY-MM-DD which describes the display and entry format for a date field.
-
time_format (string) A format string such as HH:mm:ss which describes the display and entry format for a time field.
-
custom_value_allowed (boolean) Determines if a dropdown, outside of a table, can allow a custom value to be entered.
-
class_name (string) Optional classname for this parameter
-
resizable (boolean) Determines if this column can be resized in a table. When a column is resized, width of all the columns to the right of resized column is adjusted. Applies to structure parameters only. Default is false.
The complex_type_info section defines complex data types. This section is needed if in the parameters section of the parameter definition, one of the parameters has a type that is not the base type (i.e. an array or map of base types). The type of control used for this definition depends on the group info type value.
-
Complex Type info attributes.
-
-
complex_type_ref (string) Required Name of complex type, can be referenced in other places.
-
key_definition (string) A set of parameter info attributes about the key parameter.
parameters (object) Required List of parameters that are part of this complex parameter. This parameter can either have a set of parameter_info attributes or other nested complex_type_info attributes.
-
header (boolean) If true then the table has a header row with column names. Defaults to true.
-
add_remove_rows (boolean) If true then the table can have rows added and removed. Defaults to true.
-
include_all_fields (boolean) When true and add_remove_rows is false, ensures that all fields are included in the control at all times.
-
row_selection (string enum) How many rows in a table can be selected at a time.
-
single: only one row at a time is able to be selected.
-
multiple: multiple rows at a time are able to be selected.
-
multiple-edit: select multiple rows and allow the editing of column values of all selected rows. Clicking on “Edit” button in table toolbar, opens a subpanel which shows editable columns. All columns which have edit_style: "inline" or undefined are shown in the subpabel. Changing a column value in the subpanel, changes the value in all selected rows.
-
-
-
buttons (array) An array of objects that define custom buttons to be displayed in this complex structure, overriding any default buttons. Each button object contains the following properties:
-
id (string) Required: Unique identifier used to identify the button in the callback function.
-
label (object): Button label to display. If an icon is specified as well, the icon will be shown to the right of the label.
carbon_icon (string): Host provided name of Carbon icon to display. A callback function is required for the host application to return the jsx icon object imported from @carbon/icons-react library.
-
enabled (boolean): Button will be enabled if true, disabled if false.
-
divider (string enum): Display a divider before or after this button. Defaults to after
-
before Display divider before this button
-
after Display divider after this button
-
-
-
-
-
-
Example complex_type_info section:
-
"complex_type_info":[
-{
-"complex_type_ref":"SortEntry",
-"row_selection":"multiple",
-"moveable_rows":true,
-"add_remove_rows":false,
-"include_all_fields":true,
-"key_definition":{
-"parameter_ref":"field",
-"width":28,
-"label":{
-"resource_key":"SortEntry.field.label"
-}
-},
-"parameters":[
-{
-"parameter_ref":"sort_order",
-"width":16,
-"resource_key":"SortEntry.sort_order",
-"label":{
-"resource_key":"SortEntry.sort_order.label"
-},
-"control":"toggletext",
-"value_icons":[
-"/images/up-triangle.svg",
-"/images/down-triangle.svg"
-]
-}
-]
-},
-{
-"complex_type_ref":"FieldStorageEntry",
-"key_definition":{
-"parameter_ref":"field",
-"label":{
-"default":"",
-"resource_key":"FieldStorageEntry.field"
-},
-"width":26,
-"sortable":true,
-"filterable":true
-},
-"parameters":[
-{
-"parameter_ref":"override",
-"label":{
-"default":"",
-"resource_key":"FieldStorageEntry.override"
-},
-"width":16,
-"edit_style":"inline",
-"sortable":true
-},
-{
-"parameter_ref":"storage",
-"label":{
-"default":"",
-"resource_key":"FieldStorageEntry.storage"
-},
-"width":26,
-"edit_style":"inline",
-"dm_default":"type"
-}
-],
-"buttons":[
-{
-"id":"icon_button_1",
-"carbon_icon":"Edit32",
-"label":{
-"resource_key":"table.somekey.label"
-},
-"description":{
-"default":"This renders a button that has a label and Carbon icon to the right of the label.
- },
- "enabled":true
-}
-]
-}
-]
-
The title_info sections defines what will be displayed in the title section alongside the titleDefinition.
-
Title info attributes.
-
-
action_refs (array[string]) List of action to be displayed in the title section. Each action_ref must have a corresponding action defined in the action_info section.
Used to dynamically set text based on a parameter value change. If parameter id is used then then current value for that parameter will be passed into the function.
-
-
percent(<number or parameter id>, <integer>) Return the percent of the 1st parameter. The optional 2nd parameter determines the number of decimal places.
-
sum(<number or parameter id>, <number or parameter id>, ...) Returns the sum of all parameters
The editor determines the most appropriate control and panel type for each parameter based on the context (parameter type, role, group type, etc.). Although an author can specify a desired control for a given parameter via its uihints, this should be used sparingly and carefully - specifying an inappropriate control for a parameter will lead to undefined behavior.
-
Documentation containing examples of the following group/panels and control types is available at:
Controls are grouped and arranged on panels and sub-panels within the “group_info” section of operator uihints. Some panels appear as tab controls, others are for managing shared dataset metadata, while still others contain nested sub-panels.
controls A general panel type containing parameter controls.
-
tabs A tabbed control, each tab containing sub-panels and controls.
-
subTabs A horizontal sub-tabbed control, each tab containing sub-panels and controls. If displayed within a Tearsheet container, subtabs will be displayed vertically.
-
panels A panel type that contains sub-panels.
-
panelSelector A panel containing sub-panels that are shown or hidden based upon a controlling radio selection.
-
columnSelection A panel type containing field-selection controls that share a common set of fields.
-
customPanel A custom panel for displaying user defined control. See Custom Panels section of the Custom Components page for more details.
-
summaryPanel A panel used in the flyout editor that will provide a link to open a wide flyout that can contain panels and parameter.
-
actionPanel A panel used for containing action controls.
-
textPanel A panel used to display static label and/or description.
-
twistyPanel A panel used to display a panel title that expands to the panel content when clicked.
-
columnPanel A panel used to display children side by side.
-
tearsheetPanel A tearsheet panel. The panel can be opened/closed using the propertyController methods setActiveTearsheet(groupId) and clearActiveTearsheet()
readonly A read only text field. Used for fields users shouldn’t edit.
-
hidden A control that has no UI to display.
-
textfield A single line editable text field.
-
passwordfield A masked single line text field with tooltip. The tooltip text can be customized by setting [parameter_id].passwordHide.tooltip and [parameter_id].passwordShow.tooltip in resources section.
-
textarea A multi-line text area.
-
list A single column table for editing a list of values.
-
expression An expression editing field that provides language specific syntax highlighting and text auto complete. An expression builder addon is available with the expression control. You must provide the expressionInfo field for the propertiesInfo config. See Common Properties Documentation for more details. To maximize in a tearsheet add this attribute and define a tearsheetPanel in group_info.
-
code An code editing field that provides language specific syntax highlighting and text auto complete. To maximize in a tearsheet add this attribute and define a tearsheetPanel in group_info.
-
numberfield A numeric text field. Number fields can also optionally display a random number generator button beside the control. See the uihints schema for details.
-
datefield A date input control whose date format tokens follow date-fns. Defaults to yyyy-mm-dd
-
timefield A time input control whose time format tokens follow date-fns. Defautls to H:m:s
-
datepicker A date input control with calendar picker whose date format tokens follow Flatpickr. Defaults to Y-m-d. Helper text can be included by adding [parameter_id].helper in the resources section.
-
datepickerRange A date input control with calendar picker for a range of dates. This follow the same rules as the datepicker control. Start and end labels defaults to Start and End respectively. Start, end, and helper labels can be customized by adding the following in the resources section:
-
"resources": {
- [parameter_id].range.start.label: "Custom start label",
- [parameter_id].range.start.desc: "Custom start description that will appear as tooltip next to the label",
- [parameter_id].range.start.helper: "Custom start helper that will appear as text below the input",
- [parameter_id].range.end.label: "Custom end label",
- [parameter_id].range.end.desc: "Custom end description that will appear as tooltip next to the label",
- [parameter_id].range.end.helper: "Custom end helper that will appear as text below the input"`
-}
-
-
spinner A standard spinner control to increment/decrement the number value.
-
checkbox A standard checkbox control.
-
radioset A radio set where a parameter value is selected from a small range of options. See the Conditions page for special radio button disabling options.
-
checkboxset A checkbox set for list type parameters with enumerated options where the count is less than 5.
-
oneofselect A standard dropdown list control.
-
multiselect A standard dropdown list control that allows for multiple selection.
-
someofselect A multi-selection control for enumerated list parameters where the count is greater than 4.
-
selectcolumn A dropdown list control that selects from available column names. When dropdown list is empty, selectcolumn control will display default placeholder text "...". This placeholder text can be customized by setting [parameter_id].emptyList.placeholder in resources section. When custom empty list placeholder text is provided, Common Properties will disable the empty list control.
-
selectcolumns A multi-select control for column selections.
-
selectschema A dropdown control that contains the available schemas in dataset_metadata. The name of the schema will be displayed if provided. If name is not provided, the index (zero-based) of the schema will be used instead. When dropdown list is empty, selectschema control will display default placeholder text "...". This placeholder text can be customized by setting [parameter_id].emptyList.placeholder in resources section. When custom empty list placeholder text is provided, Common Properties will disable the empty list control.
-
toggle A standard toggle control with default On/Off states. This text can be customized by setting [parameter_id].toggle.on.label and [parameter_id].toggle.off.label in resources section.
-
toggletext A two-state control with optional icons that can exist on its own or within table cells.
-
structuretable Table control for editing lists or maps of complex types that have field names in the first column.
-
structurelisteditor For lists or maps of complex types that are not field-oriented parameters.
-
structureeditor Allows one to define a structure and use it directly on a panel. Each structure member is surfaced as an individual control. Supports a layout setting that allows one to position structureeditor controls in a grid (see below).
-
readonlyTable A read only table. Used for tables to display fields that users shouldn’t edit.
-
custom A custom control for displaying a user defined control. See Custom Controls section of the Common Properties Custom Components page for more details.
-
slider A standard slider which allows to enter a numeric value within the slider range and also allows to drag and adjust the slider track to a specific value within the range. The slider labels for minimum and maximum values can be customized by setting them as [parameter_id].min.label for minimum value label and [parameter_id].max.label for maximum value label in resources section.
When a given node can accept more than a single datarecord-metadata object as input, it becomes necessary to store the schema name (a.k.a. ‘link_name’) along with each field name that is stored in parameter sets. In those cases, instead of using strings to store field names, they are represented in parameter sets as compound objects containing both ‘link_ref’ and ‘field_name’ elements:
In order to indicate that a given node can potentially accept multiple input data links and would thus require compound field name storage, all parameter definitions within the node that contain "role": "column", whether located at the top level or within complex types, should declare their data types as “object” instead of “string”:
moveable_rowsboolean A value that appears in “complex_type_definition” sections. If set to true allows rows in the table to be moved up and down for reordering.
-
row_selectionenum [“single”, “multiple”] Determines how many rows can be selected in a table at one time. Defaults to multiple.
-
sortableboolean Both sortable and filterable apply to table columns. When set within the “key_definition” or the “parameters” sections of a structure definition, those columns are sortable and/or can be filtered upon.
-
filterableboolean(see sortable above)
-
languageenum [“CLEM”, “text/x-hive”] The language for the expression control syntax highlight and text auto complete feature. If not specified, the expression control does not have syntax highlighting or text auto complete.
-
layout A two-dimensional string array value that appears in “complex_type_definition” sections and allows one to layout structureeditor controls in a two dimensional grid.
Conditions define a set of specifications for evaluating parameter values. The specifications support complex interdependency checking such as relationships between multiple parameters (i.e. Valid values for parameter one depend upon the value of parameter two). Here is the
-Conditions Schema
focus_parameter_ref (string) Required The parameter control to get focus after displaying the error/warning. If the validation refers to a table cell, then control must have the column indicator. For example if the validation is for MyTable cell column 2 then MyTable[2].
-
type (string) Type of messages. Valid values are error, warning, info.
-
-
-
-
evaluate (object) Specification for how to evaluate the validity of the parameter. The evaluate attribute can be one of the following structures.
-
-
condition (object) This is a single condition that evaluates to true or false.
-
op (string) Required A single operator for the properties of the condition. Valid values are:
-isEmpty,
-isNotEmpty,
-greaterThan,
-lessThan,
-equals,
-notEquals,
-matches,
-notMatches,
-contains,
-notContains,
-colNotExists,
-isDateTime,
-dmTypeEquals,
-dmTypeNotEquals,
-dmMeasurementEquals,
-dmMeasurementNotEquals,
-dmRoleEquals,
-dmRoleNotEquals
-lengthEquals,
-lengthGreaterThan,
-lengthLessThan.
-
-
-
parameter_ref (string) Required The primary parameter.
-
parameter_2_ref (string) Second parameter for multi-parameter validation.
-
value (string, boolean, number) Value against which to compare the primary parameter value.
-
values (array[string]) Values against which to compare the primary parameter value is in. Used only in filter conditions.
-
-
-
or (object) This is a container of ‘or’ conditions. Evaluates to true if ANY sub-condition evaluates to true. Can nest any number of additional conditional types.
-
and (object) This is a container of ‘and’ conditions. Evaluates to true if ALL sub-condition evaluates to true. Can nest any number of additional conditional types.
Enablement test. Disables controls if evaluate is false.
-
The attributes for the enabled definition are:
-
-
parameter_refs (array[string]) Array of parameter names affected by this operation. If evaluate is false, then the controls associated with these parameters are disabled. Note that individual radio buttons can be disabled by using the radio button value name instead of the overall property name in the parameter_refs array.
-
action_refs (array[string]) Array of action names affected by this operation. If evaluate is false, then the action button or image associated with these action names are disabled.
-
evaluate (object) see the evaluate attribute in validation definition.
Visibility test. Hides controls if evaluate is false.
-
The attributes for the visible definition are:
-
-
parameter_refs (array[string]) Array of parameter names affected by this operation. If evaluate is false, then hide the controls associated with these parameters.
-
action_refs (array[string]) Array of action names affected by this operation. If evaluate is false, then the action button or image associated with these action names are disabled.
-
evaluate (object) see the evaluate attribute in validation definition.
Filter test. The filter will determine which data record fields to include in a control.
-
The attributes for the filter definition are:
-
-
parameter_ref (string) Parameter id affected by this operation. This must be a parameter that operates upon datarecord-metadata columns.
-
parameter_refs (string) Exclusive with parameter_ref and used with dmSharedFields. Parameter ids affected by this operation. They must be parameters that operate upon datarecord-metadata columns.
-
evaluate (object) see the evaluate attribute in validation definition.
-
-
Supported operations (op):
-
-
dmType - filters type value from schema.
-
dmMeasurement - filters measurement value from schema.
-
dmModelingRole - filters modeling_role value from schema.
-
dmSharedFields - shares source fields with all field chooser property names found in the parameter_refs array.
Allow change validates that a change is allowed on a property. If it evaluates to true then the value for the property is changed. This is typically used to restrict values that are invalid in one property based on the value in another property. For example, if the property represents a storage type with a value of string, then a property that represents a measurement type should not be allowed to be set to continuous.
-
The attributes for the allow_change definition are:
-
-
parameter_refs (array[string]) Array of parameter names affected by this operation.
-
evaluate (object) see the evaluate attribute in validation definition.
Sets the default value on the parameter_ref property if condition evaluates to true. If multiple conditions evaluate to true only the first condition is used. Default value condition is evaluated only once when loading properties. If user updates the value of parameter_ref, default value will be overwritten by the new value.
-
The attributes for the default_value definition are:
-
-
parameter_ref (string) Parameter whose default value is to be set.
-
value (string, boolean, number, object, array) This will be the default value of parameter_ref if condition evaluates to true.
-
evaluate (object) see the evaluate attribute in validation definition.
-
-
Example:
-
{
-"default_value":{
-"parameter_ref":"conditional_default",
-"value":"Value defined in default_value condition. You will see this sentence when default value of mode equals Include.",
-"evaluate":{
-"condition":{
-"parameter_ref":"mode",
-"op":"equals",
-"value":"Include"
-}
-}
-}
-},
-{
-"default_value":{
-"parameter_ref":"conditional_default",
-"value":["This is a second condition for conditional_default. You should never see this value."],
-"evaluate":{
-"condition":{
-"parameter_ref":"mode",
-"op":"equals",
-"value":"Include"
-}
-}
-}
-}
-
Support for table cell conditions is achieved via the use of the array subscript operator, []. When evaluating table cells, one uses the table identifier with an array subscript indicating the zero-based table column being operated upon (which also corresponds to the sub-control index as defined in complex_types).
-
So for example if one has a StructureTable property named myTable, column conditions on that table are referred to using myTable[1], myTable[3], etc.
Custom components allows applications to use custom code to drive different parts of the common-properties user interface. For some panels and controls it might be necessary to listen to different types of redux state changes to cause the panel/control to rerender.
-Here is an example of a textfield listening to three state changes:
-
import{connect}from"react-redux";
-
-// ... application code
-
-render(){
-constvalue=this.props.value;// value passed by redux as a property
-
-// ... rest of component render code
-
-}
-
-TextfieldControl.propTypes={
-// ... application props
-state:PropTypes.string,// pass in by redux
-value:PropTypes.string,// pass in by redux
-messageInfo:PropTypes.object// pass in by redux
-};
-
-constmapStateToProps=(state,ownProps)=>({
-value:ownProps.controller.getPropertyValue(ownProps.propertyId),
-state:ownProps.controller.getControlState(ownProps.propertyId),
-messageInfo:ownProps.controller.getErrorMessage(ownProps.propertyId)
-});
-exportdefaultconnect(mapStateToProps,null)(TextfieldControl);
-
// Returns the 'id' for the group defined in uihints
-staticid()
-
-constructor(parameters,controller,data)
-
-// Returns the content users want to display
-renderPanel()
-
-
-
parameters - String array of parameters set under the customPanel group in uihints
// Returns the 'custom_control_id' for the parameter defined in uihints
-staticid()
-
-constructor(propertyId,controller,data,tableInfo)
-
-// Returns the content users want to display
-renderControl()
-
data - Returns values stored in data attribute of a parameter in uihints.
-
tableInfo - Set when custom control is a cell in a table.
-
table (boolean) Set to true when in a table cell
-
editStyle (string) Valid values are “summary” and “inline”. “summary” is set when the control will display either below the table (“on_panel”) or in a “subpanel”. This allows the custom control to display a summary value in the cell and something else for the custom control.
-
-
-
renderControl() - Called on all Redux store changes:
Custom condition operators allow users to create their own operators that can then be used for enablement, visibility, validation, and enum filtering. The condition operators should always return a boolean value.
/**
-* This is the key used to determine if the operator should be ran. Maps to the `op` defined in the
-* `condition` in uihints
-* @return string
-*/
-functionop()
-
-/**
-* @param see below
-* @return boolean
-*/
-functionevaluate(paramInfo,param2Info,value,controller)
-
-
-
paramInfo (object) - parameter_ref set in the condition in uihints
-
control (object) - contains information about the control.
-
value (any) - current property value
-
-
-
param2Info (object) - parameter_2_ref set in the condition in uihints. See paramInfo for object info
-
value - value set in the condition in uihints. If no value specific this will be undefined
constpropertyId={
-name:{parameternamedefinedinoperatordefinition},
-row:{rowintable/array},// optional when col not set
-col:{colintable},// optional
-propertyId:{propertyIdofthenestedstructure}// optional
-}
-
/*
- * options - optional object of config options where:
- * setDefaultValues (boolean): when set to true, set default values from parameter definition
- */
-setPropertyValues(values,options)
-updatePropertyValue(propertyId,value)
-
-/*
- * options - optional object of config options where:
- * filterHiddenDisabled (boolean): when set to true, filter out data values with a state of disabled or hidden
- * filterHiddenControls (boolean): when set to true, filter out data values having control type hidden
- * applyProperties (boolean): when set to true, will return data values in the format expected by the `applyPropertyChanges` callback. If unset or false, will return the internal format used by Common Properties.
- */
-getPropertyValue(propertyId,options)
-
-/*
- * options - optional object of config options where:
- * filterHiddenDisabled (boolean): when set to true, filter out data values with a state of disabled or hidden
- * filterHiddenControls (boolean): when set to true, filter out data values having control type hidden
- * applyProperties (boolean): when set to true, will return data values in the format expected by the `applyPropertyChanges` callback. If unset or false, will return the internal format used by Common Properties.
- */
-getPropertyValues(options)
-
/*
- * Returns current list of error messages
- * @filteredPipeline (boolean) optional
- * @filterHiddenDisable (boolean) optional. If true, will not return error messages from controls that are hidden or disabled
- * @filterDisplayError (boolean) optional. If true, will not return error messages that are not displayed in the editor
- * when filteredPipeline=true returns enabled/visible control messages and only 1 per control.
- */
-getAllErrorMessages()
-getErrorMessages(filteredPipeline,filterHiddenDisable,filterSuccess,filterDisplayError=true)
-getErrorMessage(propertyId,filterHiddenDisable=false,filterSuccess=false,filterDisplayError=true)
-getRequiredErrorMessages()
-setErrorMessages(messages)
-updateErrorMessage(propertyId,message)
-
/*
- * Returns table row selection indices as an array of integers.
- * @propertyId - see above
- */
-getSelectedRows(propertyId)
-
-/*
- * Updates table row selections for the given table control.
- * @propertyId - see above
- * @selection - A zero-based array of integer selection indices
- */
-updateSelectedRows(propertyId,selection)
-
-/*
- * Clears selected table rows for the given table.
- * @propertyId - see above
- * If the propertyId is omitted all table row selections are cleared
- */
-clearSelectedRows(propertyId)
-
-/*
- * Adds a row selection listener for a table or list.
- * @propertyId - see above
- * @listener - callback function for when a selection is made in the table or list
- */
-addRowSelectionListener(propertyId,listener)
-
-/*
- * Removes the row selection listener from a table or list.
- * @propertyId - see above
- */
-removeRowSelectionListener(propertyId)
-
/*
- * Returns the current size of the RHS flyout.
- */
-getEditorSize()
-
-/*
- * Sets default property values from parameter definition in the propertiesController.
- * Note - These values won't be displayed on the UI. Host applications can call getPropertyValues() to retrieve the values.
- * @paramDef - Follows the format of https://github.com/elyra-ai/pipeline-schemas/blob/master/common-canvas/parameter-defs/parameter-defs-v3-schema.json
- */
-setParamDef(paramDef)
-
-/*
- * Returns the id of top-level active tab or accordion
- */
-getTopLevelActiveGroupId()
-
-/*
- * Makes the passed in groupId active. Only works for top-level groups
- */
-setTopLevelActiveGroupId(groupId)
-
/*
- * Disable table row move buttons for all propertyIds in given array
- * @param propertyIds Array of propertyIds
- *
- */
-setDisableRowMoveButtons(propertyIds)
-
-/*
- * Returns array of propertyIds for which row move buttons will be disabled
- * @return Array of propertyIds
- */
-getDisableRowMoveButtons()
-
-/*
- * Check if row move buttons should be disabled for given propertyId
- * @param propertyId The unique property identifier
- * @return boolean
- */
-isDisableRowMoveButtons(propertyId)
-
/*
- * Only used in custom panel to allow for custom property summary values to be displayed
- * Displays the value set in propertiesReducer for that parameter
- * @propertyId - see above
- * @label (string)
- * @inSummary (boolean)
- */
-setControlInSummary(propertyId,label,inSummary)
-
-/*
- * Sets the content to be displayed in the summaryPanel for a customPanel property.
- * The summary panel will directly display the content.
- * @propertyId - see above
- * @content = { value: <object> , label: "<value>" }
- */
-updateCustPropSumPanelValue(propertyId,content)
-
-/*
- * Returns a standard control that can then be used in a customPanel.
- * @propertyId - See above
- * @paramDef - Follows the format of https://github.com/elyra-ai/pipeline-schemas/blob/master/common-canvas/parameter-defs/parameter-defs-v1-schema.json). titleDefinition, current_parameters, conditions, dataset_metadata are ignored and are optional.
- * @parameter - This is the parameter from the paramDef to create the control for.
- */
-createControl(propertyId,paramDef,parameter)
-
-/*
- * Returns the translated text for a control given a resource key.
- * Users should be able to use the values from resources that has been uploaded as part of paramDef.
- * @key - Resource key
- * @value - Default value returned when no resource or key has been found.
- */
-getResource(key,value)
-
-
maxLength for single-line and multi-line control methods¶
-
/*
- * Returns the maximum characters allowed for multi-line string controls
- * Default value is 1024
- */
-getMaxLengthForMultiLineControls()
-
-/*
- * Returns the maximum characters allowed for single-line string controls
- * Default value is 128
- */
-getMaxLengthForSingleLineControls()
-
/*
- * Set the addRemoveRows attribute to 'enabled' for the given propertyId
- * @param propertyId The unique property identifier
- * @param enabled boolean value to enable or disable addRemoveRows
- */
-setAddRemoveRows(propertyId,enabled)
-
-/*
- * Returns the true if addRemoveRows is enabled for the given propertyID
- * @param propertyId The unique property identifier
- * @return boolean
- */
-getAddRemoveRows(propertyId)
-
/*
- * Set the main "save" button to disabled(true) or enabled(false)
- * @param saveDisable (boolean)
- */
-setSaveButtonDisable(saveDisable)
-
-/*
- * Returns the true if the main "save" button is disabled, false otherwise
- * @return boolean
- */
-getSaveButtonDisable()
-
-
Add static rows for table controls which will disable the re-ordering of the rows that are set as static for the given propertyId¶
-
/*
- * Set static rows for the given propertyId
- * @param propertyId The unique property identifier
- * @param staticRowsArr Array of first n row indexes or last n row indexes
- */
-updateStaticRows(propertyId,staticRowsArr)
-
-/*
- * Returns the static rows set for the given propertyId
- * @param propertyId The unique property identifier
- */
-getStaticRows(propertyId)
-
-/*
- * Removes the static rows set for the given propertyId
- * @param propertyId The unique property identifier
- */
-clearStaticRows(propertyId)
-
/*
- * Set the table button to 'enabled' for the given propertyId
- * @param propertyId The unique property identifier
- * @param buttonId The unique button identifier
- * @param enabled boolean value to enable or disable the button
- */
-setTableButtonEnabled(propertyId,buttonId,enabled)
-
-/*
- * Returns the table button states for the given propertyID
- * @param propertyId The unique property identifier
- * @return object An object of buttonIds mapped to their enabled state
- */
-getTableButtons(propertyId)
-
-/*
- * Returns the true if the table button is enabled for the given propertyID and buttonId
- * @param propertyId The unique property identifier
- * @param buttonId The unique button identifier
- * @return boolean
- */
-getTableButtonEnabled(propertyId,buttonId)
-
/*
- * Check if given column is visible in the table
- * @param propertyId The unique property identifier
- * @param columnIndex Column index in the table
- */
-getColumnVisibility(propertyId,columnIndex)
-
-/*
- * Set column visibility
- * @param propertyId The unique property identifier
- * @param columnIndex Column index in the table
- * @param value Boolean value to set column visible/invisible
- */
-toggleColumnVisibility(propertyId,columnIndex,value)
-
The Properties Config is an object passed as an optional prop to the <CommonProperties< React object containing the following fields:
-
-
-
containerType string: type of container to display the properties, can be “Modal”, “Tearsheet”, or “Custom”. default: "Custom"
-
-
-
rightFlyout boolean: If set to true, groups will be displayed as an accordion. If false, groups are displayed as tabs. default: false
-
-
-
applyOnBlur boolean: calls applyPropertyChanges when focus leave Common Properties. default: false
-
-
-
disableSaveOnRequiredErrors boolean: Disable the properties editor “save” button if there are required errors
-
-
-
enableResize boolean: adds a button that allows the right-side fly-out editor to expand/collapse between small and medium sizes. default: true
-
-
-
conditionReturnValueHandling string: used to determine how hidden or disabled control values are returned in applyPropertyChanges callback. Current options are “value” or “null”. default: "value"
-
-
-
buttonLabels object:
-
-
primary string: Label to use for the primary button of the properties dialog
-
secondary string: Label to use for the secondary button of the properties dialog
-
-
-
-
heading boolean: show heading and heading icon in right-side fly-out panels. default: false
-
-
-
schemaValidation boolean: If set to true, schema validation will be enabled when a parameter definition has been set in CommonProperties. Any errors found will be reported on the browser dev console. It is recommended you run with schema validation switched on while in development mode.
-
-
-
applyPropertiesWithoutEdit boolean: When true, will always call applyPropertyChanges even if no changes were made. default: false
-
-
-
maxLengthForMultiLineControls number - maximum characters allowed for multi-line string controls like textarea. default: 1024
-
-
-
maxLengthForSingleLineControls number - maximum characters allowed for single-line string controls like textfield. default: 128
-
-
-
convertValueDataTypes boolean - Default false. If set to true, currentParameter values whose data type does not match what is defined in the parameter definitions will be converted to the specified data type.
-
-
-
trimSpaces boolean - Default true. If set to false, condition ops(isEmpty, isNotEmpty) and required fields are allowed to only contain spaces without triggering condition errors.
-
-
-
showRequiredIndicator boolean - Default true to show (required) indicator. If set to false, show (optional) indicator next to properties label.
-
-
-
showAlertsTab boolean - Default true to show “Alerts” tab whenever there are error or warning messages. If set to false, Alerts tab won’t be displayed.
-
-
-
returnValueFiltering array - Default []. When set this will filter out any values in the array in the parameters returned when applyPropertyChanges is call. Only primitive data types are currently supported.
-
-
-
categoryView string - View categories in right-flyout. Can be "accordions" or "tabs". default: "accordions".
-
-What is the relationship between Elyra Canvas and the Elyra AI Toolkit?
-
Elyra Canvas is a repo inside the Elyra AI Toolkit. The Elyra repo in the toolkit is dependent on Elyra Canvas but Elyra Canvas is not dependent on it or any repo in the toolkit other than the Elyra Pipeline Schemas repo.
-
-With resizeable nodes (enableResizableNodes: true) why don’t the shapes defined by bodyPath and selectionPath change when resizing a node?
-
The bodyPath and selectionPath ‘shapes’ do not automatically redraw when the user resizes the node. However, a function that returns a path can be provided for those fields instead of a string, so the application can return whatever shape it prefers as the resizing progresses. Obviously, these functions are called in real-time so they needs to return very quickly.
-
-
-Can React objects specified in nodeExternalObject display supernodes and, if so, how is the sub-flow rendered?
-
Yes, ’nodeExternalObject` is supported for supernodes. The way it works is:
-
-
If the supernode is collapsed (that is, it looks like a regular node) then the React node is used in the same way as for a regular node
-
If the supernode it expanded in-place, then the React object is still used in the same way and the <svg> area that displays the sub-flow is displayed by Common Canvas over the top of the node body.
-
If the user is viewing the supernode ‘full-page’ then the sub-flow is rendered in the usual way since the parent supernode is not visible at that point.
-
-
There is an example of this in the ‘React Nodes - Carbon Charts’ sample application in the test harness.
-
-
-
-When displaying React nodes using nodeExternalObject field, how can the application pass in its own props to the component?
-
The application can add whatever it wants to pass in as a field in either the nodeData object or the Canvas Controller — making sure not to over write any of the existing fields that are there by default of course. So if you wanted to pass in your own data on a node-by-node basis you could set a field in the app_data field of each node. Something like:
-
-With markdown enabled in comments, why isn’t the whitespace preserved when the user leaves edit mode?
-
That’s the way markdown works. It removes white space in the entered text. For example, if you enter similar text into a comment in a GitHub issue and look at the preview you’ll see the whitespace is removed.
-
Common Canvas is using a third party library to convert what the user enters to the HTML that is displayed so the removal of whitespace is not under its control.
-
However, Comments support the ability to enter HTML directly into the markdown text. HTML can be used to preserve whitespace and do many other styling and customizations to the text.
-
-
-Are there any plans to support different fonts in comments?
-
In Elyra Canvas v13.0.0, there is now a feature that allows the user to enter HTML in to the markdown text. This allows fonts and many other customizations of the text — although the user does need to know what they are doing with HTML.
The Canvas unit tests are automated with the primary purpose of providing rapid feedback to the developers. The test cases are run during every development build. Unit test cases are written using Jest Jest Tutorial. The test cases should be written and delivered at the time that a feature or enhancement is delivered.
-
Unit test cases should focus on good coverage of a function/service. We are current investigating code coverage analysis tools and will update this doc when it is implemented.
-
Unit test case coverage should focus on these areas:
Add debugger; statement to your Jest test suite program where you want to stop and begin debugging.
-
-
If you want to run just a single test within your test program (rather than all of them) temporarily change the it() method for the test to be it.only(). For example, change:
-
it("should add a node", () => { ... })
-
to be:
-
it.only("should add a node", () => { ... })
-
-
-
In the console enter: npm run debug or npm run debug <test suite name>
-
-
Open Chrome debugging tools by pasting this into the Chrome address field: chrome://inspect/
-
You should see a ‘remote’ target for node_modules/.bin/jest. Click on the inspect link below it.
-
Click on sources and then click the play button (right pointing blue triangle icon).
-
The code should run to the point where your debugger statement was added.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
