Add help info for split node

nodes/core/logic/17-split.html

@@ -35,9 +35,9 @@
     <div class="form-row"><span data-i18n="[html]split.object"></span></div>
     <div class="form-row" style="padding-left: 10px"><span data-i18n="[html]split.objectSend"></span></div>
     <div class="form-row">
-        <input type="checkbox" id="node-input-addname" style="margin-left:10px; vertical-align:baseline; width:auto;">
+        <input type="checkbox" id="node-input-addname-cb" style="margin-left:10px; vertical-align:baseline; width:auto;">
-        <label for="node-input-addname" style="width:auto;" data-i18n="split.addname"></label>
+        <label for="node-input-addname-cb" style="width:auto;" data-i18n="split.addname"></label>
-        <input type="text" id="node-input-addfname" style="width:70%">
+        <input type="text" id="node-input-addname" style="width:70%">
     </div>
     <hr/>
     <div class="form-row">
@@ -47,25 +47,54 @@
 </script>
 
 <script type="text/x-red" data-help-name="split">
-    <p>A function that splits <code>msg.payload</code> into multiple messages.</p>
+    <p>Splits a message into a sequence of messages.</p>
-    <p>The behaviour is determined by the type of <code>msg.payload</code>:</p>
+
+    <h3>Inputs</h3>
+    <dl class="message-properties">
+        <dt>payload<span class="property-type">object | string | array | buffer</span></dt>
+        <dd>The behaviour of the node is determined by the type of <code>msg.payload</code>:
             <ul>
-        <li><b>string</b> - a message is sent for each part of the string after it is split using the specified character, by default a newline (<code>\n</code>).
+                <li><b>string</b>/<b>buffer</b> - the message is split using the specified character (default: <code>\n</code>), buffer sequence or into fixed lengths.
-        <li><b>array</b> - a message is sent for each element of the array</li>
+                <li><b>array</b> - the message is split into either individual array elements, or arrays of a fixed-length.</li>
-        <li><b>object</b> - a message is sent for each key/value pair of the object. <code>msg.parts.key</code> is set to the key of the property.</li>
+                <li><b>object</b> - a message is sent for each key/value pair of the object.</li>
             </ul>
-    <p>Each message is sent with the <code>msg.parts</code> property set. This is
+        </dd>
-    an object that provides any subsequent <i>join</i> node the necessary information
+    </dl>
-    for it to reassemble the messages back into a single one. The object has the following
+    <h3>Outputs</h3>
-    properties:</p>
+    <dl class="message-properties">
+        <dt>parts<span class="property-type">object</span></dt>
+        <dd>This property contains information about how the message was split from
+        the original message. If passed to the <b>join</b> node, the sequence can be
+        reassembled into a single message. The property has the following properties:
         <ul>
-        <li><b>id</b> - an identifier for the group of messages</li>
+            <li><code>id</code> - an identifier for the group of messages</li>
-        <li><b>index</b> - the position within the group</li>
+            <li><code>index</code> - the position within the group</li>
-        <li><b>count</b> - the total number of messages in the group</li>
+            <li><code>count</code> - if known, the total number of messages in the group. See 'streaming mode' below.</li>
-        <li><b>type</b> - the type of message - string/array/object</li>
+            <li><code>type</code> - the type of message - string/array/object/buffer</li>
-        <li><b>ch</b> - for a string, the character used to split</li>
+            <li><code>ch</code> - for a string or buffer, the data used to the split the message as either the string or an array of bytes</li>
-        <li><b>key</b> - for an object, the key of the property this message was created from</li>
+            <li><code>key</code> - for an object, the key of the property this message was created from. The node can be configured to also copy this value to another message properties, such as <code>msg.topic</code>.</li>
+            <li><code>len</code> - the length of each message when split using a fixed length value</li>
         </ul>
+        </dd>
+    </dl>
+    <h3>Details</h3>
+    <p>This node makes it easy to create a flow that performs common actions across
+    a sequence of messages before, using the <b>join</b> node, recombining the
+    sequence into a single message.</p>
+    <p>It uses the <code>msg.parts</code> property to track the individual parts
+    of a sequence.</p>
+    <h4>Streaming mode</h4>
+    <p>The node can also be used to reflow a stream of messages. For example, a
+    serial device that sends newline-terminated commands may deliver a single message
+    with a partial command at its end. In 'streaming mode', this node will split
+    a message and send each complete segment. If there is a partial segment at the end,
+    the node will hold on to it and prepend it to the next message that is received.
+    </p>
+    <p>When operating in this mode, the node will not set the `msg.parts.count`
+    property as it does not know how many messages to expect in the stream. This
+    means it cannot be used with the <b>join</b> node in its automatic mode</p>
+
+
 </script>
 
 <script type="text/javascript">
@@ -79,8 +108,7 @@
             arraySplt: {value:1},
             arraySpltType: {value:"len"},
             stream: {value:false},
-            addname: {value:false},
+            addname: {value:""},
-            addfname: {value:"topic"}
         },
         inputs:1,
         outputs:1,
@@ -111,10 +139,26 @@
                     {value:"len", label:RED._("node-red:split.splitLength"),validate:/^\d+$/}
                 ]
             });
-            $("#node-input-addfname").typedInput({
+            $("#node-input-addname").typedInput({
                 typeField: $("#node-input-fnameType"),
                 types:['msg']
             });
+
+            $("#node-input-addname-cb").change(function() {
+                $("#node-input-addname").prop('disabled',!this.checked);
+            })
+            if (this.addname === "") {
+                $("#node-input-addname-cb").prop('checked',false);
+                $("#node-input-addname").val('topic');
+            } else {
+                $("#node-input-addname-cb").prop('checked',true);
+            }
+            $("#node-input-addname-cb").change();
+        },
+        oneditsave: function() {
+            if (!$("#node-input-addname-cb").prop('checked')) {
+                $("#node-input-addname").val('');
+            }
         }
     });
 </script>
@@ -192,11 +236,10 @@
             <li><code>id</code> - an identifier for the group of messages</li>
             <li><code>index</code> - the position within the group</li>
             <li><code>count</code> - the total number of messages in the group</li>
-            <li><code>type</code> - the type of message - string/array/object</li>
+            <li><code>type</code> - the type of message - string/array/object/buffer</li>
-            <li><code>ch</code> - for a string, the character used to split</li>
+            <li><code>ch</code> - for a string or buffer, the data used to the split the message as either the string or an array of bytes</li>
             <li><code>key</code> - for an object, the key of the property this message was created from</li>
-            <li><code>len</code> - for an array, the length of each array section</li>
+            <li><code>len</code> - the length of each message when split using a fixed length value</li>
-
         </ul>
         </dd>
         <dt class="optional">complete</dt>

nodes/core/logic/17-split.js

@@ -39,8 +39,7 @@ module.exports = function(RED) {
         var node = this;
         node.stream = n.stream;
         node.spltType = n.spltType || "str";
-        node.addname = n.addname || false;
+        node.addname = n.addname || "";
-        node.addfname = n.addfname;
         try {
             if (node.spltType === "str") {
                 this.splt = (n.splt || "\\n").replace(/\\n/,"\n").replace(/\\r/,"\r").replace(/\\t/,"\t").replace(/\\e/,"\e").replace(/\\f/,"\f").replace(/\\0/,"\0");
@@ -78,6 +77,7 @@ module.exports = function(RED) {
                     msg.parts.type = "string";
                     if (node.spltType === "len") {
                         msg.parts.ch = "";
+                        msg.parts.len = node.splt;
                         var count = msg.payload.length/node.splt;
                         if (Math.floor(count) !== count) {
                             count = Math.ceil(count);
@@ -145,7 +145,9 @@ module.exports = function(RED) {
                     for (var p in pay) {
                         if (pay.hasOwnProperty(p)) {
                             msg.payload = pay[p];
-                            if (node.addname === true) { msg[node.addfname] = p; }
+                            if (node.addname !== "") {
+                                msg[node.addname] = p;
+                            }
                             msg.parts.key = p;
                             msg.parts.index = j;
                             msg.parts.count = l;

test/nodes/core/logic/17-split_spec.js

@@ -101,7 +101,7 @@ describe('SPLIT node', function() {
     });
 
     it('should split an object into pieces and overwrite their topics', function(done) {
-        var flow = [{id:"sn1", type:"split", addname:true, addfname:"topic", wires:[["sn2"]]},
+        var flow = [{id:"sn1", type:"split", addname:"topic", wires:[["sn2"]]},
                     {id:"sn2", type:"helper"}];
         helper.load(splitNode, flow, function() {
             var sn1 = helper.getNode("sn1");