Merge pull request #33 from BasicPrimitives/loops

Loops Optimization

Author: BasicPrimitives

.eslintrc.json

@@ -18,6 +18,7 @@
     "no-unused-vars": 0,
     "no-fallthrough": 0,
     "no-control-regex": 0,
-    "no-empty": 0
+    "no-empty": 0,
+    "no-constant-condition": 0
   }
 }

ReferenceControlsProcessingDiagram.html

@@ -84,9 +84,11 @@
         default:
           controlOptions = primitives.famdiagram.getProcessDiagramConfig();
           primitives.common.mergeObjects(viewOptions, {
-            'AddLabelAnnotationsTask': { primaryParent: 'LogicalFamilyTask' },
-            'RemoveLoopsTask': { primaryParent: 'AddLabelAnnotationsTask' },
-            'AddSpousesTask': { primaryParent: 'RemoveLoopsTask' },
+            'RemoveLoopsOptionTask': { relativeItem: 'ItemsOptionTask', placementType: primitives.common.AdviserPlacementType.Right, position: 1 },
+
+            'RemoveLoopsTask': { primaryParent: 'LogicalFamilyTask' },
+            'AddLabelAnnotationsTask': { primaryParent: 'RemoveLoopsTask' },
+            'AddSpousesTask': { primaryParent: 'AddLabelAnnotationsTask' },
             'HideGrandParentsConnectorsTask': { primaryParent: 'AddSpousesTask' },
             'NormalizeLogicalFamilyTask': { primaryParent: 'HideGrandParentsConnectorsTask' },
             'OrderFamilyNodesTask': { primaryParent: 'NormalizeLogicalFamilyTask' },

apireference/algorithms.md

@@ -146,12 +146,28 @@ Eliminates direct relations between grand parent nodes.
  Returns: `family` - returns family structure without direct grand parent relations.
 
 
- `getGraph()` 
+ `getGraph(thisArg, onEdge)` 
 
 Creates graph structure out of the family structure.
 
  Returns: `graph` - returns graph structure of the family.
 
+| Param | Type | Default | Description | 
+| --- | --- | --- | --- | 
+ | `thisArg` | Object | `` | The callback function invocation context | 
+ | `onEdge` | onFamilyEdgeCallback | `` | A callback function to call for every new edge added to the final graph | 
+**Callbacks**
+
+ `onFamilyEdgeCallback(from, to)` 
+
+Callback for getting default edge value
+
+ Returns: `object` - returns new edge object.
+
+| Param | Type | Default | Description | 
+| --- | --- | --- | --- | 
+ | `from` | string | `` | From node id | 
+ | `to` | string | `` | The node | 
 
  `getPlanarFamily(treeLevels)` 
 
@@ -189,7 +205,7 @@ Returns true if structure has nodes.
 
  `loop(thisArg, onItem)` 
 
-Loops through nodes of family struture
+Loops through nodes of family structure
 
 | Param | Type | Default | Description | 
 | --- | --- | --- | --- | 
@@ -210,7 +226,7 @@ Callback for iterating family nodes
 
  `loopChildren(thisArg, nodeid, onItem)` 
 
-Loops through child nodes of family struture level by level
+Loops through child nodes of family structure level by level
 
 | Param | Type | Default | Description | 
 | --- | --- | --- | --- | 
@@ -233,7 +249,7 @@ Callback for iterating family nodes level by level
 
  `loopLevels(thisArg, parentAligned, onItem)` 
 
-Loops through nodes of family struture level by level. This function aligns nodes top or bottom.
+Loops through nodes of family structure level by level. This function aligns nodes top or bottom.
 
 | Param | Type | Default | Description | 
 | --- | --- | --- | --- | 
@@ -256,7 +272,7 @@ Callback for iterating family nodes level by level
 
  `loopNeighbours(thisArg, itemid, onItem)` 
 
-Loops through the node neighbours of the family struture level by level
+Loops through the node neighbours of the family structure level by level
 
 | Param | Type | Default | Description | 
 | --- | --- | --- | --- | 
@@ -279,7 +295,7 @@ Callback for iterating family node neighbours level by level
 
  `loopParents(thisArg, nodeid, onItem)` 
 
-Loops through parent nodes of family struture level by level
+Loops through parent nodes of family structure level by level
 
 | Param | Type | Default | Description | 
 | --- | --- | --- | --- | 
@@ -323,7 +339,7 @@ Callback for iterating family nodes
 
  `loopTopo(thisArg, onItem)` 
 
-Loops through topologically sorted nodes of family struture
+Loops through topologically sorted nodes of family structure
 
 | Param | Type | Default | Description | 
 | --- | --- | --- | --- | 
@@ -345,7 +361,7 @@ Callback for iterating family nodes in topological sort order
 
  `loopTopoReversed(thisArg, onItem)` 
 
-Loops through reversed order topologically sorted nodes of family struture
+Loops through reversed order topologically sorted nodes of family structure
 
 | Param | Type | Default | Description | 
 | --- | --- | --- | --- | 
@@ -391,6 +407,17 @@ Callback function for cretion of new family nodes
  Returns: `object` - returns new family node.
 
 
+ `removeChildRelation(parentid, childid)` 
+
+Removes child relation
+
+ Returns: `true` - if relation was broken
+
+| Param | Type | Default | Description | 
+| --- | --- | --- | --- | 
+ | `parentid` | string | `` | The parent node id | 
+ | `childid` | string | `` | The child node id | 
+
  `removeNode(nodeid)` 
 
 Removes node
@@ -401,14 +428,14 @@ Removes node
 
  `removeRelation(fromid, toid)` 
 
-Remove parent child relation
+Removes first available parent child or child parent relation
 
  Returns: `true` - if relation was broken
 
 | Param | Type | Default | Description | 
 | --- | --- | --- | --- | 
- | `fromid` | string | `` | The parent node id | 
- | `toid` | string | `` | The child node id | 
+ | `fromid` | string | `` | From node id | 
+ | `toid` | string | `` | To node id | 
 
  `validate(info)` 
 
@@ -469,11 +496,6 @@ Creates Fibonacci Heap structure
 
 ### Functions
 
- `Result(node)` 
-
-undefined
-
-
  `add(key, priority, item)` 
 
 Adds a new item into the heap
@@ -558,6 +580,64 @@ Adds edge to the graph
  | `to` | string | `` | The id of the end node | 
  | `edge` | object | `` | The edge contextual object | 
 
+ `dfsLoop(thisArg, startNode, onEdge, onNode)` 
+
+Depth first search loop
+
+| Param | Type | Default | Description | 
+| --- | --- | --- | --- | 
+ | `thisArg` | object | `` | The callback function invocation context | 
+ | `startNode` | string | `` | The start node id | 
+ | `onEdge` | onPathEdgeCallback | `` | A callback function to call for every edge of the graph | 
+ | `onNode` | onNodeCallback | `` | A callback function to be called for every neighbouring node | 
+**Callbacks**
+
+ `onPathEdgeCallback(from, to, edge)` 
+
+Callback for iterating path edges
+
+ Returns: `boolean` - returns true if edge is usable
+
+| Param | Type | Default | Description | 
+| --- | --- | --- | --- | 
+ | `from` | string | `` | The from node id | 
+ | `to` | string | `` | The to node id | 
+ | `edge` | Object | `` | The edge's context object | 
+
+ `onNodeCallback(to)` 
+
+Callback function for iterating graphs nodes
+
+ Returns: `boolean` - returns true to break loop
+
+| Param | Type | Default | Description | 
+| --- | --- | --- | --- | 
+ | `to` | string | `` | The next neighbouring node id | 
+
+ `dfsPath(thisArg, startNode, endNode, onEdge)` 
+
+Search any path from node to node using depth first search
+
+| Param | Type | Default | Description | 
+| --- | --- | --- | --- | 
+ | `thisArg` | object | `` | The callback function invocation context | 
+ | `startNode` | string | `` | The start node id | 
+ | `endNode` | string | `` | The end node id. | 
+ | `onEdge` | onPathEdgeCallback | `` | A callback function to call for every edge of the node | 
+**Callbacks**
+
+ `onPathEdgeCallback(from, to, edge)` 
+
+Callback for iterating path edges
+
+ Returns: `boolean` - returns true if edge is usable
+
+| Param | Type | Default | Description | 
+| --- | --- | --- | --- | 
+ | `from` | string | `` | The from node id | 
+ | `to` | string | `` | The to node id | 
+ | `edge` | Object | `` | The edge's context object | 
+
  `edge(from, to)` 
 
 Returns edge context object
@@ -569,6 +649,29 @@ Returns edge context object
  | `from` | string | `` | The edge's from node id | 
  | `to` | string | `` | The edge's to node id | 
 
+ `getLevelGraph(thisArg, startNode, onEdge)` 
+
+Get Level Graph starting with `startNode`
+
+| Param | Type | Default | Description | 
+| --- | --- | --- | --- | 
+ | `thisArg` | object | `` | The callback function invocation context | 
+ | `startNode` | string | `` | The start node id | 
+ | `onEdge` | onPathEdgeCallback | `` | A callback function to call for every edge of the graph | 
+**Callbacks**
+
+ `onPathEdgeCallback(from, to, edge)` 
+
+Callback for iterating path edges
+
+ Returns: `boolean` - returns true if edge is usable
+
+| Param | Type | Default | Description | 
+| --- | --- | --- | --- | 
+ | `from` | string | `` | The from node id | 
+ | `to` | string | `` | The to node id | 
+ | `edge` | Object | `` | The edge's context object | 
+
  `getMinimumWeightGrowthSequence(thisArg, startNode, onEdgeWeight, onItem)` 
 
 Get minimum weight graph growth sequence. The sequence of the traversing order of the graph nodes.
@@ -597,6 +700,8 @@ Callback for finding edge weight
 
 Callback function for iterating graphs nodes
 
+ Returns: `boolean` - returns true to break loop
+
 | Param | Type | Default | Description | 
 | --- | --- | --- | --- | 
  | `to` | string | `` | The next neighbouring node id | 
@@ -611,7 +716,6 @@ Get shortest path between two nodes in graph. The start and the end nodes are su
  | `startNode` | string | `` | The start node id | 
  | `endNodes` | string[] | `` | The array of end node ids. | 
  | `getWeightFunc` | getGraphEdgeWeightCallback | `` | Callback function to get weight of an edge. | 
- | `onItem` | onNodeCallback | `` | A callback function to be called for every node of the growth sequence | 
  | `onPathFound` | onPathFoundCallback | `` | A callback function to be called for every end node with the optimal connection path | 
 **Callbacks**
 
@@ -627,14 +731,6 @@ Callback for finding edge weight
  | `fromItem` | string | `` | The edge's start node id | 
  | `toItem` | string | `` | The edge's end node id | 
 
- `onNodeCallback(to)` 
-
-Callback function for iterating graphs nodes
-
-| Param | Type | Default | Description | 
-| --- | --- | --- | --- | 
- | `to` | string | `` | The next neighbouring node id | 
-
  `onPathFoundCallback(path, to)` 
 
 Callback for returning optimal connection path for every end node.
@@ -695,6 +791,8 @@ Callback for finding edge weight
 
 Callback function for iterating graphs nodes
 
+ Returns: `boolean` - returns true to break loop
+
 | Param | Type | Default | Description | 
 | --- | --- | --- | --- | 
  | `to` | string | `` | The next neighbouring node id | 
@@ -744,6 +842,8 @@ Loop nodes of the graph
 
 Callback function for iterating graphs nodes
 
+ Returns: `boolean` - returns true to break loop
+
 | Param | Type | Default | Description | 
 | --- | --- | --- | --- | 
  | `to` | string | `` | The next neighbouring node id | 
@@ -1389,7 +1489,7 @@ Inserts bundle node into the tree structure. The new budnle node becomes only ch
 
  `loop(thisArg, onItem)` 
 
-Loops through nodes of tree struture
+Loops through nodes of tree structure
 
 | Param | Type | Default | Description | 
 | --- | --- | --- | --- | 
@@ -1505,7 +1605,7 @@ Callback for iterating nodes in euler walk order
 
  `loopLevels(thisArg, arg0, arg1)` 
 
-Loops through child nodes of the tree struture level by level
+Loops through child nodes of the tree structure level by level
 
 | Param | Type | Default | Description | 
 | --- | --- | --- | --- | 
@@ -1528,7 +1628,7 @@ Callback for iterating the tree nodes level by level
 
  `loopNeighbours(thisArg, itemid, distance, onItem)` 
 
-Loops through the node neighbours of the tree struture level by level
+Loops through the node neighbours of the tree structure level by level
 
 | Param | Type | Default | Description | 
 | --- | --- | --- | --- | 
@@ -1853,7 +1953,7 @@ Returns element's start level index in the structure. Element may occupy multipl
 
  `hasItem(itemid)` 
 
-Checks if struture contains element
+Checks if structure contains element
 
  Returns: `boolean` - returns true if structure contains given element id
 
@@ -1863,7 +1963,7 @@ Checks if struture contains element
 
  `hasLevel(levelIndex)` 
 
-Checks if struture contains level
+Checks if structure contains level
 
  Returns: `boolean` - returns true if structure contains given level index
 

apireference/enums.md

@@ -160,6 +160,16 @@ Line style of connection lines.
  | `Dotted` | number | `1` | Dotted | 
  | `Solid` | number | `0` | Solid | 
 
+## <a name="primitives.common.LoopsLayoutMode" id="primitives.common.LoopsLayoutMode">LoopsLayoutMode</a>
+Loops layout mode. Configuration may contain loop references between items, so control tries to find layout minimizing number of loops between levels, so majority of references ideally should go in one direction. This option disables optimization and forces items levels order to match their order in `items` collection. For example if you have two nodes `A` and `B` referencing each other as a parent, then it is not defined which one is going to be on the top of the diagram. Set this option to `KeepItemsOrder`, if you need the first item in your collection to be on the top, otherwise control will optimize loops layout in order to minimize number of loops in diagram.
+
+ `primitives.common.LoopsLayoutMode` 
+
+| Name | Type | Value | Description | 
+| --- | --- | --- | --- | 
+ | `KeepItemsOrder` | number | `1` | Keeps order of items on levels, the same as in `items` collection property. | 
+ | `Optimized` | number | `0` | Optimized. Control searches for layout producing minimal number of feedback loops in the diagram. | 
+
 ## <a name="primitives.common.NavigationMode" id="primitives.common.NavigationMode">NavigationMode</a>
 Interactivity mode. Control implements standard behaivour of classic desktop UI controls. It supports single selected node - cursor. It supports on mouse over node visual feedback - highlight. It supports selection of group of nodes - selected items. All that functionality can be disabled depending on your application requirements.
 

apireference/famdiagram.md

@@ -40,6 +40,7 @@ Family Chart configuration object. Use this object as a reference for available
  | `enableMatrixLayout` | boolean | `false` | This option enables automatic layout of nodes sharing the same set of parents and children in form of matrix. | 
  | `groupByType` | GroupByType | `2` | This property sets loose nodes alignment between rows. Nodes can be placed close towards parents or children. | 
  | `hideGrandParentsConnectors` | boolean | `false` | Set this property to enable hiding of direct connectors to grand parents. It helps to reduce diagrams connectors layout complexity. | 
+ | `loopsLayoutMode` | LoopsLayoutMode | `primitives.common.LoopsLayoutMode.Optimized` | Loops layout mode. Configuration may contain loop references between items, so control tries to find layout minimizing number of loops between levels, so majority of references ideally should go in one direction. This option disables optimization and forces items levels order to match their order in `items` collection. For example if you have two nodes `A` and `B` referencing each other as a parent, then it is not defined which one is going to be on the top of the diagram. Set this option to `KeepItemsOrder`, if you need the first item in your collection to be on the top, otherwise control will optimize loops layout in order to minimize number of loops in diagram. | 
  | `maximumColumnsInMatrix` | number | `6` | Sets maximum number of columns in the matrix formation. The matrix formation stays squared as long as total number of columns does not exceed this property value. In order to shape nodes into matrix formation they should share the same set of parents and children. See `enableMatrixLayout` property. | 
  | `minimalVisibility` | Visibility | `2` | Minimal nodes visibility in the diagram. If auto fit of the diagram into current page size is enabled, then this option controls minimum allowed size of the diagram nodes. | 
  | `minimumMatrixSize` | number | `4` | Sets Minimum number of nodes needed to be shaped into matrix formtion. In order to shape nodes in form of matrix they should share the same set of parents and children. See `enableMatrixLayout` property. | 

apireference/functions.md

@@ -109,6 +109,16 @@ Callback function to iterate over pairs of crosssing rectangles
  | `rect1` | Rect | `` | First rectangle | 
  | `rect2` | Rect | `` | Second rectangle | 
 
+## <a name="primitives.common.getFamilyLoops" id="primitives.common.getFamilyLoops">getFamilyLoops</a>
+
+This function finds [optimal collection of feedback edges](https://en.wikipedia.org/wiki/Feedback_arc_set) needed to be cut in order to eliminate loops in family structure.
+
+ Returns: `Edge[]` - returns optimal collection of feedback loops
+
+| Param | Type | Default | Description | 
+| --- | --- | --- | --- | 
+ | `family` | Family | `` | Family structure | 
+
 ## <a name="primitives.common.getGreen" id="primitives.common.getGreen">getGreen</a>
 
 Gets green value of HEX color string.