Merge pull request #238 from node-red/api-updates

Add editor API docs

Author: knolleary

README.md

@@ -6,7 +6,7 @@ node-red.github.io
 ### Contributing / Fixes
 
 For simple typos and single line fixes please just raise an issue pointing out
-our mistakes. For larger changes, please raise them on the [mailing list](https://groups.google.com/forum/#!forum/node-red), or [Slack team](http://nodered.org/slack/) #docs channel, and if necessary provide content for review on the [wiki](https://github.com/node-red/node-red.github.io/wiki).
+our mistakes. For larger changes, please discuss them on the [forum](https://discourse.nodered.org) or [Slack team](http://nodered.org/slack/) #docs channel.
 
 If you need to raise a pull request please read our
 [contribution guidelines](https://github.com/node-red/node-red/blob/master/CONTRIBUTING.md)
@@ -19,10 +19,10 @@ Fork the repository so you can make changes, commit them to your own repository
 
     git clone https://github.com/{your-github}/node-red.github.io
 
-First time you run jeykll you need to do bundle install 1st for the dependencies, 
-    
+First time you run jeykll you need to do bundle install 1st for the dependencies,
+
     cd node-red.github.io
-    bundle install 
+    bundle install
     jekyll serve -w
 
-Once the site is built and running you can preview it at [`http://127.0.0.1:4000/`](http://127.0.0.1:4000/).
+Once the site is built and running you can preview it at [`http://127.0.0.1:4000/`](http://127.0.0.1:4000/).

_includes/toc-api-ui.html

@@ -2,11 +2,17 @@
     <li class="toc-expander">V</li>
     <li class="tocheader">
         <ul>
-            <li class="{% if page.url == "/docs/api/ui/" %} active{% endif %}"><a href="/docs/api/ui/">Editor Widgets</a>
-            <li {% if page.url contains "/docs/api/ui/editableList" %}class="active"{% endif %}><a href="/docs/api/ui/editableList">EditableList</a>
-            <li {% if page.url contains "/docs/api/ui/searchBox" %}class="active"{% endif %}><a href="/docs/api/ui/searchBox">SearchBox</a>
-            <li {% if page.url contains "/docs/api/ui/treeList" %}class="active"{% endif %}><a href="/docs/api/ui/treeList">TreeList</a>
-            <li {% if page.url contains "/docs/api/ui/typedInput" %}class="active"{% endif %}><a href="/docs/api/ui/typedInput">TypedInput</a>
+            <li class="{% if page.url == "/docs/api/ui/" %} active{% endif %}"><a href="/docs/api/ui/">Editor</a></li>
+            <li><a style="text-decoration: none !important; font-weight: bold">APIs</a></li>
+            <li {% if page.url contains "/docs/api/ui/actions" %}class="active"{% endif %}><a href="/docs/api/ui/actions">RED.actions</a></li>
+            <li {% if page.url contains "/docs/api/ui/events" %}class="active"{% endif %}><a href="/docs/api/ui/events">RED.events</a></li>
+            <li {% if page.url contains "/docs/api/ui/notifications" %}class="active"{% endif %}><a href="/docs/api/ui/notifications">RED.notify</a></li>
+            <li {% if page.url contains "/docs/api/ui/sidebar" %}class="active"{% endif %}><a href="/docs/api/ui/sidebar">RED.sidebar</a></li>
+            <li><a style="text-decoration: none !important; font-weight: bold">Widgets</a></li>
+            <li {% if page.url contains "/docs/api/ui/editableList" %}class="active"{% endif %}><a href="/docs/api/ui/editableList">EditableList</a></li>
+            <li {% if page.url contains "/docs/api/ui/searchBox" %}class="active"{% endif %}><a href="/docs/api/ui/searchBox">SearchBox</a></li>
+            <li {% if page.url contains "/docs/api/ui/treeList" %}class="active"{% endif %}><a href="/docs/api/ui/treeList">TreeList</a></li>
+            <li {% if page.url contains "/docs/api/ui/typedInput" %}class="active"{% endif %}><a href="/docs/api/ui/typedInput">TypedInput</a></li>
         </ul>
     </li>
 </ul>

css/editor-style.min.css

@@ -20,8 +20,9 @@ data.
 
 #### [Context Store API](context)
 
-**New in 0.19** : This API provides a pluggable way to store context data outside of the runtime.
+This API provides a pluggable way to store context data outside of the runtime.
 
-#### [Editor UI Widgets](ui)
+#### [Editor APIs](ui)
 
-A set of jQuery widgets that can be used within a node's edit template. _Since 0.14_
+The APIs available in the editor for nodes and plugins to use. This includes a set
+set of standard UI widgets that can be used within a node's edit template.

docs/api/index.md

@@ -0,0 +1,53 @@
+---
+layout: docs-api
+toc: toc-api-ui.html
+title: RED.events
+slug:
+  - url: "/docs/api/ui"
+    label: "ui"
+  - 'actions'
+---
+
+
+This API can be used to register and invoke Actions in the editor. Actions are
+individual pieces of functionality that a user may want to trigger and can be
+bound to keyboard shortcuts.
+
+ - [`RED.actions` API](#redactions-api)
+     - [`RED.actions.add( name, handler )`](#methods-add)
+     - [`RED.actions.remove( name )`](#methods-remove)
+     - [`RED.actions.invoke( name, [args...] )`](#methods-invoke)
+
+
+### `RED.actions` API
+
+#### <a href="#methods-add" name="methods-add">RED.actions.add( name, handler )</a>
+
+Register a new action.
+
+The name should follow the pattern `[provider]:[name-of-action]`. For example `core:show-debug-tab`.
+
+```javascript
+RED.actions.add("my-custom-tab:show-custom-tab",function() {
+    RED.sidebar.show("my-custom-tab");
+});
+```
+
+#### <a href="#methods-remove" name="methods-remove">RED.actions.remove( name )</a>
+
+Remove a previously registered action.
+
+```javascript
+RED.actions.remove("my-custom-tab:show-custom-tab")
+```
+
+#### <a href="#methods-invoke" name="methods-invoke">RED.actions.invoke( name, [args...])</a>
+
+Invoke an action by name.
+
+When bound to a keyboard shortcut, the handler will be invoked without any arguments. But when
+invoked using this API, it is possible to pass in arguments.
+
+```javascript
+RED.actions.invoke("my-custom-tab:show-custom-tab")
+```

docs/api/ui/actions/index.md

@@ -4,7 +4,7 @@ toc: toc-api-ui.html
 title: EditableList Widget
 slug:
   - url: "/docs/api/ui"
-    label: "ui widgets"
+    label: "ui"
   - 'editablelist'
 ---
 
@@ -121,7 +121,7 @@ $("ol.list").editableList({
         label: "with icon",
         icon: "fa fa-star",
         title: "my custom button",
-        click: function(evt) { 
+        click: function(evt) {
             alert("button clicked");
         }
    }]

docs/api/ui/editableList/index.md

@@ -0,0 +1,91 @@
+---
+layout: docs-api
+toc: toc-api-ui.html
+title: RED.events
+slug:
+  - url: "/docs/api/ui"
+    label: "ui"
+  - 'events'
+---
+
+
+The editor emits events that components can listen for so they can react as needed.
+
+*Note: any events not on this list should be considered private, subject to change without notification and not for general use.*
+
+ - [`RED.events` API](#redevents-api)
+     - [`RED.events.on( eventName, handlerFunction )`](#methods-on)
+     - [`RED.events.off( eventName, handlerFunction )`](#methods-off)
+ - [Available events](#available-events)
+     - [Workspace events](#workspace-events)
+     - [Flow configuration events](#flow-configuration-events)
+     - [Palette events](#palette-events)
+
+
+### `RED.events` API
+
+#### <a href="#methods-on" name="methods-on">RED.events.on( eventName, handlerFunction )</a>
+
+Register a new handler for the given event.
+
+
+```javascript
+RED.events.on("nodes:add", function(node) {
+    console.log("A node has been added to the workspace!")
+})
+```
+
+#### <a href="#methods-off" name="methods-off">RED.events.off(eventName, handlerFunction)</a>
+
+Remove a previously registered event handler.
+
+### Available events
+
+#### Workspace events
+
+Event | Payload | Description
+------|---------|-----
+`deploy` | | A new flow has been deployed
+`login` | `"username"` | A user has logged into the editor. If `adminAuth` is not configured, this event is never emitted
+`view:selection-changed` | `{<selection object>}` | The current selection in the workspace has changed
+`workspace:change`| `{ old: "<previous-workspace-id>", workspace: "<new-workspace-id>" }`|The workspace has switched to a different tab
+`workspace:clear` | | The workspace has been cleared - this happens when switching projects.
+`workspace:dirty` | `{ dirty:<boolean> }` | The dirty state of the editor has changed. 'Dirty' means there are undeployed changes.
+`workspace:hide` | `{ workspace: <workspace-id> }` | A tab has been hidden
+`workspace:show` | `{ workspace: <workspace-id> }` | A previously hidden tab has been shown
+
+#### Flow configuration events
+
+Event | Payload | Description
+------|---------|-----
+`flows:add` | `{<flow object>}` | A new flow has been added
+`flows:change` | `{<flow object>}` | A flow's properties have been changed
+`flows:remove` | `{<flow object>}` | A flow has been removed
+`flows:reorder`| `[<Array of flow ids]` | The flows have been reordered
+`groups:add` | `{<group object>}` | A new group has been added
+`groups:change` | `{<group object>}` | A group's properties have been changed
+`groups:remove` | `{<group object>}` | A group has been removed
+`links:add` | `{<link object>}` | A new link has been added
+`links:remove` | `{<link object>}` | A link has been removed
+`nodes:add` | `{<node object>}` | A new node has been added
+`nodes:change` | `{<node object>}` | A node's properties have been changed
+`nodes:remove` | `{<node object>}` | A node has been removed
+`nodes:reorder`| `{z:"<flow-id>", nodes:[<Array of node ids>]}`| Nodes have been reordered on a flow
+`subflows:add` | `{<subflow object>}` | A new subflow has been added
+`subflows:change` | `{<subflow object>}` | A subflow's properties have been changed
+`subflows:remove` | `{<subflow object>}` | A subflow has been removed
+
+
+
+#### Palette events
+
+Event | Payload | Description
+------|---------|-----
+`registry:module-updated`|`{module:"<module-name>", version:"<module-version>"}`|A module has updated to a new version
+`registry:node-set-added`|`{<node-set object>}`| A new Node-Set has been added to the palette
+`registry:node-set-disabled`|`{<node-set object>}`|A Node-Set has been disabled
+`registry:node-set-enabled`|`{<node-set object>}`| A Node-Set has been enabled
+`registry:node-set-removed`|`{<node-set object>}`| A Node-Set has been removed
+`registry:node-type-added`|`"node-type"`| A new Node has been added to the palette
+`registry:node-type-removed`|`"node-type"`| A Node has been removed from the palette
+`registry:plugin-added`|`"plugin-id"`| A Plugin has been added

docs/api/ui/events/index.md

@@ -1,10 +1,19 @@
 ---
 layout: docs-api
 toc: toc-api-ui.html
-title: Editor UI Widgets
-slug: "ui widgets"
+title: Editor APIs
+slug: "ui"
 ---
 
+The editor provides a number of APIs for nodes and plugins to use to help them integrate with the editor.
+
+ - [`RED.actions`](actions) - register custom actions
+ - [`RED.events`](events) - listen for events within the editor
+ - [`RED.notify`](notification) - show notifications in the editor
+ - [`RED.sidebar`](sidebar) - add sidebar tabs
+
+### Widgets
+
 A set of jQuery widgets are available that can be used within a node's edit template.
 
   - [`TypedInput`](typedInput) - a replacement for a regular `<input>` that allows

docs/api/ui/index.md

@@ -0,0 +1,119 @@
+---
+layout: docs-api
+toc: toc-api-ui.html
+title: RED.notify
+slug:
+  - url: "/docs/api/ui"
+    label: "ui"
+  - 'notifications'
+---
+
+
+This API can be used to display notifications that pop-down from the top of the editor.
+
+As these notifications interrupt the user, they should be used sparingly.
+
+ - [`RED.notify`](#rednotifymessage-options)
+     - [Configuration options](#configuration-options)
+     - [Notification buttons](#notification-buttons)
+     - [Notification object](#notification-object)
+ - [Examples](#examples)
+     - [Plain information notification](#plain-information-notification)
+     - [Warning notification for 10 seconds](#warning-notification-for-10-seconds)
+     - [Notification with buttons](#notification-with-buttons)
+
+
+### `RED.notify(message, [options])`
+
+ - `message` - the text to be displayed in the notification
+ - `options` - configuration options for the notification
+
+The function returns a `notification` object that can be used to interact with
+the notification.
+
+#### Configuration options
+
+The following properties can be provided in the `options` argument. All are optional.
+
+Option | Description
+-------|--------------
+`type` | Sets the appearance of the notification. Available values are: `compact`, `success`, `warning`, `error`. If this value is not set, the notification uses the default 'info' appearance.
+`timeout` | How long the notification should be shown for, in milliseconds. Default: `5000`. This is ignored if the `fixed` property is set.
+`fixed` | Do not hide the notification after a timeout. This also prevents the click-to-close default behaviour of the notification.
+`modal` | If set to `true`, the notification should prevent interaction with any other UI element until the notification has been dismissed.
+`buttons` | An array of buttons to display on the notification to allow user interaction.
+
+#### Notification buttons
+
+The `buttons` option can be used to provide a set of buttons that should be displayed on the notification.
+
+For example, to have a 'cancel' and 'okay' button, the following can be used (see further below for a fuller example that explains `myNotification.close()`).
+
+```javascript
+buttons: [
+    {
+        text: "cancel",
+        click: function(e) {
+            myNotification.close();
+        }
+    },
+    {
+        text: "okay",
+        class:"primary",
+        click: function(e) {
+            myNotification.close();
+        }
+    }
+```
+
+The `class` property can be used to specify an additional CSS class for the button. If the notification has multiple buttons, there should be one with the class set to `primary` to indicate the primary button for the user to click.
+
+#### Notification object
+
+The `RED.notify()` call returns a `notification` object. This object provides the following functions:
+
+Function | Description
+---------|---------
+`notification.close()` | Close the notification and dispose of it.
+`notification.update( message, options )` | Replace the contents of the notification.
+
+### Examples
+
+#### Plain information notification
+
+```javascript
+RED.notify("Hello World");
+```
+
+#### Warning notification for 10 seconds
+
+```javascript
+RED.notify("Something has happened", { type: "warning", timeout: 10000 });
+```
+
+#### Notification with buttons
+
+This example shows how the returned `myNotification` object is then used in the button event handlers to close the notification.
+
+```javascript
+let myNotification = RED.notify("This is the message to display",{
+    modal: true,
+    fixed: true,
+    type: 'warning',
+    buttons: [
+        {
+            text: "cancel",
+            click: function(e) {
+                myNotification.close();
+            }
+        },
+        {
+            text: "okay",
+            class:"primary",
+            click: function(e) {
+                myNotification.close();
+            }
+        }
+    ]
+});
+```

docs/api/ui/notifications/index.md

@@ -4,7 +4,7 @@ toc: toc-api-ui.html
 title: SearchBox Widget
 slug:
   - url: "/docs/api/ui"
-    label: "ui widgets"
+    label: "ui"
   - 'searchbox'
 ---