From 749b0d7019c43db0a374f5d7d73d053f13a7b2c8 Mon Sep 17 00:00:00 2001
From: Nick O'Leary <nick.oleary@gmail.com>
Date: Tue, 23 May 2017 14:18:09 +0100
Subject: [PATCH] Tidy up parser node edit dialogs and help text

---
 nodes/core/locales/en-US/messages.json | 20 ++++----
 nodes/core/parsers/70-CSV.html         | 65 ++++++++++++++++----------
 nodes/core/parsers/70-HTML.html        | 10 ++--
 nodes/core/parsers/70-JSON.html        | 28 +++++++----
 nodes/core/parsers/70-XML.html         | 53 ++++++++++++++-------
 nodes/core/parsers/70-YAML.html        | 21 ++++++---
 6 files changed, 123 insertions(+), 74 deletions(-)

diff --git a/nodes/core/locales/en-US/messages.json b/nodes/core/locales/en-US/messages.json
index ea9cd07ba..f5b9867e7 100644
--- a/nodes/core/locales/en-US/messages.json
+++ b/nodes/core/locales/en-US/messages.json
@@ -588,8 +588,8 @@
         "label": {
             "columns": "Columns",
             "separator": "Separator",
-            "c2o": "CSV-to-Object options",
-            "o2c": "Object-to-CSV options",
+            "c2o": "CSV to Object options",
+            "o2c": "Object to CSV options",
             "input": "Input",
             "firstrow": "first row contains column names",
             "output": "Output",
@@ -624,7 +624,7 @@
     },
     "html": {
         "label": {
-            "select": "Select",
+            "select": "Selector",
             "output": "Output"
         },
         "output": {
@@ -635,8 +635,7 @@
         "format": {
             "single": "as a single message containing an array",
             "multi": "as multiple messages, one for each element"
-        },
-        "tip": "Tip: The <b>Select</b> value is a <a href=\"https://github.com/fb55/CSSselect#user-content-supported-selectors\" target=\"_blank\"><i><u>CSS Selector</u></i></a>, similar to a jQuery selector."
+        }
     },
     "json": {
         "errors": {
@@ -645,8 +644,8 @@
             "dropped-error": "Failed to convert payload"
         },
         "label": {
-            "o2j": "Object-to-String options",
-            "pretty": "Pretty print JSON string"
+            "o2j": "Object to JSON options",
+            "pretty": "Format JSON string"
         }
     },
     "yaml": {
@@ -658,12 +657,11 @@
     },
     "xml": {
         "label": {
-            "represent": "Represent XML tag attributes as a property named",
-            "prefix": "Prefix to access character content",
+            "represent": "Property name for XML tag attributes",
+            "prefix": "Property name for tag text content",
             "advanced": "Advanced options",
-            "x2o": "XML-to-Object options"
+            "x2o": "XML to Object options"
         },
-        "tip": "There is no simple way to convert XML attributes to JSON so the approach taken here is to add a property, named $ by default, to the JSON structure.",
         "errors": {
             "xml_js": "This node only handles xml strings or js objects."
         }
diff --git a/nodes/core/parsers/70-CSV.html b/nodes/core/parsers/70-CSV.html
index 373b9c81d..c831a90e1 100644
--- a/nodes/core/parsers/70-CSV.html
+++ b/nodes/core/parsers/70-CSV.html
@@ -24,26 +24,30 @@
     </div>
     <hr align="middle"/>
     <div class="form-row">
-        <label style="width:100%;"><i class="fa fa-gears"></i> <span data-i18n="csv.label.c2o"></span></label>
-        <label style="margin-left:16px; margin-right:-16px;"><i class="fa fa-sign-in"></i> <span data-i18n="csv.label.input"></span></label>
-        <input style="width:30px" type="checkbox" id="node-input-hdrin"><label style="width: auto;" for="node-input-hdrin"><span data-i18n="csv.label.firstrow"></span>
+        <label style="width:100%; border-bottom: 1px solid #eee;"><span data-i18n="csv.label.c2o"></span></label>
     </div>
-    <div class="form-row">
-        <label style="margin-left:16px; margin-right:-16px;"><i class="fa fa-sign-out"></i> <span data-i18n="csv.label.output"></span></label>
+    <div class="form-row" style="padding-left: 20px;">
+        <label><i class="fa fa-sign-in"></i> <span data-i18n="csv.label.input"></span></label>
+        <input style="width:20px; vertical-align:top; margin-right: 5px;" type="checkbox" id="node-input-hdrin"><label style="width: auto;" for="node-input-hdrin"><span data-i18n="csv.label.firstrow"></span>
+    </div>
+    <div class="form-row" style="padding-left: 20px;">
+        <label><i class="fa fa-sign-out"></i> <span data-i18n="csv.label.output"></span></label>
         <select type="text" id="node-input-multi" style="width: 250px;">
             <option value="one" data-i18n="csv.output.row"></option>
             <option value="mult" data-i18n="csv.output.array"></option>
         </select>
     </div>
-    <hr align="middle"/>
-    <div class="form-row">
-        <label style="width:100%;"><i class="fa fa-gears"></i> <span data-i18n="csv.label.o2c"></span></label>
-        <label style="margin-left:16px; margin-right:-16px;"><i class="fa fa-sign-in"></i> <span data-i18n="csv.label.output"></span></label>
-        <input style="width:30px" type="checkbox" id="node-input-hdrout"><label style="width:auto;" for="node-input-hdrout"><span data-i18n="csv.label.includerow"></span></span>
+    <div class="form-row" style="margin-top: 20px">
+        <label style="width:100%; border-bottom: 1px solid #eee;"><span data-i18n="csv.label.o2c"></span></label>
     </div>
-    <div class="form-row">
-        <label style="margin-left:16px; margin-right:-16px;"><i class="fa fa-align-left"></i> <span data-i18n="csv.label.newline"></span></label>
-        <select style="width:150px" id="node-input-ret">
+    <div class="form-row" style="padding-left: 20px;">
+        <label><i class="fa fa-sign-in"></i> <span data-i18n="csv.label.output"></span></label>
+        <input style="width:20px; vertical-align:top; margin-right: 5px;" type="checkbox" id="node-input-hdrout"><label style="width:auto;" for="node-input-hdrout"><span data-i18n="csv.label.includerow"></span></span>
+    </div>
+    <div class="form-row" style="padding-left: 20px;">
+        <label></label>
+        <label style="width: auto; margin-right: 10px;" for="node-input-ret"><span data-i18n="csv.label.newline"></span></label>
+        <select style="width:150px;" id="node-input-ret">
             <option value='\n' data-i18n="csv.newline.linux"></option>
             <option value='\r' data-i18n="csv.newline.mac"></option>
             <option value='\r\n' data-i18n="csv.newline.windows"></option>
@@ -52,20 +56,31 @@
 </script>
 
 <script type="text/x-red" data-help-name="csv">
-    <p>A function that parses the <code>msg.payload</code> to convert CSV to or from a javascript object.
-    Places the result in the payload.</p>
+    <p>Converts between a CSV formatted string and its JavaScript object representation, in either direction.</p>
     <h3>Inputs</h3>
-    <ul>
-        <li>If the input is a string it tries to parse it as CSV and creates a javascript object.</li>
-        <li>If the input is a javascript object it tries to build a CSV string.</li>
-        <li>If the input is a simple array the output is just a CSV generated from that array.</li>
-        <li>If the input is an array of arrays, or an array of objects, a multiple-line CSV is created.</li>
-    </ul>
+    <dl class="message-properties">
+        <dt>payload<span class="property-type">object | array | string</span></dt>
+        <dd>A JavaScript object, array or CSV string.</dd>
+    </dl>
+    <h3>Outputs</h3>
+    <dl class="message-properties">
+        <dt>payload<span class="property-type">object | array | string</span></dt>
+        <dd>
+        <ul>
+            <li>If the input is a string it tries to parse it as CSV and creates a JavaScript object of key/value pairs for each line.
+                The node will then either send a message for each line, or a single message containing an array of objects.</li>
+            <li>If the input is a JavaScript object it tries to build a CSV string.</li>
+            <li>If the input is an array of simple values, it builds a single line CSV string.</li>
+            <li>If the input is an array of arrays, or an array of objects, a multiple-line CSV string is created.</li>
+        </ul>
+        </dd>
+    </dl>
     <h3>Details</h3>
-    <p>The columns template should contain an ordered list of column headers. For CSV input these become the property names.
-    For CSV output these specify the properties to extract from the object and the order for the CSV.</p>
-    <p>If the input is an array then the columns template does not matter, but can be used to generate a row of column titles.</p>
-    <p><b>Note:</b> the columns should always be specified comma separated - even if another separator is chosen for the data.</p>
+    <p>The column template can contain an ordered list of column names. When converting CSV to an object, the column names
+    will be used as the property names. Alternatively, the column names can be taken from the first row of the CSV.</p>
+    <p>When converting to CSV, the column template is used to identify which properties to extract from the object and in what order.</p>
+    <p>If the input is an array then the columns template is only used to optionally generate a row of column titles.</p>
+    <p><b>Note:</b> the column template must be comma separated - even if a different separator is chosen for the data.</p>
     </script>
 
 <script type="text/javascript">
diff --git a/nodes/core/parsers/70-HTML.html b/nodes/core/parsers/70-HTML.html
index c4bd2f6a1..bf67fe082 100644
--- a/nodes/core/parsers/70-HTML.html
+++ b/nodes/core/parsers/70-HTML.html
@@ -25,11 +25,10 @@
         <label for="node-input-name"><i class="fa fa-tag"></i> <span data-i18n="common.label.name"></span></label>
         <input type="text" id="node-input-name" style="width:70%" data-i18n="[placeholder]common.label.name">
     </div>
-    <div class="form-tips"><span data-i18n="[html]html.tip"></span></div>
 </script>
 
 <script type="text/x-red" data-help-name="html">
-    <p>Extracts elements from an html document held in <code>msg.payload</code> using a selector.</p>
+    <p>Extracts elements from an html document held in <code>msg.payload</code> using a CSS selector.</p>
     <h3>Inputs</h3>
     <dl class="message-properties">
     <dt>payload <span class="property-type">string</span></dt>
@@ -39,13 +38,14 @@
 </dl>
     <h3>Output</h3>
     <dl class="message-properties">
-        <dt>payload <span class="property-type">array | strings</span></dt>
+        <dt>payload <span class="property-type">array | string</span></dt>
         <dd>the result can be either a single message with a payload containing an array of the matched elements, or multiple
            messages that each contain a matched element.</dd>
     </dl>
     <h3>Details</h3>
-    <p>The selector uses <a href="https://github.com/cheeriojs/cheerio/blob/master/Readme.md" target="_blank">Cheerio</a>
-     which uses the <a href="https://github.com/fb55/CSSselect#user-content-supported-selectors" target="_blank">CSS selector</a> syntax.</p>
+    <p>This node supports a combination of CSS and jQuery selectors. See the
+    <a href="https://github.com/fb55/CSSselect#user-content-supported-selectors" target="_blank">css-select documentation</a> for more information
+    on the supported syntax.</p>
 </script>
 
 <script type="text/javascript">
diff --git a/nodes/core/parsers/70-JSON.html b/nodes/core/parsers/70-JSON.html
index 280ab21b7..93f54769f 100644
--- a/nodes/core/parsers/70-JSON.html
+++ b/nodes/core/parsers/70-JSON.html
@@ -6,20 +6,30 @@
     </div>
     <hr align="middle"/>
     <div class="form-row">
-        <label style="width:100%;"><i class="fa fa-gears"></i> <span data-i18n="json.label.o2j"></span></label>
-        <input style="margin-left:16px; width:20px; vertical-align:top;" type="checkbox" id="node-input-pretty"><span data-i18n="json.label.pretty"></span>
+        <label style="width:100%; border-bottom: 1px solid #eee;"><span data-i18n="json.label.o2j"></span></label>
+    </div>
+    <div class="form-row" style="padding-left: 20px;">
+        <input style="width:20px; vertical-align:top; margin-right: 5px;" type="checkbox" id="node-input-pretty"><label style="width: auto;" for="node-input-pretty" data-i18n="json.label.pretty"></span>
     </div>
 </script>
 
 <script type="text/x-red" data-help-name="json">
-    <p>A function that parses the <code>msg.payload</code> to convert a JSON string
-    to or from a javascript object. Places the result back into the payload.</p>
+    <p>Converts between a JSON string and its JavaScript object representation, in either direction.</p>
     <h3>Inputs</h3>
-    <ul>
-        <li>If the input is a JSON string it tries to parse it to a javascript object.</li>
-        <li>If the input is a javascript object it creates a JSON string.</li>
-    </ul>
-    <p>When converting a JSON object to a string the output may optionally be pretty printed.</p>
+    <dl class="message-properties">
+        <dt>payload<span class="property-type">object | string</span></dt>
+        <dd>A JavaScript object or JSON string.</dd>
+    </dl>
+    <h3>Outputs</h3>
+    <dl class="message-properties">
+        <dt>payload<span class="property-type">object | string</span></dt>
+        <dd>
+            <ul>
+                <li>If the input is a JSON string it tries to parse it to a JavaScript object.</li>
+                <li>If the input is a JavaScript object it creates a JSON string. The string can optionally be well-formatted.</li>
+            </ul>
+        </dd>
+    </dl>
 </script>
 
 <script type="text/javascript">
diff --git a/nodes/core/parsers/70-XML.html b/nodes/core/parsers/70-XML.html
index 0e4702989..f33ef6811 100644
--- a/nodes/core/parsers/70-XML.html
+++ b/nodes/core/parsers/70-XML.html
@@ -6,33 +6,50 @@
     </div>
     <hr align="middle"/>
     <div class="form-row">
-        <label style="width:100%;"><i class="fa fa-gears"></i> <span data-i18n="xml.label.x2o"></span></label>
-        <div class="form-row">
-            <i style="margin-left:16px;" class="fa fa-key"></i> <span data-i18n="xml.label.represent"></span> <input type="text" id="node-input-attr" style="text-align:center; width:40px" placeholder="$">
-        </div>
-        <div class="form-row">
-            <i style="margin-left:16px;" class="fa fa-key"></i> <span data-i18n="xml.label.prefix"></span> <input type="text" id="node-input-chr" style="text-align:center; width:40px" placeholder="_">
-        </div>
-        <div class="form-tips"><span data-i18n="xml.tip"></span></div>
+        <label style="width:100%; border-bottom: 1px solid #eee;"><span data-i18n="xml.label.x2o"></span></label>
+    </div>
+    <div class="form-row" style="padding-left: 20px;">
+        <label style="width:250px;" for="node-input-attr" data-i18n="xml.label.represent"></label> <input type="text" id="node-input-attr" style="text-align:center; width:40px" placeholder="$">
+    </div>
+    <div class="form-row" style="padding-left: 20px;">
+        <label style="width:250px;" for="node-input-chr" data-i18n="xml.label.prefix"></label> <input type="text" id="node-input-chr" style="text-align:center; width:40px" placeholder="_">
     </div>
 </script>
 
 <script type="text/x-red" data-help-name="xml">
-    <p>A function that parses the <code>msg.payload</code> to convert xml to or from a javascript
-    object. Places the result in the payload.</p>
+    <p>Converts between an XML string and its JavaScript object representation, in either direction.</p>
     <h3>Inputs</h3>
-    <ul>
-        <li>If the input is a string it tries to parse it as XML and creates a javascript object.</li>
-        <li>If the input is a javascript object it tries to build an XML string.</li>
-    </ul>
     <dl class="message-properties">
-        <dt class="optional">options <span class="property-type">string</span></dt>
-        <dd>You can also pass in a <code>msg.options</code> object to override all the multitude of parameters. See
-            <a href="https://github.com/Leonidas-from-XIV/node-xml2js/blob/master/README.md#options" target="_blank">the xml2js docs</a>
+        <dt>payload<span class="property-type">object | string</span></dt>
+        <dd>A JavaScript object or XML string.</dd>
+    </dl>
+    <h3>Outputs</h3>
+    <dl class="message-properties">
+        <dt>payload<span class="property-type">object | string</span></dt>
+        <dd>
+            <ul>
+                <li>If the input is a string it tries to parse it as XML and creates a JavaScript object.</li>
+                <li>If the input is a JavaScript object it tries to build an XML string.</li>
+            </ul>
+        </dd>
+        <dt class="optional">options <span class="property-type">object</span></dt>
+        <dd>This optional property can be used to pass in any of the options supported by the underlying
+            library used to convert to and from XML. See <a href="https://github.com/Leonidas-from-XIV/node-xml2js/blob/master/README.md#options" target="_blank">the xml2js docs</a>
             for more information.</dd>
     </dl>
     <h3>Details</h3>
-    <p>If set, options in the edit dialogue override those passed in on the msg.options object.</p>
+    <p>When converting between XML and an object, any XML attributes are added as a property named <code>$</code> by default.
+    Any text content is added as a property named <code>_</code>. These property names can be specified in the node configuration.</p>
+    <p>For example, the following XML will be converted as shown:</p>
+    <pre>&lt;p class="tag"&gt;Hello World&lt;/p&gt;</pre>
+    <pre>{
+  "p": {
+    "$": {
+      "class": "tag"
+    },
+    "_": "Hello World"
+  }
+}</pre>
 </script>
 
 <script type="text/javascript">
diff --git a/nodes/core/parsers/70-YAML.html b/nodes/core/parsers/70-YAML.html
index 36c2e7b03..3f970e9e5 100644
--- a/nodes/core/parsers/70-YAML.html
+++ b/nodes/core/parsers/70-YAML.html
@@ -7,13 +7,22 @@
 </script>
 
 <script type="text/x-red" data-help-name="yaml">
-    <p>A function that parses the <code>msg.payload</code> to convert a YAML string to or
-    from a javascript object. Places the result back into the payload.</p>
+    <p>Converts between a YAML formatted string and its JavaScript object representation, in either direction.</p>
     <h3>Inputs</h3>
-    <ul>
-        <li>If the input is a YAML string it tries to parse it to a javascript object.</li>
-        <li>If the input is a javascript object it creates a YAML string.</li>
-    </ul>
+    <dl class="message-properties">
+        <dt>payload<span class="property-type">object | string</span></dt>
+        <dd>A JavaScript object or YAML string.</dd>
+    </dl>
+    <h3>Outputs</h3>
+    <dl class="message-properties">
+        <dt>payload<span class="property-type">object | string</span></dt>
+        <dd>
+            <ul>
+                <li>If the input is a YAML string it tries to parse it to a JavaScript object.</li>
+                <li>If the input is a JavaScript object it creates a YAML string.</li>
+            </ul>
+        </dd>
+    </dl>
 </script>
 
 <script type="text/javascript">