ctrlx-datalayer-request.html

<!--

  MIT License

  Copyright (c) 2020-2021 Bosch Rexroth AG

  Permission is hereby granted, free of charge, to any person obtaining a copy
  of this software and associated documentation files (the "Software"), to deal
  in the Software without restriction, including without limitation the rights
  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
  copies of the Software, and to permit persons to whom the Software is
  furnished to do so, subject to the following conditions:

  The above copyright notice and this permission notice shall be included in all
  copies or substantial portions of the Software.

  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  SOFTWARE.

-->


<!--

  ctrlx-datalayer-request -- A node to read data from the datalayer.

-->
<script type="text/javascript">

  var treeList_Request;

  function onEditPrepare_Request(node) {

    // Create a new TreeList widget.
    // See: https://nodered.org/docs/api/ui/treeList/
    //      https://discourse.nodered.org/t/select-form-with-tree-structure-in-custom-node/8348
    treeList_Request = $("<div>")
      .css({width: "100%", height: "100%"})
      .appendTo(".node-input-browse-row")
      .treeList({})
      .on('treelistitemmouseover', function(e, item) {
      })
      .on('treelistitemmouseout', function(e, item) {
      })
      .on('treelistselect', function(event, item) {
        if (item.id && item.id !== '') {
          $('#node-input-path').val(item.id);
        }
      });


    // Now create the root item of the tree view.
    let rootItem = {
      label:  "Data Layer",
      id: '',
      class: 'red-ui-palette-header',
      expanded: true,
      children: function(done) {

        // The current selected path of the node.
        let path = $('#node-input-path').val();

        // Get a reference to the config node settings.
        let configNodeDevice = RED.nodes.node($('#node-input-device').val());

        // We need to browse the child items on the server(runtime of Node-RED). For this, the server needs to know the config node or username/password.
        let username = (configNodeDevice && configNodeDevice.credentials) ? configNodeDevice.credentials.username : undefined;
        let password = (configNodeDevice && configNodeDevice.credentials) ? configNodeDevice.credentials.password : undefined;
        let hostname = (configNodeDevice) ? configNodeDevice.hostname : undefined;
        let id = (configNodeDevice) ? configNodeDevice.id : undefined;

        // Ask the server to browse the given path for us. Send all necessary infos along the request.
        $.getJSON('ctrlx/browse', {id: id, path: this.id, hostname: hostname, username: username, password: password}, (result) => {

          // Create a new subitem for each browsed element
          let childs = result.map((val) => {
            let childId = (this.id) ? this.id + '/' + val : val;
            return {
              id: childId,
              label: val,
              expanded: path.startsWith(childId) ? true : false,
              selected: (path === childId) ? true : undefined,
              children: this.children
            }
          });
          done(childs);

        }).fail(function(jqxhr, textStatus, error) {

          // Display a toast message on error.
          RED.notify('Something went wrong (' + error + '). Please retry.', 'error');
          console.log(textStatus + ', ' + error);
          done([]);

        });
      }
    }
    let items = [];
    items.push(rootItem);

    // Show and fill the TreeView when button is clicked.
    $('#node-input-browse-button').click(function() {

      treeList_Request.treeList('empty');
      treeList_Request.treeList('data', items);
      $(".node-input-browse-row").show()

      setTimeout(function() {
        treeList_Request.treeList('show', '');
      }, 100);

    });
  }

  function resizeNodeList_Request() {
      var rows = $("#dialog-form>div:not(.node-input-browse-row)");
      var height = $("#dialog-form").height();
      for (var i = 0; i < rows.length; i++) {
          height -= $(rows[i]).outerHeight(true);
      }
      var editorRow = $("#dialog-form>div.node-input-browse-row");
      height -= (parseInt(editorRow.css("marginTop")) + parseInt(editorRow.css("marginBottom")));
      $(".node-input-browse-row").css("height",height+"px");
  }

  function generateName_Request(node) {
    if (node.name) {
      return node.name;
    } else if (node.path && node.method) {
      if (node.path.length < 50) {
        return `${node.method}: ${node.path}`;
      } else {
        let shortPath = node.path.substr(node.path.length - 45);
        let shortPathStart = Math.max(shortPath.indexOf('/'), 0);
        return `${node.method}: ...${shortPath.substr(shortPathStart)}`;
      }
    } else if (node.method && !node.path) {
      return `${node.method}: <msg.path>`;
    } else {
      return 'Data Layer Request';
    }
  }

  function validateIntPropertyWithDefault_Request(prop, opts) {
    if (prop === '' || (Number.isInteger(parseInt(prop)) && parseInt(prop) >= 0)) {
      return true;
    }
    return "Must be a positive number or empty field";
  }

  RED.nodes.registerType('ctrlx-datalayer-request', {
      category: 'ctrlX AUTOMATION',
      color: '#C0DEED',
      icon: 'icons/core.png',
      defaults: {
        device: {type: 'ctrlx-config', required: true},
        method: {value: 'READ', required: true},
        path: {value: '', required: false},
        payloadFormat: {value: 'value_type', required: true},
        name: {value: ''},
        pendingWarnLevel: {value: 50, required: false, validate: validateIntPropertyWithDefault_Request},
        pendingErrorLevel: {value: 100, required: false, validate: validateIntPropertyWithDefault_Request}
      },
      inputs: 1,
      outputs: 1,
      paletteLabel: 'Data Layer Request',
      label: function() {
        return generateName_Request(this);
      },
      oneditprepare: function() {
        onEditPrepare_Request(this);
      },
      oneditresize: resizeNodeList_Request
  });
</script>




<script type="text/html" data-template-name="ctrlx-datalayer-request">

  <div class="form-row">
    <label for="node-input-device"><i class="fa fa-sign-in"></i> Device</label>
    <input type="text" id="node-input-device">
  </div>

  <div class="form-row">
    <label for="node-input-method"><i class="fa fa-tasks"></i> Method</label>
    <select type="text" id="node-input-method" style="width:70%;">
    <option value="READ">READ</option>
    <option value="WRITE">WRITE</option>
    <option value="CREATE">CREATE</option>
    <option value="DELETE">DELETE</option>
    <option value="BROWSE">BROWSE</option>
    <option value="METADATA">METADATA</option>
    <option value="READ_WITH_ARG">READ_WITH_ARG</option>
    <option value="msg">- set by msg.method -</option>
    </select>
  </div>

  <div class="form-row">
    <label for="node-input-path"><i class="fa fa-globe"></i> Path</label>
    <input id="node-input-path" type="text" placeholder="path/to/data/layer/node">
    <button type="button" id="node-input-browse-button" class="btn"><i class="fa fa-search"></i></button>
  </div>

  <div class="form-row node-input-browse-row" hidden></div>

  <div class="form-row">
    <label for="node-input-payloadFormat"><i class="fa fa-sign-out"></i> Payload</label>
    <select id="node-input-payloadFormat" style="width:70%;">
      <option value="value_type">value + type (json)</option>
      <option value="value">value only</option>
      <!--<option value="v1">v1 (deprecated)</option>-->
    </select>
  </div>

  <hr>

  <div class="form-row">
    <i class="fa fa-bookmark"></i> Limits for number of active requests (0=disabled):
  </div>
  <div class="form-row"><label></label>
    Warning: <input type="number" min="0" id="node-input-pendingWarnLevel" style="width:90px;">&nbsp;&nbsp;Error: <input type="number" min="0" id="node-input-pendingErrorLevel" style="width:90px;">
  </div>

  <hr>

  <div class="form-row">
    <label for="node-input-name"><i class="fa fa-tag"></i> Name</label>
    <input type="text" id="node-input-name" placeholder="Name">
  </div>

</script>




<script type="text/html" data-help-name="ctrlx-datalayer-request">

  <p>Use this node to read or write data to the ctrlX Data Layer.</p>

  <h3>Inputs</h3>
  <dl class="message-properties">
    <dt class="optional">path <span class="property-type">string</span></dt>
    <dd>If not configured in the node, this optional property sets the path of the request.</dd>

    <dt class="optional">method <span class="property-type">string</span></dt>
    <dd>If not configured in the node, this optional property sets the method of the request.
        Must be one of <code>READ</code>, <code>WRITE</code>, <code>CREATE</code>, <code>DELETE</code>, <code>BROWSE</code>, <code>READ_WITH_ARG</code> or <code>METADATA</code>.</dd>

    <dt class="optional">payload <span class="property-type">object</span></dt>
    <dd>Data to be sent in case of WRITE, READ_WITH_ARG or CREATE method.</dd>

    <dt class="optional">requestTimeout <span class="property-type">number</span></dt>
    <dd>If set to a positive number of milliseconds, will override the globally set <code>httpRequestTimeout</code> parameter.</dd>
  </dl>

  <h3>Outputs</h3>
  <dl class="message-properties">
    <dt>payload <span class="property-type">string | object</span></dt>
    <dd>The body of the response. The node can be configured to return only the value of the data
        as a string or value and type as a json object.</dd>

    <dt>topic <span class="property-type">string</span></dt>
    <dd>If the <code>topic</code> property is not already set in the <code>msg</code> object as input, then it will be set to the effective
        <code>path</code> of request.</dd>
  </dl>

  <h3>Details</h3>
  <p>In case of an error, the node will not emit a <code>msg</code> but throw an error, that can be catched by the <code>catch</code> node.</p>
  <p>The <code>limits</code> can be used to prevent, that the flow gets unstable when the rate at which requests are sent from the flow
    is constantly higher than the rate at which these can be processed on server side. To do so, all further requests get dropped as long as the number of
    active requests  (i.e. pending responses) is higher than the <code>Error</code> limit. This case can also be catched by the <code>catch</code> node.
    When the number of active requests reaches the <code>Warning</code> limit only a warning message will be logged.
  </p>
  <!-- TODO: implement later
  <p><b>Note</b>: If running behind a proxy, the standard <code>http_proxy=...</code> environment variable should be set and Node-RED restarted, or use Proxy Configuration. If Proxy Configuration was set, the configuration take precedence over environment variable.</p>
  -->

  <h3>References</h3>
  <ul>
    <li><a href="https://github.com/boschrexroth/node-red-contrib-ctrlx-automation">GitHub</a> - the nodes github repository</li>
    <li><a href="https://developer.community.boschrexroth.com">ctrlX Community</a> - forum and support</li>
    <li><a href="https://docs.automation.boschrexroth.com">ctrlX AUTOMATION Product Help</a> - the online documentation of ctrlX AUTOMATION</li>
    <li><a href="https://www.boschrexroth.com">Bosch Rexroth AG</a> - WE MOVE. YOU WIN.</li>
  </ul>

</script>