Canvas config

There are five types of config objects available for Common canvas consumers: Canvas, Toolbar, Notification, Context menu, and Keyboard.

Below you’ll find Canvas config objects.

Canvas config object

The canvas config object should contain one or more of the following properties:

       "enableInteractionType": "Trackpad",
       "enableNodeFormatType": "Horizontal",
       "enableLinkType": "Curve",
       "enableLinkDirection": "LeftRight",
       "enableLinkSelection": "None",
       "enableLinkReplaceOnNewConnection": true,
       "enableInternalObjectModel": true,
       "enablePaletteLayout": "Flyout",
       "enableToolbarLayout": "Top",

enableInteractionType

This can be “Mouse” or “Trackpad”. The default is “Mouse”.

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

enableNodeFormatType

This is only applicable when “Ports” connection type is specified. 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.

enableLinkType

This is only applicable when “Ports” connection type is specified. This can be “Curve”, “Elbow”, or “Straight”. “Curve” is the default. This will set the link style used to connect nodes.

enableLinkDirection

This is only applicable when “Ports” connection type is specified. This can be “LeftRight”, “TopBottom”, or “BottomTop”. “LeftRight” is the default. This will set the input and output port positions on nodes to facilitate links being drawn in the direction specified.

For “LeftRight” output ports will be on the right and input ports will be on the left of the nodes
For “TopBottom” output ports will be on the bottom and input ports will be on the top of the nodes
For “BottomTop” output ports will be on the top and input ports will be on the bottom of the nodes

enableLinkSelection

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.

enableLinkReplaceOnNewConnection

This can be true or false. 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".

enableInternalObjectModel

You should use true for this all the time. true is the default. If you set this to false your code will be responsible for handling the object model, which is NOT recommended. When false, changes are not set into the object model, and consumers are expected to listen to events and update the internal object model themselves (again, not recommended).

enablePaletteLayout

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.

enableToolbarLayout

This can be: “Top” or “None”. The default is “Top”. “Top” displays a toolbar at the top of the canvas area. See the toolbar configuration object docs for details on how to customize the toolbar. “None” stops the toolbar from appearing.

enableInsertNodeDroppedOnLink

This can be true or false. 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

enableRightFlyoutUnderToolbar

This can be true or false. 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.

enablePositionNodeOnRightFlyoutOpen

This can be true or false. The default is false. If set to true, when the right-side flyout is open th currently selected node (assuing 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.

enableHighlightNodeOnNewLinkDrag

This can be true or false. 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.

enableHighlightUnavailableNodes

This can be true or false. 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.

enableAutoLinkOnlyFromSelNodes

This can be true or false. 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.

enableMoveNodesOnSupernodeResize

This can be true or false. The default is true. If true, nodes surrounding a supernode will be moved when the supernode is resized so that the supernode does not overlay them.

enableExternalPipelineFlows

This can be true or false. 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.

Warning: The host application must implement some of the common-canvas callbacks for external pipeline flow support to work correctly. See the Wiki section on external pipeline flow support for more details. enableDisplayFullLabelOnHover

This can be true or false. 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.

enableDisplayFullLabelOnHover

enableSingleOutputPortDisplay

This can be true or false. 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.

enableDragWithoutSelect

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.

enableDropZoneOnExternalDrag

This can be true or false. 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.

See the Dragging an object from the desktop section of the Wiki for details on how to handle the drop of an external object onto the canvas.

enableNodeLayout

This is a simple Javascript object, the properties of which override the default node layout properties. For more details see: Customizing Node Layout Properties

enableSaveZoom

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

enablePanIntoViewOnOpen

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”).

enableZoomIntoSubFlows

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.

enableSnapToGridType

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.

enableSnapToGridX

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%”. enableSnapToGridY

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%”. enableAutoLayoutVerticalSpacing

This is the spacing in pixels which is used to separate nodes vertically when either the vertical or horizontal auto layout action is used.

enableAutoLayoutHorizontalSpacing

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.

enableAssocLinkCreation

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.

enableAssocLinkType

This can be “Straight” or “RightSideCurve”. The default it “Straight”. This field changes the way association links are drawn on the canvas.

enableBrowserEditMenu

This can be true or false. 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 be disabled 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.

enableNarrowPalette

This can be true or false. true is the default. If true when the palette is closed the narrow palette will be shown. When false the palette completely closes.

paletteInitialState

This can be true or false. false is the default. It set to true the palette will be opened when common canvas first appears to its full (non-narrow) state.

emptyCanvasContent

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!”. dropZoneCanvasContent

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.

schemaValidation

This can be true or false. false is the default. It tells common canvas whether you want pipleineFlow and palette files to be validated against the schema files when they are submitted to the canvas controller. If a validation error is found it is thrown to the calling code. This should probably be set to true only during testing.

tipConfig

Object that configures whether tips for palette items, nodes, ports or links are enabled (value set to true) or disabled (value set to false). By default, all tips are enabled. The default content of tips can be overwritten by implementing the tipHandler callback.

Common Canvas: Canvas documentation

Canvas config: Toolbar config