Added option hierarchical.layout.userControlsFreeAxis

Author: softwareCobbler

docs/network/layout.html

@@ -66,7 +66,8 @@ <h3>Options</h3>
       edgeMinimization: true,
       parentCentralization: true,
       direction: 'UD',        // UD, DU, LR, RL
-      sortMethod: 'hubsize'   // hubsize, directed
+      sortMethod: 'hubsize',   // hubsize, directed
+      userControlsFreeAxis: false
     }
   }
 }
@@ -103,6 +104,20 @@ <h3>Options</h3>
         <tr parent="hierarchical" class="hidden"><td class="indent">hierarchical.sortMethod</td><td>String</td><td><code>'hubsize'</code></td>  <td>The algorithm used to ascertain the levels of the nodes based on the data. The possible options are: <code>hubsize, directed</code>. <br><br>
             Hubsize takes the nodes with the most edges and puts them at the top. From that the rest of the hierarchy is evaluated. <br><br>
             Directed adheres to the to and from data of the edges. A --> B so B is a level lower than A.</td></tr>
+        <tr parent="hierarchical" class="hidden">
+                <td class="indent">hierarchical.userControlsFreeAxis</td>
+                <td>Boolean</td>
+                <td><code>false</code></td>
+                <td>Whether or not the value specified by a node's <code>Dataset</code> <code>x</code> or <code>y</code> values will affect a node's layout along its "free" axis.<br><br>
+                    If the hierarchical layout <code>direction</code> is either <code>"DU"</code> or <code>"UD"</code>, vis.js will layout the node using the Node's <code>x</code> property,
+                    or if <code>direction</code>is either <code>"LR"</code> or <code>"RL"</code>, vis.js will use the node's <code>y</code> property.<br><br>
+                    If the property vis wants to use (e.g., the <code>x</code> or <code>y</code> property on the node within the target <code>Dataset</code>)
+                    is undefined, the default behavior is invoked, as though this option were set to <code>false</code>. This provides the ability to initally utilize Vis's default layout,
+                    then later call <code>Network.storePositions()</code> and have the hierarchical layout engine respect the retreived values.<br><br>
+                    This option is helpful because updating a hierarchically layed-out graph will trigger a redraw, and without this option, if a node has been moved along its free axis,
+                    it will be returned to its default position.<br><br>
+                    This option is useful with physics disabled.</td>
+        </tr>
     </table>
 
 </div>

lib/network/modules/LayoutEngine.js

@@ -743,11 +743,18 @@ class LayoutEngine {
             this._determineLevelsCustomCallback();
           }
         }
-
+        
+        //
+        // to be iterated over later, in the userControlsFreeAxis option section
+        // we iterate over nodeIds once to call ensureLevel, so we might as well
+        // capture them now
+        //
+        let nodeIds = [];
 
         // fallback for cases where there are nodes but no edges
         for (let nodeId in this.body.nodes) {
           if (this.body.nodes.hasOwnProperty(nodeId)) {
+            nodeIds.push(nodeId);
             this.hierarchical.ensureLevel(nodeId);
           }
         }
@@ -765,6 +772,33 @@ class LayoutEngine {
 
         // shift to center so gravity does not have to do much
         this._shiftToCenter();
+
+        //
+        // if option hierarchical.userControlsFreeAxis is set (to true)
+        // we will attempt to set each node's free axis position based on Dataset value
+        // if the node's free axis position is undefined, we skip it and keep the original LayoutEngine-generated value
+        //
+        // the free axis in direction DU/UD is x
+        // the free axis in direction LR/RL is y
+        //
+        if (this.options.hierarchical.userControlsFreeAxis) {
+          let direction = this.options.hierarchical.direction;
+          let dataSet = this.body.data.nodes.getDataSet();
+          let freeAxis = "";
+           if (direction === "UD" || direction === "DU") {
+            freeAxis = "x";
+          }
+          else { // direction === "LR" || direction == "RL", any other values are caught as errors earlier in the program
+            freeAxis = "y";
+          }
+           for (let nodeId of nodeIds) {
+            let targetPosition = dataSet._data[nodeId][freeAxis];
+            if (targetPosition !== undefined) {
+                this.body.nodes[nodeId][freeAxis] = targetPosition;
+              }
+          }
+        }
+        
       }
     }
   }

lib/network/options.js

@@ -183,6 +183,7 @@ let allOptions = {
       parentCentralization: { boolean: bool },
       direction: { string: ['UD', 'DU', 'LR', 'RL'] },   // UD, DU, LR, RL
       sortMethod: { string: ['hubsize', 'directed'] }, // hubsize, directed
+      userControlsFreeAxis: { boolean: bool },
       __type__: { object, boolean: bool }
     },
     __type__: { object }
@@ -553,7 +554,8 @@ let configureOptions = {
       edgeMinimization: true,
       parentCentralization: true,
       direction: ['UD', 'DU', 'LR', 'RL'],   // UD, DU, LR, RL
-      sortMethod: ['hubsize', 'directed'] // hubsize, directed
+      sortMethod: ['hubsize', 'directed'], // hubsize, directed
+      userControlsFreeAxis: false
     }
   },
   interaction: {