Read Only or Locked 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 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.

General Config¶

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.

Canvas¶

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:

    .editing-actions-false {
        .d3-node-group {
        & .d3-node-label,
            & svg path {
                color: $disabled-02;
                stroke: $disabled-02;
                fill: $disabled-03;
            }
        }
    }

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.

Keyboard¶

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.

Palette¶

Setting enableEditingActions to false:

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

State Tag¶

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-oly or locked) the flow is in. The state tag can be switched on using the enableStateTag canvas configuration field.

Test Harness: Sample Read-Only application¶

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.