#1893 New common-canvas documentation required (#1894) (#1897)

canvas_modules/harness/src/client/components/custom-canvases/stages/stages-canvas.jsx

@@ -19,6 +19,8 @@ import PropTypes from "prop-types";
 
 import { CommonCanvas, CanvasController } from "common-canvas"; // eslint-disable-line import/no-unresolved
 
+import { Edit16 } from "@carbon/icons-react";
+
 import MultiUndoPanel from "./multi-undo-panel";
 import StagesCanvasFlow from "./stagesCanvas.json";
 import StagesPalette from "../../../../../test_resources/palettes/stagesPalette.json";

docs/mkdocs.yml

@@ -55,7 +55,8 @@ nav:
       - Nodes: 01.01.01-nodes.md
       - Links: 01.01.02-links.md
       - Comments: 01.01.03-comments.md
-      - Background: 01.01.04-background.md
+      - Decorations: 01.01.04-decorations.md
+      - Background: 01.01.05-background.md
     - Palette: 01.02-palette.md
     - Context Menu: 01.03-context-menu.md
     - Context Toolbar: 01.04-context-toolbar.md

docs/pages/01-canvas-components.md

@@ -2,6 +2,8 @@
 
 The Elyra Canvas package delivers two decoupled React objects: Common Canvas and Common Properties.
 
+<img src="../assets/components.png" width="900" />
+
 ## Common Canvas
 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 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.
 
@@ -17,35 +19,33 @@ The common-canvas user can perform operations such as:
 * 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](03.07-external-objects.md).
 * And much more! ...
 
-
 ### Common Canvas Components
 
-Common canvas has several constituent parts that are visible to the user:
+Common canvas has several constituent parts that can be visible to the user and can be customized by the application:
+
+<img src="../assets/cc-elements.png" width="900" />
 
 * [Flow editor](01.01-flow-editor.md) - the main area of the UI where the flow is displayed and edited
 * [Palette](01.02-palette.md) - a set of node templates that can be dragged to the canvas to create new nodes
 * [Context menu](01.03-context-menu.md) - a menu of options for nodes, comments, etc
 * [Context toolbar](01.04-context-toolbar.md) - 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
 * State Tag - a small pill shaped component that appears over the canvas to indicate its state: locked or read-only.
 
+In addition, there are three optional panels where application specific output can be displayed such as
+properties, log info or data previews.
+<img src="../assets/cc-panels.png" width="900" />
 
-and it handles:
+* 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
 
-  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.
 
 ## Common Properties
-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.
+[Common properties](04-common-properties.md) 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.
 
+<img src="../assets/cp-example.png" width="300" />
 
 
 

docs/pages/01.01-flow-editor.md

@@ -1,13 +1,27 @@
 # Flow Editor Overview
 
-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.
+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.
+
+<img src="../assets/cc-flow-editor.png" width="900" />
+
 
 The editor displays the following object types which the user can interact with:
 
 * [Nodes](01.01.01-nodes.md)
 * [Links](01.01.02-links.md)
 * [Comments](01.01.03-comments.md)
-* [Flow Editor background](01.01.04-background.md)
+* [Decorations](01.01.04-decorations.md)
+* [Flow Editor background](01.01.05-background.md)
+
+## Pipeline Flow
 
+The defintions of objects displayed within the flow editor are contained in a JavaScript object descibed by the [pipeline flow schema](https://github.com/elyra-ai/pipeline-schemas/blob/main/common-pipeline/pipeline-flow/pipeline-flow-v3-schema.json). 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:
+```js
+    const pflow - canvasController.getPipelineFlow();
+```
+and a previously saved pipeline flow can be provided to common-canvas also using the canvas controller:
 
+```js
+    canvasController.setPipelineFlow(pFlow);
+```
 

docs/pages/01.01.01-nodes.md

@@ -3,8 +3,43 @@
 ## Introduction
 
 Nodes displayed in the flow editor can represent data operations or other types of
-operations for the type of flow the application displays.
+operations for the type of flow the application displays. Nodes are joined together in a flow by 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 and large number of different layouts depending on the needs of the application, as shown below:
+
+<img src="../assets/cc-node1.png" width="110" />
+<img src="../assets/cc-node2.png" width="300" />
+<img src="../assets/cc-node3.png" width="240" />
+<img src="../assets/cc-node4.png" width="115" />
+<img src="../assets/cc-node5.png" width="280" />
+<img src="../assets/cc-node6.png" width="120" />
+<img src="../assets/cc-node7.png" width="290" />
+
+Nodes are made up of a number of display elements such as:
+
+* an image
+* a label
+* a background shape
+* selection highlighting
+* ellipsis icon (if context menus are enabled)
+* ports
+* decorations
+
+## Customization
+Nodes can be customized in the following ways:
+
+* Setting [canvas configuration](03.02.01-canvas-config/#nodes) fields
+* Overrdiing CSS. A node contains the following objects with specified classes:
+
+| Purpose      | DOM tag                             | Classes      | Notes                            |
+| :---------- | :----------------------------------- | :---------- | :----------------------------------- |
+|Group	        | g | d3-node-group |	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 |
 
-Nodes are made up of a number of display elements such as an image, label background shape etc.
 
-[Under construction]

docs/pages/01.01.02-links.md

@@ -53,10 +53,10 @@ Links are drawn on the canvas using SVG elements in the DOM. Each link has a top
 
 | 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. |
+|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).
+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).

docs/pages/01.01.03-comments.md

@@ -2,4 +2,55 @@
 
 ## Introduction
 
-[Under construction]
+Comments are used to display explanatory information to the user about the flow. Comments can be standalone:
+<img src="../assets/cc-comment1.png" width="290" />
+
+or connected to one or more nodes with a link line:
+
+<img src="../assets/cc-comment2.png" width="200" />
+
+## Creating comments
+
+Comments can be created by the user by clicking a button on the toolbar or clicking an option in the flow editor background context menu.
+
+| Doing this: | Yields this: |
+|----| ------|
+| <img src="../assets/cc-comment-reg-edit.png" width="250" /> | <img src="../assets/cc-comment-reg-type.png" width="250" /> |
+
+
+
+The comment can be edited by the user by double-clicking it or selecting an edit option from the context menu or context toolbar depending on which is enabled.
+
+Comments can be sized by dragging the border.
+
+
+## Connecting a comment to a node
+
+By default, the connection is shown as a dashed link line. The user can create a connection by dragging the small gray blob at the bottom of the comment and dropping it onto the targte node or by selecting one of more nodes and then creating the comment. This will automatically add comment links from the comments to each selected node.
+
+
+## Markdown
+
+Optionally, the applicaton can switch on [markdown support](03.02.01-canvas-config/#enablemarkdownincomments) 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.
+
+| Entering this: | Yields this: |
+|----| ------|
+| <img src="../assets/cc-comment-markdown-edit.png" width="320" /> | <img src="../assets/cc-comment-markdown-out.png" width="310" /> |
+
+## Customization
+
+Comments can be customized in the following ways:
+
+* Setting the [enableMarkdownInComments](03.02.01-canvas-config/#enablemarkdownincomments) canvas configuration fields
+* Overrdiing CSS. A comment contains the following objects with specified classes:
+
+| Purpose      | DOM tag                             | Classes      | Notes                            |
+| :---------- | :----------------------------------- | :---------- | :----------------------------------- |
+|Group	        | g | d3-comment-group |	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 |
+
+

docs/pages/01.01.04-decorations.md

@@ -0,0 +1,5 @@
+# Decorations
+
+## Introduction
+
+[Under construction]

docs/pages/03-common-canvas.md

@@ -1,7 +1,7 @@
 # Getting started with Common Canvas
 
 ## 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. Here's some sample code to show the minimum needed to get a working canvas.
+   Common-canvas is a react component that can be used in your react application to display a fully-functional canvas user interface. The `<CommonCanvas>` component is displayed in a `<div>` provided by your application. Here's some sample code to show the [minimum code](https://github.com/elyra-ai/canvas/blob/master/canvas_modules/harness/src/client/app-tiny.js) needed to get a working canvas.
 
 ```
 import React from "react";
@@ -30,6 +30,14 @@ class App extends React.Component {
 }
 ```
 
+This code will display this:
+
+<img src="../assets/cc-app-tiny.png" width="800" />
+
+
+The ["Tiny App"](https://elyra-canvas-test-harness.u20youmx4sm.us-south.codeengine.appdomain.cloud/#/app-tiny) is available as part of the test harness funciton. Click here to begin and 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 using the scroll gesture.
+
+
 ## Canvas Controller
 
 The only mandatory parameter for the `<CommonCanvas>` component is a regular JavaScript object called the [CanvasController](03.04-canvas-controller.md).