More docs changes (elyra-ai#1871)

docs/pages/03.03-callbacks.md

@@ -1,18 +1,18 @@
 # Callbacks Overview
 
 You can *optionally* provide callback listeners.  These will be called when the user interacts with the canvas and allows
-your application to perform processing specific to your application's needs based on user interactions.
+your application to perform processing specific to your application's needs based on user interactions. If you don't implement any of the callbacks, common-canvas will perform appropriate actions if necessary.
 
 These listeners are as follows:
 
 ### Context Menu Handler
 _Overrides or adds to the default context menu (or context toolbar) displayed for nodes, links, comments, etc._
 
 ### Before Edit Action Handler
-_Called for each edit action on the canvas. For example, when a node it created or a link is deleted or a comment is moved. It is called **before** the internal object model has been updated and the edit action has completed, so this can be used to cancel user actions if necessary._
+_Called for each edit action on the canvas. It is called **before** the internal object model has been updated and the edit action has completed, so this can be used to cancel user actions if necessary._
 
 ### Edit Action Handler
-_Called for each edit action on the canvas. For example, when a node it created or a link is deleted or a comment is moved. It is called **after** the internal object model has been updated and the edit action has completed._
+_Called for each edit action on the canvas. It is called **after** the internal object model has been updated and the edit action has completed._
 
 ### Layout Handler
 _Allows the application to override layout settings for nodes on a node-by-node basis._

docs/pages/03.03.01-context-menu-handler.md

@@ -1,27 +1,31 @@
 # Context Menu Handler
 
-This callback is optional. You don't need to implement anything for it. If implemented it must return an array of actions that describe what options are displayed on the [context menu](01.03-context-menu.md) or [context toolbar](01.04-context-toolbar.md).
+This callback is optional. You don't need to implement anything for it. If implemented, it must return an array of actions that describe what options are displayed in the [Context Menu](01.03-context-menu.md) or [Context Toolbar](01.04-context-toolbar.md).
 
-## contextMenuHandler
-```js
-    contextMenuHandler(source, defaultMenu)
-```
-This callback is used for both 'context menus' and, if the [`enableContextToolbar`](03.02.01-canvas-config.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 or provide your own menus in place of the default ones.
+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 or provide your own menus in place of the default ones.
 
-## For Context Menu
+## When is it called
 
-For context menus, this will be dependent on what object or set of objects the context menu was requested for by the user.
+### For Context Menu
 
-This callback will be called if the user performs a context menu gesture (such as mouse 'right click' or clicking an ellipsis icon) on a:
+This callback will be called if the [`enableContextToolbar`](03.02.01-canvas-config.md#enablecontexttoolbar) canvas config option is set to `false` (which is the default) and when the user performs a **context menu gesture**, such as mouse 'right click' or clicking an ellipsis icon, on a:
 
 * Node
 * Link
 * Comment
 * Port
-* On the canvas background or
+* The canvas background or
 * Combination of objects - if a number of objects are selected
+    - Note: With multiple selected objects, the convention is that a context menu/toolbar should display actions that are applicable to all the objects that are selected, rather than just the object for which the menu was requested.
+
+### For Context Toolbar
+
+This callback will be called if the [`enableContextToolbar`](03.02.01-canvas-config.md#enablecontexttoolbar) canvas config option is set to `true` and when the mouse cursor is **hovered over** any of the objects mentioend above.
+
+## contextMenuHandler
+```js
+    contextMenuHandler(source, defaultMenu)
+```
 
 #### 'source' parameter
 
@@ -44,13 +48,13 @@ The source object passed in looks like this:
 
 #### 'defaultMenu' parameter
 
-This is an array describing the default menu that common-canvas would usually display. If necessary, you can modify this array with your own elements or remove elements and then return the modified array.
+This is an array describing the default menu that common-canvas would usually display. If necessary, you can modify this array with your own elements or remove elements and then return the modified array. Alternatively, you can ignore this parameter and just return your own array.
 
-### Return
+## Return array for Context Menus
 
-The callback must return an array, that describes the context menu to be displayed. If the callback returns a null, then no menu will be displayed.
+The callback must return an array, that describes the context menu to be displayed. If the callback returns a null, then no menu/toolbar will be displayed.
 
-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. An action can be disabled by setting the 'enable' field to 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. An action can be disabled by setting the 'enable' field to false.
 
 Here's an example of a contextMenuHandler:
 
@@ -60,7 +64,7 @@ Here's an example of a contextMenuHandler:
             return [
                 { action: "deleteSelectedObjects", label: "Delete" },
                 { divider: true},
-                { action: "myAction", label: "My Action" },
+                { action: "myApp_Action1", label: "My Action" },
                 { action: "paste", label: "Paste from clipboard", enable: false }
             ];
         }
@@ -72,44 +76,29 @@ The above array will produce a context menu like this:
 
 <img src="../assets/context-menu.png" width="300" />
 
-When the user clicks an action in the menu the action is executed either internally or externally.
-
-### Internal acitons
-
-Internal actions are implemented inside the common canvas, like "deleteSelectedObjects" in the example above. Common-canvas supports a large number of [internal actions](03.11-internal-actions.md).
-
-### External actions
-
-External actions are custom actions you want common canvas to display for your application like "myAction", in the example above.
-Tip: To avoid any future name clashes with internal actions that might be added it is recommended you should make sure you action names are unique. For example, by adding a prefix to your application specfic actions.
-
-### Handling actions
-
-When the user clicks an option in the context menu (or context toolbar) it causes the [Before Edit Action Handler](03.03.02-before-edit-action-handler.md) and then the [Edit Action Handler](03.03.03-edit-action-handler.md) callbacks to be called.
-
-
 ### Customizing the default context menu
 
- 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.
+ 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" });
+            customMenu = customMenu.concat({ action: "myApp_Action1", label: "My Action" });
         }
         return customMenu;
     }
 ```
 
-## For Context Toolbar
+## Return array for Context Toolbar
 
 To display a context toolbar the same type of array is returned as described above for context menu. However, there are some extra fields for the action elements in the array. These are
 
-* isToolbarItem: This is a boolean. The default is false. If set to true the action will be added to the toolbar and if set to false the action will be displayed in the overflow menu.
-* icon: This is the icon to display for the action. If `isToolbarItem` is set to true you must provide an icon otherwise the action will show as an empty space in the toolbar. If an icon is specified and `isToolbarItem` is set to false, the icon will be displayed next to the action in the overflow menu.  For many internal actions, common canvas will automatically display an appropriate  carbon icon. See the [Internal Actions page](03.11-internal-actions.md/#action-names-with-built-in-icons) for a list of actions that have associated icons.
+**isToolbarItem** - This is a boolean. The default is false. If set to true the action will be added to the toolbar and if set to false the action will be displayed in the overflow menu.
+
+**icon** - This is the icon to display for the action. If `isToolbarItem` is set to true you must provide an icon otherwise the action will show as an empty space in the toolbar. If an icon is specified and `isToolbarItem` is set to false, the icon will be displayed next to the action in the overflow menu.  For many internal actions, common-canvas will automatically display an appropriate  Carbon icon. See the [Internal Actions page](03.11-internal-actions.md/#action-names-with-built-in-icons) for a list of actions that have associated icons.
 
 Dividers can also be added to the context toolbar by specifying 'toolbarItem: true'
 
@@ -142,9 +131,26 @@ And when the overflow icon is clicked, like this:
 
 
 #### Warning
-The contents of the context toolbar is dependent on which object the mouse cursor is currently **hovering** over (which may be different to any of the **currently selected** objects). You should make sure the actions you return in the array are applicable to the object the mouse cursor is hovering over or, if it is hovering over a selected object and other objects are alos selected, to the set of selected objects.
+The contents of the context toolbar is dependent on which object the mouse cursor is currently **hovering** over (which may be different to any of the **currently selected** objects). You should make sure the actions you return in the array are applicable to the object the mouse cursor is hovering over or, if it is hovering over a selected object and other objects are also selected, to the set of selected objects.
 
 To help decide whether the mouse cursor is hovering over a selected object or not, the application can call the canvas controller's helper function: 'isContextToolbarForNonSelectedObj(source)'. This will return true if the mouse cursor is over a non-selected object.
 
+## Actions
+
+When the user clicks an action in the menu the action is executed either internally or externally.
+
+### Internal acitons
+
+Internal actions are implemented inside common-canvas, like "deleteSelectedObjects" in the example above. Common-canvas supports a large number of [internal actions](03.11-internal-actions.md).
+
+### External actions
+
+External actions are custom actions you want common-canvas to display for your application like "myApp_Action1", in the example above.
+Tip: To avoid any future name clashes with internal actions that might be added it is recommended you should make sure you action names are unique. For example, by adding a prefix to your application specfic actions.
+
+### Handling actions
+
+When the user clicks an option in the context menu (or context toolbar) it causes the [Before Edit Action Handler](03.03.02-before-edit-action-handler.md) and then the [Edit Action Handler](03.03.03-edit-action-handler.md) callbacks to be called.
+
 
 

docs/pages/index.md

@@ -14,30 +14,30 @@ flows of linked nodes.
 
 Elyra Canvas:
 
-* Provides a comprehensive set of out-of-the-box UI components needed to build
+* Provides a **comprehensive set of out-of-the-box UI components** needed to build
 an application such as: flow editor, palette, toolbar, context menu, tooltips, command stack,
 clipboard support, notifications area, side panels and more!
-* Is a UI-centric library and is therefore back-end and run-time agnositc, meaning the flow can
+* Is a UI-centric library and is therefore **back-end and run-time agnositc**, meaning the flow can
 display connected nodes representing any kind of operations.
-* Is fast to get running - and easy to customize  - with extensive customization capability.
-* Is delivered as a package from the [NPM registry](https://www.npmjs.com/package/@elyra/canvas)
+* Is fast to get running - and **easy to customize**  - with extensive customization capability.
+* Is delivered as a package from the [**NPM registry**](https://www.npmjs.com/package/@elyra/canvas)
 * Delivers a JSON powered properties management component to allow easy, no-code handling of
 mulltiple properties windows - for when you have a multitude of node types each with their own range of properties.
-* Conforms to the [IBM Carbon](https://carbondesignsystem.com/all-about-carbon/what-is-carbon/) visual design language - and therefore plugs in easily to any application wishing to follow the Carbon standards including dark mode and light mode themes.
-* Delivers built-in accessibility so there's no need to worry about keyboard
+* Conforms to the [**IBM Carbon**](https://carbondesignsystem.com/all-about-carbon/what-is-carbon/) visual design language - and therefore plugs in easily to any application wishing to follow the Carbon standards including dark mode and light mode themes.
+* Delivers built-in **accessibility** so there's no need to worry about keyboard
 navigation, accessible color themes, screen reader integration, etc.
-* Is translated into 12 languages.
-* Is the mainstay of several IBM products/applications across multiple divisions.
+* Is translated into **12 languages**.
+* Is the mainstay of several IBM products/applications.
 
 
-## Elyra Canvas Components
+## Elyra Canvas Modules
 
-The elyra-ai/canvas repo contains three main components:
+The elyra-ai/canvas repo contains three main modules:
 
-* [Common Canvas](03-common-canvas.md) - This contains canvas functionality which is packaged into the [elyra/canvas NPM module](https://www.npmjs.com/package/@elyra/canvas) and deployed to the NPM registry. It provides a way for an application to display a flow of data operations (shown as a set of nodes connected with links) to the user and to allows the user to interact with the display to modify the flow. Common canvas is a react component which can be imported, and is assisted by a regular JavaScript class called `CanvasController` which provides an API and handles the internal data model of the flow. Common canvas is highly customizable where node shape and appearance, colors, styles layout etc can all be customized by your application code. Common canvas handles flows parsed from, and serialized into, a pipeline flow JSON document. It's palette of available nodes is also
+* [Common-Canvas](03-common-canvas.md) - This contains canvas functionality which is packaged into the [elyra/canvas NPM module](https://www.npmjs.com/package/@elyra/canvas) and deployed to the NPM registry. It provides a way for an application to display a flow of data operations (shown as a set of nodes connected with links) to the user and to allows the user to interact with the display to modify the flow. Common canvas is a react component which can be imported, and is assisted by a regular JavaScript class called `CanvasController` which provides an API and handles the internal data model of the flow. Common canvas is highly customizable where node shape and appearance, colors, styles layout etc can all be customized by your application code. Common canvas handles flows parsed from, and serialized into, a pipeline flow JSON document. It's palette of available nodes is also
 customized usging a JSON document
 
-* [Common Properties](04-common-properties.md) - This contains properties functionality which is packaged into the [elyra/canvas NPM module](https://www.npmjs.com/package/@elyra/canvas) and deployed to the NPM registry. It provides a way to translate a JSON document, which describes a set of properties with UI hints, into a working properties dialog panel. Common properties is a React component and has an associated properties controller object.
+* [Common-Properties](04-common-properties.md) - This contains properties functionality which is packaged into the [elyra/canvas NPM module](https://www.npmjs.com/package/@elyra/canvas) and deployed to the NPM registry. It provides a way to translate a JSON document, which describes a set of properties with UI hints, into a working properties dialog panel. Common properties is a React component and has an associated properties controller object.
 
 * [Test Harness](https://github.com/elyra-ai/canvas/tree/master/canvas_modules/harness#test-harness) - This provides a node.js app which displays a UI which allows you to try out some sample applications and various features of the common canvas and common properties components. Bear in mind this is not supposed to be a fully functional app but is, as the name suggests, a framework for testing. In the test harness, you can select one of the sample applications or select `None` as the sample app and then select a test canvas file from the `Canvas Diagram` drop down list and a test palette from the `Canvas palette` drop down list.