From 7667de5ced55bec815ccb730a28eccb074deded8 Mon Sep 17 00:00:00 2001
From: Dave Conway-Jones <conway@uk.ibm.com>
Date: Fri, 3 Apr 2020 16:50:09 +0100
Subject: [PATCH] Tidy up ping notes for pub

---
 io/ping/88-ping.html               | 12 +++++---
 io/ping/locales/en-US/88-ping.html | 47 ++++++++++++++++--------------
 io/ping/locales/en-US/88-ping.json |  3 +-
 io/ping/package.json               |  7 +++--
 4 files changed, 40 insertions(+), 29 deletions(-)

diff --git a/io/ping/88-ping.html b/io/ping/88-ping.html
index 7826c500..b82abfda 100644
--- a/io/ping/88-ping.html
+++ b/io/ping/88-ping.html
@@ -19,6 +19,7 @@
         <label for="node-input-name"><i class="fa fa-tag"></i> <span data-i18n="node-red:common.label.name"></span></label>
         <input type="text" id="node-input-name" data-i18n="[placeholder]node-red:common.label.name">
     </div>
+    <div class="form-tips" id="node-ping-tip"><span data-i18n="ping.label.tip"></span></div>
 </script>
 
 <script type="text/javascript">
@@ -46,7 +47,7 @@ var timerParameterValidator = function(node,v){
         } else {
             let $mode = $( "#node-input-mode" );
             return $mode.val();
-        }        
+        }
     }
 
     RED.nodes.registerType("ping",{
@@ -61,7 +62,7 @@ var timerParameterValidator = function(node,v){
             },
             timer: {value:"20", validate: function(v){
                     return timerParameterValidator(this,v) ;
-                } 
+                }
             },
             inputs: {value:0}
         },
@@ -84,20 +85,23 @@ var timerParameterValidator = function(node,v){
         oneditprepare: function () {
             let node = this;
             let $timer = $("#div-node-input-timer");
+            let $tip = $("#node-ping-tip");
             $("#node-input-mode").val(node.mode);
             let $mode = $( "#node-input-mode" );
-            function updateControlsVisibility(){   
-                node.mode = $mode.val();          
+            function updateControlsVisibility(){
+                node.mode = $mode.val();
                 switch (node.mode) {
                     case "triggered":
                         node.inputs = 1;
                         node._def.inputs = 1
                         $timer.hide();
+                        $tip.show();
                         break;
                     default:
                         node.inputs = 0;
                         node._def.inputs = 0;
                         $timer.show();
+                        $tip.hide();
                         break;
                 }
             }
diff --git a/io/ping/locales/en-US/88-ping.html b/io/ping/locales/en-US/88-ping.html
index cd81ec09..2bcf660f 100644
--- a/io/ping/locales/en-US/88-ping.html
+++ b/io/ping/locales/en-US/88-ping.html
@@ -3,11 +3,13 @@
     <h3>Output</h3>
     <dl class="message-properties">
         <dt>payload <span class="property-type">number</span></dt>
-        <dd> the trip time in mS.</dd>
+        <dd> the trip time in mS, or boolean <i>false</i> if no response.</dd>
         <dt>topic <span class="property-type">string</span></dt>
-        <dd> the target host/ip</dd>
-        <dt>ping <span class="property-type">object</span></dt>
-        <dd> an object containing <code>host</code> and any other properties sent in the array object. <br>NOTE: This object is only appended when using triggered mode and an array for input payload. It is intended for adavanced users and permits scenarios where you need additional properties to be tagged into your result for use downstream.</dd>
+        <dd> the target host or ip address.</dd>
+        <dt>[ping] <span class="property-type">object</span></dt>
+        <dd> an object containing <code>host</code> and any other properties sent in the array object.<br>
+            <b>Note</b>: This object is only appended when using triggered mode and an array for input payload. It is
+            intended for advanced users and permits scenarios where you need additional properties to be tagged into your result for use downstream.</dd>
     </dl>
     <h3>Details</h3>
     <p>Returns <b>false</b> if no response received, or if the host is unresolveable.</p>
@@ -16,27 +18,31 @@
     <h4>Mode...</h4>
     <ul>
         <li><b>Timed</b><br>
-            <P>In <code>Timed</code> mode, the fields <code>Target</code> and <code>Ping (S)</code> must be populated.</P>
-            <p><code>Target</code> must be a CSV list of hosts / IPs e.g. <code>"192.168.0.1"</code> or <code>"192.168.0.1, www.google.com"</code></p>
-            <p><code>Ping (S)</code> is the number of seconds between pings</p>
+            <P>In Timed mode, the fields <code>Target</code> and <code>Ping (S)</code> must be populated.</P>
+            <p>Target must be a CSV list of hosts / IPs e.g. <code>"192.168.0.1"</code> or <code>"192.168.0.1, www.google.com"</code></p>
+            <p>Ping (S) is the number of seconds between pings</p>
         </li>
         <li><b>Triggered</b><br>
-            <p>In <code>Triggered</code> mode, you must connect an input wire and pass a <code>msg</code> in to trigger the ping operation.</p>
-            <p>If <code>Target</code> is populated, this will be used as the host/ip. The Target must be is a CSV list of hosts / IPs e.g. <code>"192.168.0.1"</code> or <code>"192.168.0.1, www.google.com"</code></p>
-            
-            <p>If <code>Target</code> is left empty, you can pass a CSV string or an array of hosts in `msg.payload`
+            <p>In Triggered mode, you must connect an input wire and pass a <code>msg</code> in to trigger the ping operation.</p>
+            <p>If <code>Target</code> is populated, this will be used as the host/ip. The Target must be is a CSV list of
+                hosts / IPs e.g. <code>"192.168.0.1"</code> or <code>"192.168.0.1, www.google.com"</code></p>
+
+            <p>If Target is left empty, you can pass a CSV string or an array of hosts in <code>msg.payload</code>.
                 <ul>
-                    <li><code>string</code> - a CSV list of hosts / IPs e.g. <code>"192.168.0.1"</code> or <code>"192.168.0.1, www.google.com"</code> </li>
-                    <li><code>array</code> - an array of hosts as string or object. NOTE: The object must contain at minimum <code>.host</code>. Optionally, you can add a <code>timeout</code> property between 1000 & 30000 (default is 5000 / 5 seconds).  Additionally, you can add whatever other properties you wish to this object and when the ping result is returned, it will be passed to the next node in <code>msg.ping</code> for use downstream</li>
+                    <li><b>string</b> - a CSV list of hosts / IPs e.g. <code>"192.168.0.1"</code> or <code>"192.168.0.1, www.google.com"</code> </li>
+                    <li><b>array</b> - an array of hosts as strings or objects. <b>Note</b>: The object must contain at minimum <code>.host</code>.
+                        Optionally, you can add a <code>timeout</code> property between 1000 & 30000 (default is 5000 / 5 seconds).
+                        Additionally, you can add whatever other properties you wish to this object and when the ping result is returned, it will
+                        be passed to the next node in <code>msg.ping</code> for use downstream</li>
                     <li>Example array payload input: <pre>[
     "192.168.0.99",
     {
-        "host":"192.168.0.1", 
+        "host":"192.168.0.1",
         "name":"The router"
-    },  
+    },
     {
-        "host":"myapiserver.com", 
-        "name":"external API", 
+        "host":"myapiserver.com",
+        "name":"external API",
         "timeout": 20000,
         "support":"support@myapiserver.com"
     }
@@ -45,9 +51,6 @@
             </p>
         </li>
     </ul>
-
-
-
-    <p>Note: if running inside Ubuntu Snap you will need to manually start the network-observe interface.
-        `snap connect node-red:network-observe`</p>
+    <p><b>Note</b>: if running inside Ubuntu Snap you will need to manually start the network-observe interface.
+        <code>snap connect node-red:network-observe</code>.</p>
 </script>
diff --git a/io/ping/locales/en-US/88-ping.json b/io/ping/locales/en-US/88-ping.json
index f1a9093e..0bfc7373 100644
--- a/io/ping/locales/en-US/88-ping.json
+++ b/io/ping/locales/en-US/88-ping.json
@@ -8,7 +8,8 @@
             "mode_option": {
                 "timed": "Timed",
                 "triggered": "Triggered"
-            }            
+            },
+            "tip": "Note: Leave Target field blank to allow msg.payload to set hosts dynamically."
         }
     }
 }
diff --git a/io/ping/package.json b/io/ping/package.json
index 6ce6cffe..31edb417 100644
--- a/io/ping/package.json
+++ b/io/ping/package.json
@@ -1,6 +1,6 @@
 {
     "name"          : "node-red-node-ping",
-    "version"       : "0.1.0",
+    "version"       : "0.2.0",
     "description"   : "A Node-RED node to ping a remote server, for use as a keep-alive check.",
     "dependencies"  : {
     },
@@ -19,5 +19,8 @@
         "name": "Dave Conway-Jones",
         "email": "ceejay@vnet.ibm.com",
         "url": "http://nodered.org"
-    }
+    },
+    "contributors": [
+        { "name": "@Steve-Mcl" }
+    ]
 }