Test using readthedocs theme

Signed-off-by: srikant <[email protected]>
srikant-ch5 · Feb 23, 2024 · 7252eb7 · 7252eb7
1 parent d88a8d7
commit 7252eb7
Show file tree

Hide file tree

Showing 35 changed files with 6,066 additions and 10 deletions.
diff --git a/docs/2.0-Common-Canvas-Documentation.md b/docs/2.0-Common-Canvas-Documentation.md
@@ -0,0 +1,241 @@
+## Introduction
+Common canvas displays a flow of data operations as nodes and links which the user can create and edit to get the flow they want. These visual flows of data operations are translated into data processing steps performed by a back-end server. Common canvas provides functionality for the visual display of flows in the browser and leaves persistence and execution of data flows to the application.
+Within common canvas the user can perform operations such as:
+
+* Create a new node by dragging a node definition from a palette onto the canvas.
+* Create a new node by dragging a node from outside the canvas onto the canvas (you'll have to do some programming to get this to work).
+* Delete a node by clicking a context menu option.
+* Create a link by dragging a line from one node to another.
+* Delete a link by clicking a context menu option.
+* Add a comment to the canvas and draw a link from it to one or more nodes.
+* Edit a comment.
+* Move nodes and comments around in the canvas to get the desired arrangement.  
+* And more! ...
+
+# Architecture
+
+## Common Canvas react object
+   Common-canvas is a react component that can be used in your react application to display a fully-functional canvas user interface including the function mentioned above. The `<CommonCanvas>` component is displayed in a `<div>` provided by your application. 
+
+Common-canvas has these constituent parts that are visible to the user:
+
+* [Canvas editor](/2.0.1-Canvas-Editor/) - the main area of the UI where the flow is displayed and edited
+* [Palette](/2.0.2-Palette/) - a set of node templates that can be dragged to the canvas to create new nodes
+* [Context menu](/2.0.3-Context-Menu/) - a menu of options for nodes, comments, etc
+* [Context toolbar](/2.0.4-Context-Toolbar/) - a menu of options for nodes, comments, etc presented as a small toolbar
+* Toolbar - a set of tools across the top of the UI
+* Notification panel - a panel for displaying runtime and other messages to your user
+* Right side flyout - a panel, often used to display node properties
+* Top panel - a panel which can be used to display other app related information
+* Bottom panel - a panel which can be used to display other app related information
+
+and it handles: 
+
+  1. the visual display of the flow of operations;
+  2. any user gestures on the canvas;
+  3. display of context menus;
+  4. display and handling of the palette.
+  5. provision of callbacks to tell your code what operations the user is performing on the canvas
+  6. and much much more.
+
+## Canvas Controller
+
+The only mandatory parameter for the `<CommonCanvas>` component is a regular JavaScript object called the [CanvasController](/2.4-Canvas-Controller-API/).
+
+  The CanvasController routes handles calls from the host application and actions performed by the user. It then updates the internal object model which stores:
+
+  1. the data that describes the flow of nodes, links and comments (called a pipelineFlow);
+  2. the data that describes the definition of the palette which contains node templates that can dragged to add nodes to the canvas;
+  3. the set of currently selected objects.
+  4. notification messages
+  5. breadcrumbs that indicate which sub-flow is being viewed
+  6. layout information
+
+  The [CanvasController](/2.4-Canvas-Controller-API/) provides an API which allows your code to:
+
+   1. set a new pipelineFlow;
+   2. get the current pipelineFlow (after the user has edited it);
+   3. update and edit objects in the canvas (for example, add node, delete link etc.);
+   4. set the node definition data (for display of nodes in the palette)
+
+# Getting started with common canvas programming
+
+## Hello Canvas!
+  You can start by looking at these two 'hello  world' examples for using common canvas:
+
+* This first one called [app-tiny.js](https://github.com/elyra-ai/canvas/blob/master/canvas_modules/harness/src/client/app-tiny.js) has the bare minimum necessary to get a fully functioning common-canvas to appear including all the basic functionality, a palette and a flow of nodes and links. 
+* The second, called [app-small.js](https://github.com/elyra-ai/canvas/blob/master/canvas_modules/harness/src/client/app-small.js), shows many of the options available to a common-canvas developer such as configurations and callback handlers.
+
+You can also look at the [App.js](https://github.com/elyra-ai/canvas/blob/49ed634e3353d8f5c58eb8409ed8e1009f19c87a/canvas_modules/harness/src/client/App.js) file in the test harness section of this repo to see examples of code that uses the common canvas component.
+
+   Now let's walk through the different steps to get common-canvas working:
+
+
+## Step 1 : Install Elyra Canvas NPM module
+
+Enter:
+```
+     npm install @elyra/canvas 
+```
+
+## Step 2 : Import Common-canvas
+
+To use common canvas in your react application you need to do the following. First import the CommonCanvas react component and CanvasController class from the Elyra Canvas library.  Elyra Canvas produces both `esm` and `cjs` outputs.  By default `esm` will be used when webpack is used to build the consuming application.
+
+**All Components**
+```js
+    import { CommonCanvas, CanvasController } from "@elyra/canvas";
+```
+**Canvas only**
+
+ To import only canvas functionality in `cjs` format use:
+```js
+    import { CommonCanvas, CanvasController } from "@elyra/canvas/dist/lib/canvas";
+```
+
+In addition you'll need to import `<IntlProvider>` from the `react-intl` library.
+```js
+    import { IntlProvider } from "react-intl";
+```
+
+
+## Step 3 : Create an instance of the canvas controller
+To control the canvas you'll need an instance of the canvas controller so create an instance of it like this (probably in the constructor of your object).
+```js
+    this.canvasController = new CanvasController();
+```
+## Step 4 : Set the palette data
+Next you'll need to populate the palette data. This will specify the nodes (split into categories) that will appear in the palette. The user can drag them from the palette to build their flow. This is done by calling CanvasController with:
+```js
+    this.canvasController.setPipelineFlowPalette(pipelineFlowPalette);
+```
+The pipelineFlowPalette object should conform to the JSON schema found here:    
+https://github.com/elyra-ai/pipeline-schemas/tree/master/common-canvas/palette
+
+Some examples of palette JSON files can be found here:    
+https://github.com/elyra-ai/canvas/tree/master/canvas_modules/harness/test_resources/palettes
+
+## Step 5 : (Optional) Set the flow data
+This is an optional step. If you want a previously saved flow to be shown in the canvas editor so the user can start to edit it, you will need to call the CanvasController with:
+```js
+    this.canvasController.setPipelineFlow(pipelineFlow);
+```
+
+The pipelineFlow object should conform to the JSON schema found here:    
+https://github.com/elyra-ai/pipeline-schemas/tree/master/common-pipeline/pipeline-flow
+
+Some examples of pipeline flow JSON files can be found here:    
+https://github.com/elyra-ai/canvas/tree/master/canvas_modules/harness/test_resources/diagrams
+
+## Step 6 : Pull in the CSS
+Check this section to find info on what CSS to include in your application's CSS. [Styling](./4.0-Styling.md).
+
+## Step 7 : Display the canvas
+
+Finally you'll need to display the canvas object inside an `<IntlProvider>` object. Inside your render code, add the following:
+```html
+    <div>
+        <IntlProvider>
+            <CommonCanvas canvasController={this.canvasController} />
+        </IntlProvider>
+    </div>
+```
+The div should have the dimensions you want for your canvas to display in your page. For the canvasController property, pass the instance of canvas controller you created earlier. This is the only mandatory property. After providing this and running your code you will have a fully functioning canvas including: a palette; default toolbar; context menus; direct manipulation (move and resize) etc. To customize these behaviors and presentation continue with the sections below.
+
+## Common Canvas customization
+If you want to customize the behavior of common canvas you can specify any combination of the following optional settings:   
+```html
+    <div>
+        <CommonCanvas
+            canvasController={this.canvasController}
+
+            config={this.commonCanvasConfig}
+            toolbarConfig={this.toolbarConfig}
+            notificationConfig={this.notificationConfig}
+            contextMenuConfig={this.contextMenuConfig}
+            keyboardConfig={this.keyboardConfig}
+
+            contextMenuHandler={this.contextMenuHandler}
+            beforeEditActionHandler={this.beforeEditActionHandler}
+            editActionHandler={this.editActionHandler}    
+            clickActionHandler={this.clickActionHandler}   
+            decorationActionHandler={this.decorationActionHandler}
+            layoutHandler={this.layoutHandler}  
+            tipHandler={this.tipHandler}
+            idGeneratorHandler={this.idGeneratorHandler}
+            selectionChangeHandler={this.selectionChangeHandler}
+            actionLabelHandler={this.actionLabelHandler}
+
+            showRightFlyout={showRightFlyout}
+            rightFlyoutContent={rightFlyoutContent}
+
+            showBottomPanel={showBottomPanel}
+            bottomPanelContent={bottomPanelContent}
+
+            showTopPanel={showTopPanel}
+            topPanelContent={topPanelContent}
+        >
+        </CommonCanvas>
+    </div>
+```
+
+### Config objects
+Common canvas has five **optional** configuration objects: config, toolbarConfig, notificationConfig, contextMenuConfig and keyboardConfig.
+They are documented here:
+[Config Objects](/2.1-Config-Objects)
+
+### Handlers
+There are several **optional** handlers implemented as callback functions. They are contextMenuHandler, editActionHandler, beforeEditActionHandler, clickActionHandler, decorationActionHandler, layoutHandler, tipHandler, idGeneratorHandler, selectionChangeHandler and actionLabelHandler. They are documented here:
+[Common Canvas Callback](/2.2-Common-Canvas-callbacks)
+
+### Right-flyout panel parameters
+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.
+
+### Bottom panel parameters
+The bottom panel appears below the canvas area and between the palette and the right flyout panel. You can add whatever content you like to this panel. There are two **optional** parameters to let you manage the bottom panel. These are:
+
+- showBottomPanel: This can be true or false to indicate whether the bottom panel is shown or not. The default is false.
+- bottomPanelContent: content to display in the bottom panel which is a JSX object. Nothing is displayed by default.
+
+### Top panel parameters
+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.
+
+### Localization
+You can customize `<CommonCanvas>` using the `<IntlProvider>` object to [display translated test](/#localization)
+
+## Creating nodes on the canvas
+
+Nodes can be created on the canvas by the user in two ways:
+
+* By dragging a node from the palette onto the canvas background
+* By dragging a node from outside the canvas
+
+The first technique is provided by Common canvas. The second requires some development work which is documented here:
+[Enabling node creation from external object](/2.3-Enabling-node-creation-from-external-object)
+
+
+## Keyboard support
+
+Common canvas supports a number of keyboard interactions as follows:
+
+|Keyboard Shortcut|Action|Description|
+|---|---|---|
+|Ctrl/Cmnd + a|selectAll|Select All objects   
+|delete|deleteSelectedObjects|Delete currently selected objects|
+|Ctrl/Cmnd + x|cut|Cut selected objects to the clipboard|
+|Ctrl/Cmnd + c|copy|Copy selected objects to the clipboard|
+|Ctrl/Cmnd + v|paste|Paste objects from the clipboard. If the mouse cursor is over <br>the canvas, objects will be pasted at the cursor position or, <br>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](/2.1-Config-Objects#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](/2.2-Common-Canvas-callbacks#editactionhandler) callback will be called with the `data.editType` parameter set to the action above and the `data.editSource` parameter set to "keyboard".
diff --git a/docs/2.0.1-Canvas-Editor.md b/docs/2.0.1-Canvas-Editor.md
@@ -0,0 +1,11 @@
+The Canvas Editor displays the flow to the user and allows the user to interact with the flow using the mouse/trackpad and the keyboard.
+
+The editor displays the following object types which the user can interact with:
+
+## Nodes
+## Links
+## Comments
+## The Canvas background
+
+
+[Still under construction]
diff --git a/docs/2.0.1.1-Nodes.md b/docs/2.0.1.1-Nodes.md
@@ -0,0 +1 @@
+[Under construction]
diff --git a/docs/2.0.1.2-Links.md b/docs/2.0.1.2-Links.md
@@ -0,0 +1,62 @@
+## Introduction
+Common-canvas is designed to display one link line on the canvas for each link defined in the pipeline flow. There are three types of link supported by common canvas: data links; association links; and comment links. Links can be enhanced by:
+
+* Overriding the CSS styles applied to the elements of the link line
+* By specifying decorations for the link
+
+## Data Links
+Data links are designed to model a flow from a source node to a target node. Data links are defined in the pipeline flow to connect a port on the source node to a port on the target node. The host application can choose whether or not to display ports on the nodes. Data links are typically displayed with an arrow head to display the flow along the link from source to target.
+
+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.
+
+## Association Links
+
+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. (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.
+
+## Comment Links
+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.
+
+If a comment 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 "commentLink"
+* srcNodeId - the ID of comment.
+* trgNodeId - the ID of the node the comment is connected to.
+* app_data - any application specific data that was previously specified for the link in the pipeline flow or through the canvas controller API.
+
+
+## Display of links
+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:
+
+| Purpose      | DOM tag                             | Classes      | Notes                            |
+| :---------- | :----------------------------------- | :---------- | :----------------------------------- |
+|Group	| g |	d3-link group |	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).