Update node appearance - add button docs

Author: knolleary

_posts/2019-08-16-going-async.md

@@ -2,7 +2,7 @@
 layout: blog
 title: Making flows asynchronous by default
 author: nick
-description: Changes are coming in Node-RED 1.0 to how messages are routed in a flow. Find out what its means to go asynchronous.
+description: Changes are coming in Node-RED 1.0 to how messages are routed in a flow. Find out what it means to go asynchronous.
 ---
 
 In Node-RED 1.0, we are changing the way messages pass between nodes from being
@@ -92,7 +92,7 @@ When a flow branches, the branches will be evaluated in 'parallel'.
 ![](/blog/content/images/2019/08/flow2-async.svg)
 
 Which also means a flow with Debug nodes at each point, will log the message
-is the expected order.
+in the expected order.
 
 ![](/blog/content/images/2019/08/flow4-async.svg)
 

docs/creating-nodes/appearance.md

@@ -16,16 +16,26 @@ The value of the property can be either a string or a function.
 
 If the value is a string, that is used as the icon.
 
-If the value is a function, it will get evaluated when the node is first loaded, or after it has been edited. The function is expected to return the value to use as the icon.
-The function will be called both for nodes in the workspace, where `this` references a node instance, as well as
-for the node's entry in the palette. In this latter case, `this` will not refer to a particular node instance and
-the function *must* return a valid value.
+If the value is a function, it will get evaluated when the node is first loaded,
+or after it has been edited. The function is expected to return the value to use
+as the icon.
+
+The function will be called both for nodes in the workspace, where `this` references
+a node instance, as well as for the node's entry in the palette. In this latter case,
+ `this` will not refer to a particular node instance and the function *must* return
+ a valid value.
+
+{% highlight javascript %}
+...
+icon: "file.png",
+...
+{% endhighlight %}
 
-                ...
-                icon: "file.png",
-                ...
+The icon can be either:
 
-There are some stock icons available for use, or the node can provide its own.
+ - the name of a stock icon provided by Node-RED,
+ - the name of a custom icon provided by the module,
+ - a Font Awesome 4.7 icon
 
 #### Stock icons
 
@@ -48,24 +58,28 @@ There are some stock icons available for use, or the node can provide its own.
 </style>
 
 <ul class="nr-icon-list">
-<li><img src="images/alert.png"/> alert.png</li>
-<li><img src="images/arrow-in.png"/> arrow-in.png</li>
-<li><img src="images/bridge-dash.png"/> bridge-dash.png</li>
-<li><img src="images/bridge.png"/> bridge.png</li>
-<li><img src="images/db.png"/> db.png</li>
-<li><img src="images/debug.png"/> debug.png</li>
-<li><img src="images/envelope.png"/> envelope.png</li>
-<li><img src="images/feed.png"/> feed.png</li>
-<li><img src="images/file.png"/> file.png</li>
-<li><img src="images/function.png"/> function.png</li>
-<li><img src="images/hash.png"/> hash.png</li>
-<li><img src="images/inject.png"/> inject.png</li>
-<li><img src="images/light.png"/> light.png</li>
-<li><img src="images/serial.png"/> serial.png</li>
-<li><img src="images/template.png"/> template.png</li>
-<li><img src="images/white-globe.png"/> white-globe.png</li>
+<li><img src="images/alert.svg"/> alert.png</li>
+<li><img src="images/arrow-in.svg"/> arrow-in.png</li>
+<li><img src="images/bridge-dash.svg"/> bridge-dash.png</li>
+<li><img src="images/bridge.svg"/> bridge.png</li>
+<li><img src="images/db.svg"/> db.png</li>
+<li><img src="images/debug.svg"/> debug.png</li>
+<li><img src="images/envelope.svg"/> envelope.png</li>
+<li><img src="images/feed.svg"/> feed.png</li>
+<li><img src="images/file.svg"/> file.png</li>
+<li><img src="images/function.svg"/> function.png</li>
+<li><img src="images/hash.svg"/> hash.png</li>
+<li><img src="images/inject.svg"/> inject.png</li>
+<li><img src="images/light.svg"/> light.png</li>
+<li><img src="images/serial.svg"/> serial.png</li>
+<li><img src="images/template.svg"/> template.png</li>
+<li><img src="images/white-globe.svg"/> white-globe.png</li>
 </ul>
 
+**Note**: In Node-RED 1.0, all of these icons have been replaced with SVG alternatives
+for a better appearance. For ensure backwards compatibility, the editor will automatically
+swap any request for the png version for the SVG version if it is available.
+
 #### Custom icon
 
 A node can provide its own icon in a directory called `icons` alongside its `.js`
@@ -74,17 +88,25 @@ looks for a given icon filename. Because of this, the icon filename must be uniq
 
 The icon should be white on a transparent background, 40 x 60 in size.
 
-#### User defined icon
+#### Font Awesome icon
 
-From Node-RED version 0.18 the node's icon can be overwritten by the user using the `node settings` section of the configuration editor.
+Node-RED includes the full set of [Font Awesome 4.7 icons](https://fontawesome.com/v4.7.0/icons/).
 
-<div style="text-align:center">
-    <img title="port label editor" src="images/user-defined-icon.png"/>
-</div>
+To specify a FA icon, the property should take the form:
+
+{% highlight javascript %}
+...
+icon: "font-awesome/fa-automobile",
+...
+{% endhighlight %}
+
+#### User defined icon
 
-The name of installed modules that contain one or more icon files or `node-red` for core nodes are shown on the left. The name of icon files in the module are shown on the right.
+Individual node icons can be customised by the user within the editor on the 'appearance'
+tab of the node's edit dialog.
 
-**Note**: If a node has `icon` property by default, the node's icon cannot be overwritten (e.g. ui_button node of node-red-dashboard).
+**Note**: If a node has an `icon` property in its `defaults` object, its icon
+cannot be customised. For example, the `ui_button` node of `node-red-dashboard`.
 
 ### Background Colour
 
@@ -227,27 +249,31 @@ align: 'right',
 
 #### Port labels
 
-From Node-RED version **0.17** onwards nodes can optionally provide labels on their input
-and output ports, that can be seen by hovering the mouse over the port.
+Nodes can provide labels on their input and output ports that can be seen by
+hovering the mouse over the port.
 
 <div style="text-align:center">
     <img title="port labels" src="images/node-labels.png"/>
 </div>
 
 These can either be set statically by the node's html file
 
-    ...,
-    inputLabels: "parameter for input",
-    outputLabels: ["stdout","stderr","rc"],
-    ...
+{% highlight javascript %}
+...
+inputLabels: "parameter for input",
+outputLabels: ["stdout","stderr","rc"],
+...
+{% endhighlight %}
 
 or generated by a function, that is passed an index to indicate the output pin (starting from 0).
 
-    ...,
-    outputLabels: function(index) {
-        return "my port number "+index;
-    }
-    ...
+{% highlight javascript %}
+...
+outputLabels: function(index) {
+    return "my port number "+index;
+}
+...
+{% endhighlight %}
 
 
 In both cases they can be overwritten by the user using the `node settings` section of the configuration editor.
@@ -261,3 +287,68 @@ In both cases they can be overwritten by the user using the `node settings` sect
 </div>
 
 **Note**: Labels are not generated dynamically, and cannot be set by `msg` properties.
+
+### Buttons
+
+A node can have a button on its left or right hand edge, as seen with the core
+Inject and Debug nodes.
+
+A key principle is the editor is not a dashboard for controlling your flows. So
+in general, nodes should not have buttons on them. The Inject and Debug nodes are
+special cases as the buttons play a role in the development of flows.
+
+The `button` property in its definition is used to describe the behaviour of the
+button. It must provide, as a minimum, an `onclick` function that will be called
+when the button is clicked.
+
+{% highlight javascript %}
+...
+button: {
+    onclick: function() {
+        // Called when the button is clicked
+    }
+},
+...
+{% endhighlight %}
+
+The property can also define an `enabled` function to dynamically enable and
+disable the button based on the node's current configuration. Similarly, it can
+define a `visible` function to determine whether the button should be shown at all.
+
+{% highlight javascript %}
+...
+button: {
+    enabled: function() {
+        // return whether or not the button is enabled, based on the current
+        // configuration of the node
+        return !this.changed
+    },
+    visible: function() {
+        // return whether or not the button is visible, based on the current
+        // configuration of the node
+        return this.hasButton
+    },
+    onclick: function() { }
+},
+...
+{% endhighlight %}
+
+The `button` can also be configured as a toggle button - as seen with the Debug
+node. This is done by added a property called `toggle` that identifies a property
+in the node's `defaults` object that should be used to store a boolean value whose
+value is toggled whenever the button is pressed.
+
+
+{% highlight javascript %}
+...
+defaults: {
+    ...
+    buttonState: {value: true}
+    ...
+},
+button: {
+    toggle: "buttonState",
+    onclick: function() { }
+}
+...
+{% endhighlight %}

docs/creating-nodes/first-node.md

@@ -8,9 +8,9 @@ slug: first node
 Nodes get created when a flow is deployed, they may send and receive some messages
 whilst the flow is running and they get deleted when the next flow is deployed.
 
-They typically consist of a pair of files; a JavaScript file that defines what the
-node does, and an html file that defines the node's properties, edit dialog and
-help text.
+They consist of a pair of files:
+ -  a JavaScript file that defines what the node does,
+ -  an html file that defines the node's properties, edit dialog and help text.
 
 A `package.json` file is used to package it all together as an npm module.
 
@@ -25,7 +25,8 @@ A `package.json` file is used to package it all together as an npm module.
 This example will show how to create a node that converts message payloads to
 all lower-case characters.
 
-Ensure you have the recommended LTS version of Node.js installed on your system.  As of this writing this is version **LTS 8.x** which includes npm version 5.x.
+Ensure you have the current LTS version of Node.js installed on your system. At
+the time of writing this is 10.x.
 
 Create a directory where you will develop your code. Within that directory, create the following files:
 
@@ -152,44 +153,41 @@ For more information about the editor part of the node, see [here](node-html).
 
 Once you have created a basic node module as described above, you can install it into your Node-RED runtime.
 
-To test a node module locally using npm 5.x, the [`npm install <folder>`](https://docs.npmjs.com/cli/install) command can be used. This allows you
-to develop the node in a local directory and have it linked into a local node-red install during development.
+To test a node module locally the [`npm install <folder>`](https://docs.npmjs.com/cli/install)
+command can be used. This allows you to develop the node in a local directory and
+have it linked into a local node-red install during development.
 
 In your node-red user directory, typically `~/.node-red`, run:
 
     npm install <location of node module>
 
-For example, on Mac OS or linux, if your node is located at `~/dev/node-red-contrib-example-lower-case` you would type the following:
+For example, on Mac OS or Linux, if your node is located at `~/dev/node-red-contrib-example-lower-case` you would do the following:
 
     cd ~/.node-red
     npm install ~/dev/node-red-contrib-example-lower-case
 
-This creates a symbolic link to your node module project directory in  `~/.node-red/node_modules` so that Node-RED will discover the node when it starts. Any changes to the node's file can be picked up by simply restarting Node-RED.  On Windows, again, using npm 5.x or greater:
+On Windows you would do:
 
     cd C:\Users\my_name\.node_red
     npm install C:\Users\my_name\Documents\GitHub\node-red-contrib-example-lower-case
 
-If you are using an older version of npm, you can create a symbolic link manually to your project.  For example, on Mac or linux systems:
-
-    cd ~/.node-red/node_modules
-    ln -s ~/dev/node-red-contrib-example-lower-case  .
-
-On Windows with older versions of npm, use `mklink` instead:
-
-    cd C:\Users\my_name\.node_red
-    mklink /D node_modules\node-red-contrib-example-lower-case C:\Users\my_name\Documents\GitHub\node-red-contrib-example-lower-case
+This creates a symbolic link to your node module project directory in  `~/.node-red/node_modules` so that Node-RED will discover the node when it starts. Any changes to the node's file can be picked up by simply restarting Node-RED.  On Windows, again, using npm 5.x or greater:
 
 <div class="doc-callout">
-<em>Note</em> :  npm 5 will add your module as a dependency in the <code>package.json</code> file located in your user directory.  If you want to prevent this, use the npm <code>--no-save</code> option.
+<em>Note</em> :  <code>npm</code> will automatically add an entry for your module in the
+<code>package.json</code> file located in your user directory.  If you don't want
+it to do this, use the <code>--no-save</code> option to the <code>npm install</code>
+command.
 </div>
 
 ### Unit Testing
 
-To support unit testing, an npm module called [`node-red-node-test-helper`](https://www.npmjs.com/package/node-red-node-test-helper) can be used.  The test-helper is a framework built on the Node-RED runtime to make it easier to test nodes.
+To support unit testing, an npm module called [`node-red-node-test-helper`](https://www.npmjs.com/package/node-red-node-test-helper) can be used.  The test-helper is a framework
+built on the Node-RED runtime to make it easier to test nodes.
 
 Using this framework, you can create test flows, and then assert that your node properties and output is working as expected.  For example, to add a unit test to the lower-case node you can add a `test` folder to your node module package containing a file called `_spec.js`
 
-<h4><i class="fa fa-file-o"></i> test/_spec.js</h4>
+<h4 id="lower-casespecjs"><i class="fa fa-file-o"></i> test/lower-case_spec.js</h4>
 
 ```javascript
 var should = require("should");