diff --git a/canvas_modules/harness/src/client/components/custom-canvases/stages/stages-canvas.jsx b/canvas_modules/harness/src/client/components/custom-canvases/stages/stages-canvas.jsx index 3a8eb02564..c721d4a4a6 100644 --- a/canvas_modules/harness/src/client/components/custom-canvases/stages/stages-canvas.jsx +++ b/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"; diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 3d332e2baf..bbe8fdadcc 100644 --- a/docs/mkdocs.yml +++ b/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 diff --git a/docs/pages/01-canvas-components.md b/docs/pages/01-canvas-components.md index 05a7a7778a..aa3c17258d 100644 --- a/docs/pages/01-canvas-components.md +++ b/docs/pages/01-canvas-components.md @@ -2,6 +2,8 @@ The Elyra Canvas package delivers two decoupled React objects: Common Canvas and Common Properties. + + ## 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,10 +19,11 @@ 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: + + * [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 @@ -28,24 +31,21 @@ Common canvas has several constituent parts that are visible to the user: * [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. + -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. + diff --git a/docs/pages/01.01-flow-editor.md b/docs/pages/01.01-flow-editor.md index fe21297d4c..bab6dd332f 100644 --- a/docs/pages/01.01-flow-editor.md +++ b/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. + + + 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); +``` diff --git a/docs/pages/01.01.01-nodes.md b/docs/pages/01.01.01-nodes.md index d48282040b..f4018df40d 100644 --- a/docs/pages/01.01.01-nodes.md +++ b/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: + + + + + + + + + +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] diff --git a/docs/pages/01.01.02-links.md b/docs/pages/01.01.02-links.md index 1adca82cd6..9650954a61 100644 --- a/docs/pages/01.01.02-links.md +++ b/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). \ No newline at end of file +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). diff --git a/docs/pages/01.01.03-comments.md b/docs/pages/01.01.03-comments.md index 7a116849d1..1e277dda52 100644 --- a/docs/pages/01.01.03-comments.md +++ b/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: + + +or connected to one or more nodes with a link line: + + + +## 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: | +|----| ------| +| | | + + + +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: | +|----| ------| +| | | + +## 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 | + + diff --git a/docs/pages/01.01.04-decorations.md b/docs/pages/01.01.04-decorations.md new file mode 100644 index 0000000000..0ffd90779b --- /dev/null +++ b/docs/pages/01.01.04-decorations.md @@ -0,0 +1,5 @@ +# Decorations + +## Introduction + +[Under construction] diff --git a/docs/pages/01.01.04-background.md b/docs/pages/01.01.05-background.md similarity index 100% rename from docs/pages/01.01.04-background.md rename to docs/pages/01.01.05-background.md diff --git a/docs/pages/03-common-canvas.md b/docs/pages/03-common-canvas.md index bd1794c037..2a9adaf6f2 100644 --- a/docs/pages/03-common-canvas.md +++ b/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 `` component is displayed in a `
` 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 `` component is displayed in a `
` 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: + + + + +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 `` component is a regular JavaScript object called the [CanvasController](03.04-canvas-controller.md). diff --git a/docs/pages/assets/cc-app-tiny.png b/docs/pages/assets/cc-app-tiny.png new file mode 100644 index 0000000000..35a3644a16 Binary files /dev/null and b/docs/pages/assets/cc-app-tiny.png differ diff --git a/docs/pages/assets/cc-comment-markdown-edit.png b/docs/pages/assets/cc-comment-markdown-edit.png new file mode 100644 index 0000000000..1cde89be11 Binary files /dev/null and b/docs/pages/assets/cc-comment-markdown-edit.png differ diff --git a/docs/pages/assets/cc-comment-markdown-out.png b/docs/pages/assets/cc-comment-markdown-out.png new file mode 100644 index 0000000000..7345eb0cb1 Binary files /dev/null and b/docs/pages/assets/cc-comment-markdown-out.png differ diff --git a/docs/pages/assets/cc-comment-reg-edit.png b/docs/pages/assets/cc-comment-reg-edit.png new file mode 100644 index 0000000000..6ab308f8e1 Binary files /dev/null and b/docs/pages/assets/cc-comment-reg-edit.png differ diff --git a/docs/pages/assets/cc-comment-reg-type.png b/docs/pages/assets/cc-comment-reg-type.png new file mode 100644 index 0000000000..53c531eb9f Binary files /dev/null and b/docs/pages/assets/cc-comment-reg-type.png differ diff --git a/docs/pages/assets/cc-comment1.png b/docs/pages/assets/cc-comment1.png new file mode 100644 index 0000000000..8a5a1f39d2 Binary files /dev/null and b/docs/pages/assets/cc-comment1.png differ diff --git a/docs/pages/assets/cc-comment2.png b/docs/pages/assets/cc-comment2.png new file mode 100644 index 0000000000..807b4d0b7e Binary files /dev/null and b/docs/pages/assets/cc-comment2.png differ diff --git a/docs/pages/assets/context-menu.png b/docs/pages/assets/cc-context-menu.png similarity index 100% rename from docs/pages/assets/context-menu.png rename to docs/pages/assets/cc-context-menu.png diff --git a/docs/pages/assets/context-toolbar-open-overflow.png b/docs/pages/assets/cc-context-toolbar-open-overflow.png similarity index 100% rename from docs/pages/assets/context-toolbar-open-overflow.png rename to docs/pages/assets/cc-context-toolbar-open-overflow.png diff --git a/docs/pages/assets/context-toolbar.png b/docs/pages/assets/cc-context-toolbar.png similarity index 100% rename from docs/pages/assets/context-toolbar.png rename to docs/pages/assets/cc-context-toolbar.png diff --git a/docs/pages/assets/cc-elements.png b/docs/pages/assets/cc-elements.png new file mode 100644 index 0000000000..dd910a07a8 Binary files /dev/null and b/docs/pages/assets/cc-elements.png differ diff --git a/docs/pages/assets/cc-flow-editor.png b/docs/pages/assets/cc-flow-editor.png new file mode 100644 index 0000000000..59588dabdc Binary files /dev/null and b/docs/pages/assets/cc-flow-editor.png differ diff --git a/docs/pages/assets/cc-node1.png b/docs/pages/assets/cc-node1.png new file mode 100644 index 0000000000..a120be2270 Binary files /dev/null and b/docs/pages/assets/cc-node1.png differ diff --git a/docs/pages/assets/cc-node2.png b/docs/pages/assets/cc-node2.png new file mode 100644 index 0000000000..064802462f Binary files /dev/null and b/docs/pages/assets/cc-node2.png differ diff --git a/docs/pages/assets/cc-node3.png b/docs/pages/assets/cc-node3.png new file mode 100644 index 0000000000..92c0b14f63 Binary files /dev/null and b/docs/pages/assets/cc-node3.png differ diff --git a/docs/pages/assets/cc-node4.png b/docs/pages/assets/cc-node4.png new file mode 100644 index 0000000000..7f54de125b Binary files /dev/null and b/docs/pages/assets/cc-node4.png differ diff --git a/docs/pages/assets/cc-node5.png b/docs/pages/assets/cc-node5.png new file mode 100644 index 0000000000..293ce4662e Binary files /dev/null and b/docs/pages/assets/cc-node5.png differ diff --git a/docs/pages/assets/cc-node6.png b/docs/pages/assets/cc-node6.png new file mode 100644 index 0000000000..50fe7ca66b Binary files /dev/null and b/docs/pages/assets/cc-node6.png differ diff --git a/docs/pages/assets/cc-node7.png b/docs/pages/assets/cc-node7.png new file mode 100644 index 0000000000..009450df06 Binary files /dev/null and b/docs/pages/assets/cc-node7.png differ diff --git a/docs/pages/assets/cc-panels.png b/docs/pages/assets/cc-panels.png new file mode 100644 index 0000000000..8daaba4bed Binary files /dev/null and b/docs/pages/assets/cc-panels.png differ diff --git a/docs/pages/assets/components.png b/docs/pages/assets/components.png new file mode 100644 index 0000000000..267c998c72 Binary files /dev/null and b/docs/pages/assets/components.png differ diff --git a/docs/pages/assets/cp-example.png b/docs/pages/assets/cp-example.png new file mode 100644 index 0000000000..08cd4c9376 Binary files /dev/null and b/docs/pages/assets/cp-example.png differ