documentation

entity/Turnover_entity/recordcontainers/jdito/contentProcess.js

-import("system.logging");
 import("system.datetime");
 import("system.db");
 import("system.result");
@@ -15,7 +14,7 @@ var sumOfMonthForecast = db.table("select year(DATE_START) yearNum, month(DATE_S
 
 // build chartData
 var rootNode = "";
-var chartData = ParentingData.begin(rootNode);
+var chartData = ReferencingData.begin(rootNode);
 
 var skippedCounts = {};
 

others/guide/HowToDataLib.adoc

+How to use the DataLib (state: 21.01.2019)
+==========================================
+:toc2: left
+:numbered:
+
+== What is the DataLib ==
+The data lib provides objects for a more easy data structure creation.
+
+Currently the lib provides
+
+* DataTree
+** an object for building a tree structure
+* ReferencingData
+** a wrapper for DataTree
+** the programmer doesn't have to decide if the tree is needed, or if a simple array is sufficient. This Class will use the tree only if needed. 
+
+== DataTree ==
+See the library comments for further explanations.
+
+The purpose of this lib is
+
+* creating a tree object
+* creating an array with uid and parent from the tree object (e.g. for treetables and charts)
+* resolve problems with adding the same item multiple times (by creating new uuids)
+
+=== usage ===
+* import the lib:
+[source,javascript]
+----
+import("Data_lib");
+----
+* create an object
+[source,javascript]
+----
+var myDescriptiveNameOfTheTree = new DataTree(alias);
+// or
+var myDescriptiveNameOfTheTree = DataTree.begin(alias);
+----
+* use the object, add conditions
+[source,javascript]
+----
+var myTree = myDescriptiveNameOfTheTree.add("1", "myRoot", ["itemId1", "value"])
+                          .add("2", "myRoot", ["itemId2", "value"])
+                          .add("3", "2", ["itemId3", "value"])
+                          .add("4", "2", ["itemId4", "value"])
+                          .add("5", "4", ["itemId5", "value"])
+                          .add("5", "3", ["itemId5", "value"])  // Now you added id "5" a seccond time.
+                          .getTreeObject();
+
+var myArray = myDescriptiveNameOfTheTree.toArray();
+----
+
+Note that if you add an item two times, only the data-array of the second item is used! It will overwrite the data from the first one!
+
+== ReferencingData ==
+See the library comments for further explanations.
+
+The purpose of this lib is
+
+* creating an array with uid and parent from the tree object (e.g. for treetables and charts)
+* resolve problems with adding the same item multiple times (by creating new uuids)
+
+It is a wrapper for DataTree, but only uses the tree if needed. Otherwise the data is just concatenated to an array.
+
+It does not provide getTreeObject() because the tree is not always built.
+
+=== usage ===
+* import the lib:
+[source,javascript]
+----
+import("Data_lib");
+----
+* create an object
+[source,javascript]
+----
+var myDescriptiveName = new ReferencingData(alias);
+// or
+var myDescriptiveName = ReferencingData.begin(alias);
+----
+* use the object, add conditions
+[source,javascript]
+----
+var myTree = myDescriptiveName.add("1", "myRoot", ["itemId1", "value"])
+                          .add("2", "myRoot", ["itemId2", "value"])
+                          .add("3", "2", ["itemId3", "value"])
+                          .add("4", "2", ["itemId4", "value"])
+                          .add("5", "4", ["itemId5", "value"])
+                          .add("5", "3", ["itemId5", "value"])  // Now you added id "5" a seccond time. After this line the tree is used.
+                          .toArray();
+----
+
+Note that if you add an item two times, only the data-array of the second item is used! It will overwrite the data from the first one!
+
+== When to use which ==
+If you only need a array with parent - child - structure e.g. for the treetable or charts, use
+ReferencingData
+
+If you need a tree object for your logic, use DataTree.
\ No newline at end of file

process/Data_lib/process.js

 import("system.util");
 
 /**
- *  TODO: documentation!!
+ * This class is for data which is built in a children -> parent -  way. Eich "row" consists of one UID and one parentId.<br>
+ * The class makes sure that even if you add an child multiple times, the ID is corrected, so that the resulting array has only unique id's.<br>
+ * <br>
+ * Keep in mind for performance reasons that as soon, as you add a seccond item withe the same UID as an already added child, a tree-object is buiilt internally.<br>
+ * If you only add unique children, this class will just push them to a simple array.<br>
+ * <br>
+ * Note that if you add an item two times, only the data-array of the second item is used! It will overwrite the data from the first one!<br>
+ * <br>
+ * The UID's and parentID's in the generated array may not be the same as you added. If you need to know what you added, simply provide an ID also as data.<br>
+ * <br>
+ * When to use this class:<br>
+ * - you want to fill a Treetable or MultiDataChart<br>
+ * - and it should be possible to add the same children several times<br>
+ * <br>
+ * When NOT to use this class:<br>
+ * - you need a Tree-Object for your logic and / or want to do additional stuff with the tree -> use "DataTree" directly, because ReferencingData doesn't build always a tree.<br>
+ * 
+ * @param {String} pRootId the Id you use as parentId for the root elements. The parentId for base elements will be changed to "" when using toArray().
+ * 
+ * @example
+ * var myResult = ReferencingData.begin("myRoot")
+ *                .add("1", "myRoot", ["itemId1", "value"])
+ *                .add("2", "myRoot", ["itemId2", "value"])
+ *                .add("3", "2", ["itemId3", "value"])
+ *                .add("4", "2", ["itemId4", "value"])
+ *                .add("5", "4", ["itemId5", "value"])
+ *                .add("5", "3", ["itemId5", "value"])  // Now you added id "5" a seccond time. As soon as you do this, a tree will be generated internally to resolve the ID's.
+ *                .toArray();
+ *                
+ * results in:
+ * [  
+ *    [  
+ *       "eb2c88a3-ba9d-4991-acf5-7476e7dc5628", // note that the IDs are now new UUIDs
+ *       "",                                     // note that the parentId is now ""
+ *       "itemId1",
+ *       "value"
+ *    ],
+ *    [  
+ *       "f245bfdf-6e3b-4c83-8c4b-14225acce7b3",
+ *       "",
+ *       "itemId2",
+ *       "value"
+ *    ],
+ *    [  
+ *       "054e605e-6224-4cc5-8f02-04c6a6d7965d",
+ *       "f245bfdf-6e3b-4c83-8c4b-14225acce7b3",
+ *       "itemId3",
+ *       "value"
+ *    ],
+ *    [  
+ *       "818641ca-bcf3-415b-8c0e-e2e55430d4d8",
+ *       "054e605e-6224-4cc5-8f02-04c6a6d7965d",
+ *       "itemId5",
+ *       "value"
+ *    ],
+ *    [  
+ *       "c8e81040-c9e1-4f74-bd0f-fb4615ae6bec",
+ *       "f245bfdf-6e3b-4c83-8c4b-14225acce7b3",
+ *       "itemId4",
+ *       "value"
+ *    ],
+ *    [  
+ *       "55eeb384-e5dd-4759-b70d-c2a289762168",
+ *       "c8e81040-c9e1-4f74-bd0f-fb4615ae6bec",
+ *       "itemId5",
+ *       "value"
+ *    ]
+ * ]
+ * 
  * @class
  */
-function ParentingData(pRootId) 
+function ReferencingData(pRootId) 
 {
     this._data = [];
     this._uids = {};
@@ -12,36 +80,61 @@ function ParentingData(pRootId)
 }
 
 /**
- * @return {DataTree}
+ * creates a new ReferencingData-object
+ * 
+ * @param {String} pRootId the Id you use as parentId for the root elements. The parentId for base elements will be changed to "" when using toArray().
+ * @return {ReferencingData} the new instance
  */
-ParentingData.begin = function(pRootId) 
-{
-    return new ParentingData(pRootId);
+ReferencingData.begin = function(pRootId) 
+{   var referencingData = new ReferencingData(pRootId);
+    return referencingData;
 }
 
-ParentingData.prototype.addArray = function(pData) 
+/**
+ * Add an array of data. It will be added row by row to the already added data.
+ *
+ * @param {Array} pData the data in the form: [ [uid, parentId, [data...],  [uid2, parentId2, [data2...] ]
+ * @return {ReferencingData} this
+ */
+ReferencingData.prototype.addArray = function(pData) 
 {
     pData.forEach(function(pRow)
     {
         this.add(pRow[0], pRow[1], pRow.splice(2));
-    }, this);
+    }, this); // make "this" also available inside of the forEach
     
     return this;
 }
 
-ParentingData.prototype.add = function(pUid, pParentId, pData) 
+/**
+ * Add one row. If the uid already exists, the data is converted internally to a tree to resolve the ids.
+ * 
+ * @param {String} pUid the id of the row
+ * @param {String} pParentId the parentId of the row
+ * @param {String} pData the data
+ * @return {ReferencingData} this
+ */
+ReferencingData.prototype.add = function(pUid, pParentId, pData) 
 {
     if (this._dataTree == undefined && this._uids[pUid] == undefined) 
     {
         this._uids[pUid] = true;
         this._data.push([pUid, pParentId].concat(pData));
     } else {
-        this._convertToTree();
+        this._convertToTree(); // convert to tree if not already a tree
         this._dataTree.add(pUid, pParentId, pData);
     }
+    return this;
 }
 
-ParentingData.prototype.toArray = function(pMaxDepth) 
+/**
+ * Get an array of the added data with already resolved, unique uid's.
+ * @param {Integer} [pMaxDepth=undefined] If it is set AND if the internal tree-object is used, this option can limit the depth of the tree.
+ *                                        This is especially to prevent stack overflows if a children-parent-loop exists.
+ *                                        If you only added unique items, this parameter is ignored!
+ * @return {Array} [ [uid, parentId, [data...],  [uid2, parentId2, [data2...] ]
+ */
+ReferencingData.prototype.toArray = function(pMaxDepth) 
 { 
     if (this._dataTree == undefined)
     {
@@ -53,7 +146,12 @@ ParentingData.prototype.toArray = function(pMaxDepth)
     }
 }
 
-ParentingData.prototype._convertToTree = function() 
+/**
+ * switch to tree if the tree is not already used.
+ * 
+ * @ignore
+ */
+ReferencingData.prototype._convertToTree = function() 
 {
     if (this._dataTree == undefined)
     {
@@ -64,7 +162,84 @@ ParentingData.prototype._convertToTree = function()
 }
 
 /**
- *  TODO: documentation + evtl. check-function for loops
+ * This class is for creating a tree structure.
+ * @param {String} pRootId the Id you use as parentId for the root elements. The parentId for base elements will be changed to "" when using toArray().
+ * 
+ * @example
+ * 
+ * var myResult = DataTree.begin("myRoot")
+ *                .add("1", "myRoot", ["itemId1", "value"])
+ *                .add("2", "myRoot", ["itemId2", "value"])
+ *                .add("3", "2", ["itemId3", "value"])
+ *                .add("4", "2", ["itemId4", "value"])
+ *                .add("5", "4", ["itemId5", "value"])
+ *                .add("5", "3", ["itemId5", "value"])  // Now you added id "5" a seccond time.
+ *                .getTreeObject();
+ * results in:
+ * 
+ * ({  
+ *   1:{  
+ *      data:[  
+ *         "itemId1",
+ *         "value"
+ *      ],
+ *      parent:"myRoot",
+ *      ids:[  
+ *
+ *      ]
+ *   },
+ *   2:{  
+ *      data:[  
+ *         "itemId2",
+ *         "value"
+ *      ],
+ *      parent:"myRoot",
+ *      ids:[  
+ *         "3",
+ *         "4"
+ *      ]
+ *   },
+ *   3:{  
+ *      data:[  
+ *         "itemId3",
+ *         "value"
+ *      ],
+ *      parent:"2",
+ *      ids:[  
+ *         "5"
+ *      ]
+ *   },
+ *   4:{  
+ *      data:[  
+ *         "itemId4",
+ *         "value"
+ *      ],
+ *      parent:"2",
+ *      ids:[  
+ *         "5"
+ *      ]
+ *   },
+ *   5:{  
+ *      data:[  
+ *         "itemId5",
+ *         "value"
+ *      ],
+ *      parent:"3",
+ *      ids:[  
+ *
+ *      ]
+ *   },
+ *   myRoot:{  
+ *      ids:[  
+ *         "1",
+ *         "2"
+ *      ],
+ *      parent:"9f034e84-39a8-4239-ba06-ccc604654477"
+ *   }
+ *})
+ * 
+ * TODO: evtl check-funktion anbieten
+ * 
  * @class
  */
 function DataTree(pRootId) 
@@ -79,7 +254,10 @@ function DataTree(pRootId)
 }
 
 /**
- * @return {DataTree}
+ * creates a new DataTree-object
+ * 
+ * @param {String} pRootId the Id you use as parentId for the root elements. The parentId for base elements will be changed to "" when using toArray().
+ * @return {DataTree} the new instance
  */
 DataTree.begin = function(pRootId) 
 {
@@ -87,16 +265,39 @@ DataTree.begin = function(pRootId)
 }
 
 /**
- *
- * @param {String[]} pData
- * @param {manipulateNodeCallback} pManipulateNodeFn
- * 
+ * Get the tree object. See the example of the class.
+ * @return {Object} the tree-object
+ * ({  
+ *   GENERATED_UUID:{  
+ *      data:[  
+ *         ...
+ *         ...
+ *      ],
+ *      parent:"parentId",
+ *      ids:[  
+ *          "childid1",
+ *          "childid2",
+ *          ....
+ *      ]
+ *   },
+ *   ...
+ * )
  */
 DataTree.prototype.getTreeObject = function() 
 {
     return this._dataTree;
 }
 
+/**
+ * Add one row.
+ * Note that if you add an item two times, only the data-array of the second item is used! It will overwrite the data from the first one!
+ * 
+ * @param {String} pUid the id of the row
+ * @param {String} pParentId the parentId of the row
+ * @param {String} pData the data
+ * @param {DataTree~manipulateNode} [pManipulateNodeFn=undefined] callback for manipulating the Node. Attention: Use with caution. You can corrupt the tree. 
+ * @return {DataTree} this
+ */
 DataTree.prototype.add = function(pUid, pParentId, pData, pManipulateNodeFn) 
 {
     if (this._dataTree[pParentId] == undefined) 
@@ -138,10 +339,13 @@ DataTree.prototype.add = function(pUid, pParentId, pData, pManipulateNodeFn)
 }
 
 /**
- *
- * @param {String[]} pData
- * @param {manipulateNodeCallback} pManipulateNodeFn may be called more than once for each node!!!
+ * Add an array of data. It will be added row by row to the already added data.
+ * Note that if you add an item two times, only the data-array of the second item is used! It will overwrite the data from the first one!
+ * 
+ * @param {Array} pData the data in the form: [ [uid, parentId, [data...],  [uid2, parentId2, [data2...] ]
+ * @param {DataTree~manipulateNode} [pManipulateNodeFn=undefined] callback for manipulating the Node. Attention: Use with caution. You can corrupt the tree. 
  * 
+ * @return {DataTree} this
  */
 DataTree.prototype.addArray = function(pData, pManipulateNodeFn) 
 {
@@ -153,6 +357,12 @@ DataTree.prototype.addArray = function(pData, pManipulateNodeFn)
     return this;
 }
 
+/**
+ * Get an array of the added data with already resolved, unique uid's.
+ * @param {Integer} [pMaxDepth=undefined] If it is set, this option can limit the depth of the tree.
+ *                                        This is especially to prevent stack overflows if a children-parent-loop exists.
+ * @return {Array} [ [uid, parentId, [data...],  [uid2, parentId2, [data2...] ]
+ */
 DataTree.prototype.toArray = function(pMaxDepth) 
 {   
     var that = this;
@@ -169,6 +379,7 @@ DataTree.prototype.toArray = function(pMaxDepth)
         for (var i = 0; i < pNode.ids.length; i++) {
             if (pNode.parent == that.baseId)
             {
+                // set UUID to "" if it is a root-node
                 pParent = "";
             }
             
@@ -184,6 +395,7 @@ DataTree.prototype.toArray = function(pMaxDepth)
     {
         uidMap[pUid] = util.getNewUUID();
         if (uidMap[pParentId] == undefined) {
+            // The root node has "" as ID.
             if (pParentId == "")
             {
                 uidMap[pParentId] = "";
@@ -198,4 +410,16 @@ DataTree.prototype.toArray = function(pMaxDepth)
     }
     
     return treeArray;
-}
\ No newline at end of file
+}
+
+/**
+ * Manipulate a node with this callback
+ * You get the uid of the node and the node.
+ * You can do anything you want, with the node.
+ * 
+ * But if you modify parent or ids, the tree may corrupt.
+ * 
+ * @callback DataTree~manipulateNode
+ * @param {String} pUid
+ * @param {Object} pNode
+ */
\ No newline at end of file