#1768 Improve format of mkdocs version of Elyra Canvas Help (part 2) (#…

…1771)

.github/workflows/deploy-docs.yml

@@ -29,7 +29,7 @@ jobs:
     runs-on: ubuntu-latest
     defaults:
       run:
-        working-diretory: ./docs
+        working-directory: ./docs
     steps:
       - uses: actions/checkout@v4
       - uses: actions/setup-python@v5

docs/mkdocs.yml

@@ -69,7 +69,18 @@ nav:
       - Notification Config: 02-canvas/02-configs/03-notification-config.md
       - Context Menu Config: 02-canvas/02-configs/04-context-menu-config.md
       - Keyboard Config: 02-canvas/02-configs/05-keyboard-config.md
-    - Callbacks: 02-canvas/03-callbacks/index.md
+    - Callbacks:
+      - 02-canvas/03-callbacks/index.md
+      - Context Menu Handler: 02-canvas/03-callbacks/01-context-menu-handler.md
+      - Edit Action Handler: 02-canvas/03-callbacks/02-edit-action-handler.md
+      - Before Edit Action Handler: 02-canvas/03-callbacks/03-before-edit-action-handler.md
+      - Layout Handler: 02-canvas/03-callbacks/04-layout-handler.md
+      - Decoration Action Handler: 02-canvas/03-callbacks/05-decoration-action-handler.md
+      - Tip Handler: 02-canvas/03-callbacks/06-tip-handler.md
+      - ID Generator Handler: 02-canvas/03-callbacks/07-id-generator-handler.md
+      - Selection Change Handler: 02-canvas/03-callbacks/08-selection-change-handler.md
+      - Click Action Handler: 02-canvas/03-callbacks/09-click-action-handler.md
+      - Action Label Handler: 02-canvas/03-callbacks/10-action-label-handler.md
     - Canvas Controller:
       - 02-canvas/04-controller/index.md
       - Styling Canvas Objects: 02-canvas/04-controller/01-Styling-Objects.md

docs/pages/02-canvas/03-callbacks/01-context-menu-handler.md

@@ -0,0 +1,105 @@
+# Context Menu Handler
+
+## contextMenuHandler
+```js
+    contextMenuHandler(source, defaultMenu)
+```
+This callback is used for both 'context menus' and, if the [`enableContextToolbar`](2.1-Config-Objects.md#enablecontexttoolbar) canvas config option is set to `true`, for 'context toolbars'.
+
+If this callback is not provided common canvas will handle context menu/toolbars, and their actions, internally. You only need to implement this callback if you want to add or remove options to/from the context menu/toolbar.
+
+The job of this callback is to tell common canvas what items to display in the context menu/toolbar.
+
+### For Context Menu
+
+For context menus this will be dependent on what object or set of objects the context menu was requested for by the user.
+
+This callback will be called if the user performs a context menu gesture (such as mouse 'right click') on a:
+
+* node
+* link
+* comment
+* port
+* on the canvas background or
+* if a number of objects are selected, the combination of objects.
+
+This callback must return an array that defines the menu to be displayed. If the callback is *not* provided, a default context menu (the defaultMenu passed into the handler) will be displayed by the common canvas.
+
+The source object passed in looks like this:
+```js
+    {
+      type: "node",
+      targetObject: {<object_info>},
+      selectedObjectIds: ["node_1", "node_2"],
+      mousePos: {x: "10", y:"20"}
+    }
+```
+**type** - Indicates type of object for which the context menu was selected. Can be "node", "port", "link", "canvas" or "comment"
+
+**targetObject** - The object for which the context menu was requested. Only provided when type is "node" or "comment"
+
+**selectedObjectIds** -  An array containing the IDs of all currently selected nodes and/or comments
+
+**mousePos** - An object containing the coords of the mouse when the context menu was requested
+
+The callback would need to return an array, that describes the context menu to be displayed, that looks something like this:
+```js
+    [
+     {action: "deleteSelectedObjects", label: "Delete"},
+     {divider: true},
+     {action: "myAction", label: "My Action"}
+     {action: "myUnavailableAction", label: "A test disabled item", enable: false}
+    ]
+```
+There is one element in the array for each entry in the context menu. An entry can be either a context menu item, which consists of a label and an action, or a divider, whose field would need to be set to true.
+
+Actions can be either internal (implemented inside the common canvas, like "deleteSelectedObjects" above) or external (like "myAction").
+
+Existing internal actions are:
+
+* selectAll
+* cut
+* copy
+* paste
+* undo
+* redo
+* createSupernode
+* expandSupernode
+* collapseSupernode
+* deleteSelectedObjects
+* createComment
+* deleteLink
+* disconnectNode
+* highlightBranch
+* highlightDownstream
+* highlightUpstream
+* unhighlight
+
+External actions are custom actions you want common canvas to display for your application. To get common canvas to display your action you would need to return an array from the callback that includes a menu item for the action.
+
+When the user clicks the option in the context menu matching your action common canvas will call the [editActionHandler](#editactionhandler) callback so you'll need to implement some code in that callback to execute the intended action. If you want to simply add your action to the default context menu provided by common canvas you can take the defaultMenu parameter provided to the callback and add your menu item to it. Alternatively, you can provide a complete new context menu of your own.
+
+Here is a sample implementation of contextMenuHandler, which takes a source object (described above) and the defaultMenu as parameters, and adds a custom action to the default menu when the user 'right clicks' the canvas background.
+
+```js
+    contextMenuHandler(source, defaultMenu) {
+      let customMenu = defaultMenu;
+      if (source.type === "canvas") {
+	customMenu = customMenu.concat({ action: "myAction", label: "My Action" });
+      }
+      return customMenu;
+    }
+```
+In addition to adding the context menu item, you would also need to implement the editActionHandler callback to execute the action, like this:
+```js
+    editActionHandler(data) {
+      if (data.editType === "myAction") {
+        // Execute my action code here.
+      }
+    }
+```
+Tip: To avoid any future name clashes with internal actions you should make sure you action names are unique. For example, you could add a prefix to your action names eg. `$MyApp_action` where `$MayApp_` is the prefix for all your actions.
+
+### For Context Toolbar
+
+For context toolbars, this will be dependent on which object the mouse cursor is currently hovering over (which may be different to any of the currently selected objects).

docs/pages/02-canvas/03-callbacks/02-edit-action-handler.md

@@ -0,0 +1,50 @@
+# Edit Action Handler
+
+## editActionHandler
+```js
+    editActionHandler(data, command)
+```
+This callback is optional. You don't *need* to implement anything for it and it doesn't return anything. It is called whenever the user does the following types of action on the canvas:
+
+* Clicks a tool in the toolbar.
+* Clicks an option in the context menu.
+* Presses a [key combination](2.0-Common-Canvas-Documentation.md#keyboard-support) on the keyboard to cause the canvas to change.
+* Performs some direct manipulation on the canvas such as:
+    * Creates a node (createNode)
+    * Moves one or a set of nodes/comments (moveObjects)
+    * Edits a comment (editComment)
+    * Links two nodes together (linkNodes)
+    * Links a comment to a node (linkComment)
+    * Resizes a supernode (resizeObjects)
+    * Resizes a comment (editComment)
+    * Expands a supernode in place (expandSuperNodeInPlace)
+    * Navigates into a sub-flow in a supernode (displaySubPipeline)
+    * Navigates out of a sub-flow in a supernode (displayPreviousPipeline)
+
+
+This callback is called *after* the common-canvas internal object model has been updated.  This callback is provided with two parameters: `data` and `command`.
+
+1. **data parameter** - that looks like this. The data provided can vary depending on the action the user performed.
+```js
+    {
+      editType: "createComment",
+      editSource: "contextmenu",
+      selectedObjects: [],
+      selectedObjectIds: [],
+      offsetX: 100,
+      offsetY: 42
+    }
+```
+
+   + ***editType*** - This is the action that originates from either the toolbar, context menu, keyboard action or direct manipulation on the canvas. If you specified your own action in the context menu or in the toolbar this field will be your action's name.
+
+   + ***editSource*** - This is the source of the action. It can be set to "toolbar", "contextmenu", "keyboard" or "canvas" (for an action caused by direct manipulation on the canvas).
+
+   + ***selectedObjects*** - An array of the currently selected objects.
+
+   + ***selectedObjectIds*** - An array of the IDs of currently selected objects. Included for backward compatibility.
+
+   + ***Other fields*** - Numerous other fields which vary based on the action and the source of the action.
+
+2. **command parameter** - This is a Javascript class which is the command object that was added to the command stack and executed to run the action 'requested' by the user. If the user performed an `undo` action this will be the command that has been undone. If the user performed a `redo` action this will be the command that was redone. The command object may contain fields which are connected with the execution of the command.
+

docs/pages/02-canvas/03-callbacks/03-before-edit-action-handler.md

@@ -0,0 +1,25 @@
+# Before Edit Action Handler
+
+
+## beforeEditActionHandler
+```js
+    beforeEditActionHandler(data, command)
+```
+This callback is optional. You don't *need* to implement anything for it but if you do implement it you **must** return either a data object or null. This callback is called in all the same instances where `editActionHandler` is called. The difference is that this callback is called *before* the internal object model is updated. This gives your application the opportunity to examine the action that is about to be performed and either: let it continue; modify it and let it continue; or cancel it.
+
+ This callback is provided with two parameters: `data` and `command`.
+
+1. **data parameter** - this is the same as the data object described for `editActionHandler` (see above)
+2. **command parameter** - typically this will be null but for `undo` operations (that is where data.editType === "undo") this will be the command that is about to be undone. For `redo` operations (that is where data.editType === "redo") this will be the command that is about to be redone.
+
+This callback *must* return either the data object that was passed in or null. `beforeEditActionHandler` will behave as follows based on what is returned:
+
+* If the data object is returned unmodified: the action will be performed as normal.
+* If the data object is returned modified: the action will be performed based on the modified data object. This means your application can alter the behavior of the action that will be performed. For example, you could intercept a `createNode` command and change the label for the new node in the nodeTemplate to something different. Then when the node is created the new label will be used. It is recommended you be **very** **very** careful when updating this object since there is no error checking in common-canvas to ensure you modified the object correctly.
+* If `null` is returned: the action will be cancelled and not performed on the internal object model nor will `editActionHandler` be called.
+
+If you need to do any asynchronous activity in the beforeEditActionHandler callback you can:
+
+* Return null from the callback - which will cancel the current action
+* Do your asynchronous activity. While this is happening, the user ought to be prevented from modifying the canvas so you should display some sort of progress indicator or modal dialog to inform the user that some activity is occurring.
+* Then call `CanvasController.editActionHandler(data)` passing in the `data` object as a parameter with the modified properties. This will then execute the action as before. Note: This means the `beforeEditActionHandler` will be called a second time so be sure you put in a check to make sure you don't get into a loop.

docs/pages/02-canvas/03-callbacks/04-layout-handler.md

@@ -0,0 +1,12 @@
+# Layout Handler
+
+This is an optional handler you don't need to implement anything for it unless you want to. The layoutHandler callback, when provided, is called for each node on the canvas and allows the application to customize the node layout properties on a
+node-by-node basis.
+
+## layoutHandler
+```js
+    layoutHandler(data)
+```
+ The callback should return a Javascript object whose properties will override the default properties for node layout. The callback is provided with a parameter `data` which is the node object. Your code can look at the node properties and decide which properties it needs to override. This can be used to change the node shape, styling and position and size of node elements like the image, main label etc.
+
+For more details see: [Customizing Node Layout](02-canvas/07-layout/01-Customizing-Node-Layout.md)

docs/pages/02-canvas/03-callbacks/05-decoration-action-handler.md

@@ -0,0 +1,16 @@
+# Decoration Action Handler
+
+## decorationActionHandler
+```js
+    decorationActionHandler(object, id, pipelineId)
+```
+Decorations are small images that can be displayed on or near to your nodes and links. They can be for display only or actionable (so the user can click on them). See the canvas JSON schema for information on how to define decorations for your nodes.
+
+This callback is called when the user clicks on an actionable decoration. You don't need to implement anything for this callback unless you added actionable decorations to your nodes. It doesn't return anything. It is called whenever the user clicks on a decoration that you added to a node in the canvas JSON.
+
+It is provided with two parameters:
+
+* object -- the node or link with which the decoration is associated.
+* id -- the ID of the decoration that you provided in the canvas JSON
+* pipelineId -- the ID of the pipeline for the node.
+