Revize 583f8755

Re #9006 - Přidat komentáře ke kódu

• add code comments

src/app/shared/graph-loading/emptygraph.ts

@@ -2 +2 @@
 
 declare var require: any
 
+/**
+ * A graph with no sensors to display
+ */
 export class EmptyGraph implements Graph{
 
+  /**
+   * Message in the middle of the graph
+   */
   message: string;
 
   constructor(message) {
     this.message = message;
   }
 
-
+  /**
+   * Returns vega configuration
+   */
   getConfig(): {} {
     return require('/src/vega/config/config.json');
   }
 
+  /**
+   * Returns vega specification
+   */
   getSpec(): {} {
     const lodash = require('lodash/object');
     const rvalue: any = {};
@@ -24 +35 @@
     return rvalue;
   }
 
-  setData(spec, data) {
-    //DO NOTHING
-  }
-
-  setLegendInfo(spec, legend) {
-    //DO NOTHING
-  }
-
 }

src/app/shared/graph-loading/graph.ts

@@ -1 +1 @@
 export interface Graph {
+  /**
+   * Gets vega specification
+   */
   getSpec(): {},
+
+  /**
+   * Gets vega configuration
+   */
   getConfig(): {}
 }

src/app/shared/graph-loading/graphloader.ts

@@ -9 +9 @@
 
 export class GraphLoader {
 
+  /**
+   * Loads graph with default interval value (e.g. for observation service)
+   * @param sensors array of sensors to display
+   * @param data source of values for vega graph
+   * @param legendInfo source of legend info for graph (e.g. sensor phenomenon)
+   * @param element name of html element for graph display
+   * @param isAnalytics true/false analytics/observations
+   */
+  static getGraph(sensors, data, legendInfo, element, isAnalytics) {
+    this.getGraphWithInterval(sensors, data, 1800000, legendInfo, element, isAnalytics);
+  }
+
+
+
+  /**
+   * Loads graph with specified interval (e.g. for analytics service)
+   * @param sensors array of sensors to display
+   * @param data source of values for vega graph
+   * @param interval default graph interval used for different purposes (in milliseconds) (see timeWindow and maxTimeDifference in vega specification)
+   * @param legendInfo source of legend info for graph (e.g. sensor phenomenon)
+   * @param element name of html element for graph display
+   * @param isAnalytics true/false analytics/observations
+   */
+  static getGraphWithInterval(sensors, data, interval, legendInfo, element, isAnalytics) {
+    //gets uses sensors array to get graph type
+    //then gets configuration and specification from corresponding class
+    let graph = this.getGraphType(sensors,data, interval, legendInfo, isAnalytics);
+    let config = graph.getConfig();
+    let spec = graph.getSpec();
+
+   //then displays the graph
+    this.showGraph(spec, config, element);
+  }
+
 
-  static getGraphType(sensors, data, interval, legend, isAnalytics): Graph {
+  /**
+   * Create graph of specific type according to selected sensors
+   * @param sensors array of sensors to display
+   * @param data source of values for vega graph
+   * @param interval default graph interval used for different purposes (in milliseconds) (see timeWindow and maxTimeDifference in vega specification)
+   * @param legendInfo source of legend info for graph (e.g. sensor phenomenon)
+   * @param isAnalytics isAnalytics true/false analytics/observations
+   */
+  static getGraphType(sensors, data, interval, legendInfo, isAnalytics): Graph {
     if (sensors == null) {
       return new EmptyGraph("No sensors selected.");
 
@@ -18 +60 @@
       if (sensors.length == 0) {
         return new EmptyGraph("No sensors selected.");
       } else if (sensors.length == 1) {
-        return new SingleGraph(sensors[0], isAnalytics, data, legend,interval);
+        return new SingleGraph(sensors[0], isAnalytics, data, legendInfo,interval);
       } else {
-        return new MultiGraph(isAnalytics, data, legend,interval);
+        return new MultiGraph(isAnalytics, data, legendInfo,interval);
       }
 
     } else {
-      return new SingleGraph(sensors, isAnalytics, data, legend, interval);
+      return new SingleGraph(sensors, isAnalytics, data, legendInfo, interval);
     }
   }
 
 
-  static getGraphWithInterval(sensors, data, interval, legendInfo, element, isAnalytics) {
-    let graph = this.getGraphType(sensors,data, interval, legendInfo, isAnalytics);
-    let config = graph.getConfig();
-    let spec = graph.getSpec();
-
-
-    this.showGraph(spec, config, element);
-  }
-
-  static getGraph(sensors, data, legendInfo, element, isAnalytics) {
-    this.getGraphWithInterval(sensors, data, 1800000, legendInfo, element, isAnalytics);
-  }
-
-
+  /**
+   * Displays the graph
+   * @param spec vega specification
+   * @param config vega configuration
+   * @param element name of html element for graph display
+   */
   static showGraph(spec, config, element) {
     const vega = require('vega');
     const vegaTooltip = require('vega-tooltip');

src/app/shared/graph-loading/multigraph.ts

@@ -2 +2 @@
 
 declare var require: any
 
+/**
+ * Graph with multiple sensors. (Only linechart)
+ */
 export class MultiGraph implements Graph{
 
+
   isAnalytics: boolean;
   data: any [];
   interval: number;
   legend: {};
 
+  /**
+   * Instantiates new multigraph
+   * @param isAnalytics true/false analytics/observations
+   * @param data source of values for vega graph
+   * @param legend source of legend for graph (e.g. sensors phenomenon)
+   * @param interval default graph interval used for different purposes (in milliseconds) (see timeWindow and maxTimeDifference in vega specification)
+   */
   constructor(isAnalytics: boolean, data: any [], legend: {}, interval: number) {
     this.isAnalytics = isAnalytics;
     this.data = data;
@@ -17 +28 @@
 
   }
 
-
+  /**
+   * Returns vega configuration (see readme.txt in vega folder)
+   */
   getConfig(): {} {
+    //from folder vega/config merge corresponding files
+
     const lodash = require('lodash/object');
     const rvalue: any = {};
     let config1 = require('/src/vega/config/config.json');
@@ -47 +62 @@
     return rvalue;
   }
 
+
+  /**
+   * returns vega specification (see readme.txt in vega folder)
+   */
   getSpec(): {} {
     const lodash = require('lodash/object');
     const rvalue: any = {};
@@ -57 +76 @@
 
     lodash.merge(rvalue, base, body, legend, tooltip);
 
-    rvalue.data[1].values = this.data;
+    //setting legend to result
     rvalue.data[0].values = this.legend;
+
+    //setting data to result
+    rvalue.data[1].values = this.data;
+
+    //setting interval to json
+    //interval used for
+    // 1) appending graph domain
+    // 2) 5 * interval is max difference for connecting the dots
+    // 3) setting zoom in windcharts
     rvalue.signals[0].value = this.interval;
+
+    //setting tooltip message
     rvalue.marks[0].marks[0].marks[0].marks[2].encode.enter.tooltip.signal = this.getTooltipMessage();
 
     return rvalue;
   }
 
+  /**
+   * Generates the tooltip message
+   */
   private getTooltipMessage() {
     let message = "{title: timeFormat(datum.dateTime, '%A, %B %e, %Y %X')";
     this.data.forEach(function (e) {
@@ -75 +108 @@
     return message;
   }
 
+  /**
+   * If legend is array of phenomenons, it selects the first element
+   * @param legend info for displaying legend
+   */
   private getLegend(legend: any) {
     if(Array.isArray(legend)) {
       return legend[0];

src/app/shared/graph-loading/singlegraph.ts

@@ -3 +3 @@
 
 declare var require: any
 
+/**
+ * Graph with single sensors (linechart, barchart, windchart)
+ */
 export class SingleGraph implements Graph {
   isAnalytics: boolean;
   sensorId: number;
@@ -11 +14 @@
   legend: {};
   type: SingleGraphType;
 
+  /**
+   *
+   * @param sensorId id of sensor
+   * @param isAnalytics true for analytics, false for observations
+   * @param data source of values for vega graph
+   * @param legend source of legend info for graph (e.g. sensor phenomenon)
+   * @param interval default graph interval used for different purposes (in milliseconds) (see timeWindow and maxTimeDifference in vega specification)
+   */
   constructor(sensorId: number, isAnalytics: boolean, data: any[], legend: {}, interval: number) {
     this.sensorId = sensorId;
     this.isAnalytics = isAnalytics;
@@ -21 +32 @@
 
   }
 
-
+  /**
+   * Returns vega configuration (see readme.txt in vega folder)
+   */
   getConfig(): {} {
     const lodash = require('lodash/object');
     const rvalue: any = {};
@@ -60 +73 @@
     return rvalue;
   }
 
+  /**
+   * Gets vega specification (see readme.txt in vega folder)
+   */
   getSpec(): {} {
     const lodash = require('lodash/object');
     const rvalue: any = {};
@@ -69 +85 @@
     const tooltip = this.getTooltipSpec();
     lodash.merge(rvalue, base, body, legend, tooltip);
 
-
+    //setting data to result
     this.setData(rvalue, this.data);
+
+    //setting legend to result
     rvalue['data'][0].values = this.legend;
+
+    //setting interval to result
     rvalue.signals[0].value = this.interval;
 
     return rvalue;
   }
 
-
+  /**
+   * Gets legend specification (windchart does not have a legend)
+   */
   private getLegendSpec() {
     switch (this.type) {
       case SingleGraphType.BARCHART:
@@ -88 +110 @@
     }
   }
 
+  /**
+   * Gets body specification
+   */
   private getBodySpec() {
     switch (this.type) {
       case SingleGraphType.BARCHART:
@@ -95 +120 @@
       case SingleGraphType.WINDCHART:
         return require('/src/vega/body/windchart.json');
       case SingleGraphType.LINECHART:
-        //TODO pridat min/max
         return require('/src/vega/body/linechart.json');
     }
   }
 
 
+  /**
+   * Get tooltip specification
+   */
   private getTooltipSpec() {
     let lodash = require('lodash');
     let tooltipMessage;
@@ -113 +140 @@
       tooltipMessage = this.getValueTooltip();
     }
 
+    //sets the tooltip message
     rvalue.marks[0].marks[0].marks[0].encode.enter.tooltip.signal = tooltipMessage;
     return rvalue;
   }
 
-
+  /**
+   *
+   */
   private getValueTooltip() {
     return "{title: timeFormat(datum.dateTime, '%A, %B %e, %Y %X')  ,  'value': datum.value + ' " + this.legend['phenomenon']['unit'] + "'}"
   }
@@ -131 +161 @@
   }
 
 
+  /**
+   * Sets data to specification. If data is array, it selects only the first element
+   * @param spec specification to insert into
+   * @param data data to insert
+   */
   private setData(spec: any, data: any) {
     if(data.length > 0 && 'data' in data[0]) {
       spec['data'][1].values = data[0].data;
@@ -139 +174 @@
     }
   }
 
+  /**
+   * If legend is array of phenomenons, it selects the first element
+   * @param legend info for displaying legend
+   */
   private getLegend(legend: any) {
     if (Array.isArray(legend)) {
       return legend[0];
@@ -147 +186 @@
     }
   }
 
+  /**
+   * Select the graph type from id
+   */
   private getGraphType() {
     if (this.sensorId >= 480000000 && this.sensorId < 490000000) {
       return SingleGraphType.BARCHART;

src/vega/readme.txt

@@ +1 @@
+1) Getting vega specification
+
+a) getting the base
+empty -> for empty graphs
+default -> for other graphs
+
+b) getting the body
+barchart / linechart / multilinechart / windchart
+
+c) getting the legend specification
+
+d) getting the tooltip specification
+(samm -> sum, avg, min, max)
+
+e) merging the files into result
+
+
+2) Vega configurations.
+
+Process of getting configuration:
+a) gets config.json
+b) gets other config file for corresponding graphs
+c) merge signals array from other graph to config.json
+
+(barline = bar + line)
+
+note: config signals typically contain path to values
+