Simplified Graph constructor

docs/graph.html

@@ -103,17 +103,17 @@
             {from: 2, to: 5}
         ];
 
-        // specify options
+        // create a graph
+        var container = document.getElementById('mygraph');
+        var data= {
+            nodes: nodes,
+            edges: edges,
+        };
         var options = {
             width: '400px',
             height: '400px'
         };
-
-        // create a graph
-        var graph = new vis.Graph(document.getElementById('mygraph'));
-
-        // draw the graph with the created data and options
-        graph.draw(nodes, edges, options);
+        var graph = new vis.Graph(container, data, options);
     </script>
 
     </body>
@@ -132,38 +132,41 @@
 </pre>
 
 
-The class name of the Graph is <code>vis.Graph</code>
-<pre class="prettyprint lang-js">var graph = new vis.Graph(container);</pre>
-
-After being loaded, the graph can be drawn via the function <code>draw()</code>,
-provided with data and options.
-<pre class="prettyprint lang-js">graph.draw(nodes, edges, packages, options);</pre>
-where <code>nodes</code>, <code>edges</code>, and <code>packages</code> are
-an <code>Array</code>, and <code>options</code> is a name-value map in the
-JSON format. Both <code>edges</code> and <code>packages</code> are optional.
-
-
+The class name of the Graph is <code>vis.Graph</code>.
+<pre class="prettyprint lang-js">var graph = new vis.Graph(container, data, options);</pre>
 
+The constructor accepts three parameters:
+<ul>
+    <li>
+        <code>container</code> is the DOM element in which to create the graph.
+    </li>
+    <li>
+        <code>data</code> is an Object containing properties <code>nodes</code> and
+        <code>edges</code>, which both contain an array with objects.
+        Optionally, data may contain an <code>options</code> object.
+        The parameter <code>data</code> is optional, data can also be set using
+        the method <code>setData</code>.
+    </li>
+    <li>
+        <code>options</code> is an optional Object containing a name-value map
+        with options. Options can also be set using the method
+        <code>setOptions</code>.
+    </li>
+</ul>
 
 <h2><a name="Data_Format"></a>Data Format</h2>
 <p>
-    Graph accepts the following data
+    The Graph draws nodes and edges, which are both an Array with objects.
+    This section describes the data format of nodes and edges.
 </p>
-<ul>
-    <li><b>Nodes</b>. An array which defines the nodes. Required.</li>
-    <li><b>Edges</b>. An array which defines edges between nodes. Optional.</li>
-    <li><b>Packages</b>. An array which defines static and/or interactive packages
-        moving between nodes. Required.</li>
-</ul>
 
 <h3>Nodes</h3>
 
 <p>
-    The node array is required for the graph visualization.
-
-    The array must contain at least a property <code>id</code>.
-    The array can have extra properties, used to define the type and style of
-    individual nodes.
+    Nodes typically have an <code>id</code> and <code>text</code>.
+    A node must contain at least a property <code>id</code>.
+    Nodes can have extra properties, used to define the type and style the
+    nodes.
 </p>
 
 <p>
@@ -181,7 +184,7 @@ var nodes = [
 
 
 <p>
-    The node properties are defined as:
+    Nodes support the following properties:
 </p>
 
 <table>
@@ -372,10 +375,10 @@ var nodes = [
 <h3>Edges</h3>
 
 <p>
-    The array with edges must at least contain properties <code>from</code> and
-    <code>to</code>.
-    The array can have extra properties, used to define the type and style of
-    individual edges.
+    Edges are connections between nodes.
+    An edge must at least contain properties <code>from</code> and
+    <code>to</code>, both referring to the <code>id</code> of a node.
+    Edges can have extra properties, used to define the type and style.
 </p>
 
 <p>
@@ -392,7 +395,7 @@ var edges= [
 </pre>
 
 <p>
-    The edge properties are defined as:
+    Edges support the following properties:
 </p>
 
 <table>
@@ -769,7 +772,7 @@ var packages = [
             containing with nodes and edges in the format of Graph.
             The returned object contains parameters <code>nodes</code>,
             <code>edges</code>, and <code>options</code>, which can be used
-            directly to draw a graph using <code>draw(nodes, edges, options)</code>.
+            directly to draw a graph using <code>setData(data)</code>.
         </td>
     </tr>
 </table>
@@ -779,15 +782,12 @@ Example usage:
 </p>
 
 <pre class="prettyprint lang-js">
-    // create a graph view
-    var graph = new vis.Graph(container);
-
     // parse data in DOT-notation
     var dot = 'digraph {1 -> 1 -> 2; 2 -> 3; 2 -- 4; 2 -> 1 }';
-    data = vis.Graph.util.DOTToGraph(dot);
+    var data = vis.Graph.util.DOTToGraph(dot);
 
-    // draw the data
-    graph.draw(data.nodes, data.edges, data.options);
+    // create a graph
+    var graph = new vis.Graph(container, data);
 </pre>
 
 
@@ -1219,7 +1219,7 @@ var nodes = [
 <h2><a name="Dynamic_Data"></a>Dynamic Data</h2>
 
 <p>
-    The Graph is normally rendered using the method <code>draw</code>.
+    The Graph is normally rendered using the method <code>setData</code>.
     The graph can handle dynamic data in two ways:
 </p>
 <ul>
@@ -1399,12 +1399,11 @@ packageTable.addRow([7,  1,    2, 'delete', undefined,          undefined, new D
     </tr>
 
     <tr>
-        <td>draw(nodes, edges, packages, options)</td>
+        <td>setData(data)</td>
         <td>none</td>
-        <td>Loads data, sets the provided options, and draws the graph.
-            Parameters nodes, edges, and packages are an Array,
-            and options is a name-value map in the JSON format.
-            Both edges and packages are optional and can be left undefined.
+        <td>Loads data. Parameter <code>data</code> is an object containing
+            nodes, edges, and options. Parameters nodes, edges are an Array.
+            Options is a name-value map and is optional.
         </td>
     </tr>
 
@@ -1420,8 +1419,7 @@ packageTable.addRow([7,  1,    2, 'delete', undefined,          undefined, new D
     <tr>
         <td>redraw()</td>
         <td>none</td>
-        <td>Redraw the graph. Useful after the camera position is changed externally,
-            when data is changed, or when the layout of the webpage changed.</td>
+        <td>Redraw the graph. Useful when the layout of the webpage changed.</td>
     </tr>
 
     <tr>
@@ -1515,7 +1513,7 @@ vis.events.addListener(graph, 'select', onselect);
         <td>ready</td>
         <td>The graph is loaded and ready for external method calls.
             If you want to interact with the graph, and call methods after you draw it,
-            you should set up a listener for this event before you call the draw method,
+            you should set up a listener for this event before you call the setData method,
             and call them only after the event was fired.</td>
         <td>none</td>
     </tr>

examples/graph/01_basic_usage.html

@@ -28,17 +28,17 @@
         {from: 2, to: 5}
     ];
 
-    // specify options
+    // create a graph
+    var container = document.getElementById('mygraph');
+    var data = {
+        nodes: nodes,
+        edges: edges
+    };
     var options = {
         width: '400px',
         height: '400px'
     };
-
-    // create a graph
-    var graph = new vis.Graph(document.getElementById('mygraph'));
-
-    // draw the graph with the created data and options
-    graph.draw(nodes, edges, options);
+    var graph = new vis.Graph(container, data, options);
 </script>
 
 </body>

examples/graph/02_random_nodes.html

@@ -63,7 +63,12 @@
                 }
             }
 
-            // specify options
+            // create a graph
+            var container = document.getElementById('mygraph');
+            var data = {
+                nodes: nodes,
+                edges: edges
+            };
             var options = {
                 width: '600px',
                 height: '600px',
@@ -72,12 +77,7 @@
                 },
                 stabilize: false
             };
-
-            // create a graph
-            graph = new vis.Graph(document.getElementById('mygraph'));
-
-            // draw data
-            graph.draw(nodes, edges, options);
+            graph = new vis.Graph(container, data, options);
 
             // add event listeners
             vis.events.addListener(graph, 'select', function(params) {

examples/graph/03_images.html

@@ -54,18 +54,18 @@
                 edges.push({from: 3, to: i, length: LENGTH_SUB});
             }
 
-            // specify options
+            // create a graph
+            var container = document.getElementById('mygraph');
+            var data = {
+                nodes: nodes,
+                edges: edges
+            };
             var options = {
                 width: '600px',
                 height: '600px',
                 stabilize: false   // stabilize positions before displaying
             };
-
-            // create a graph
-            graph = new vis.Graph(document.getElementById('mygraph'));
-
-            // draw data
-            graph.draw(nodes, edges, options);
+            graph = new vis.Graph(container, data, options);
         }
     </script>
 </head>

examples/graph/04_shapes.html

@@ -49,18 +49,18 @@
                 }
             }
 
-            // specify options
+            // create a graph
+            var container = document.getElementById('mygraph');
+            var data = {
+                nodes: nodes,
+                edges: edges
+            };
             var options = {
                 width:  '780px',
                 height: '600px',
                 stabilize: false
             };
-
-            // Instantiate our graph object.
-            graph = new vis.Graph(document.getElementById('mygraph'));
-
-            // Draw our graph with the created data and options
-            graph.draw(nodes, edges, options);
+            graph = new vis.Graph(container, data, options);
         }
     </script>
 </head>

examples/graph/05_social_network.html

@@ -49,7 +49,12 @@
                 {from: 2,   to: 7,  value: 4,   color: color}
             ];
 
-            // specify options
+            // create a graph
+            var container = document.getElementById('mygraph');
+            var data = {
+                nodes: nodes,
+                edges: edges
+            };
             var options = {
                 width:  '600px',
                 height: '600px',
@@ -57,12 +62,7 @@
                     fill: '#F3F3F3'
                 }
             };
-
-            // create graph
-            graph = new vis.Graph(document.getElementById('mygraph'));
-
-            // draw data
-            graph.draw(nodes, edges, options);
+            graph = new vis.Graph(container, data, options);
         }
     </script>
 </head>

examples/graph/06_groups.html

@@ -117,7 +117,12 @@
                 group++;
             }
 
-            // specify options
+            // create a graph
+            var container = document.getElementById('mygraph');
+            var data = {
+                nodes: nodes,
+                edges: edges
+            };
             var options = {
                 width:  '600px',
                 height: '600px',
@@ -129,12 +134,7 @@
                     length: 50
                 }
             };
-
-            // Instantiate our graph object.
-            graph = new vis.Graph(document.getElementById('mygraph'));
-
-            // Draw our graph with the created data and options
-            graph.draw(nodes, edges, options);
+            graph = new vis.Graph(container, data, options);
         }
     </script>
 </head>

examples/graph/08_selections.html

@@ -29,17 +29,17 @@
         {from: 2, to: 5}
     ];
 
-    // specify options
+    // create a graph
+    var container = document.getElementById('mygraph');
+    var data = {
+        nodes: nodes,
+        edges: edges
+    };
     var options = {
         width: '400px',
         height: '400px'
     };
-
-    // create a graph
-    var graph = new vis.Graph(document.getElementById('mygraph'));
-
-    // draw the graph with the created data and options
-    graph.draw(nodes, edges, options);
+    graph = new vis.Graph(container, data, options);
 
     // add event listener
     function onSelect() {

examples/graph/16_scalable_images.html

@@ -52,7 +52,12 @@
                 {from: 2, to: 7, value: 4, title: '4 emails per week'}
             ];
 
-            // specify options
+            // create a graph
+            var container = document.getElementById('mygraph');
+            var data = {
+                nodes: nodes,
+                edges: edges
+            };
             var options = {
                 width:  '600px',
                 height: '600px',
@@ -64,12 +69,7 @@
                     color: 'lightgray'
                 }
             };
-
-            // Instantiate our graph object.
-            graph = new vis.Graph(document.getElementById('mygraph'));
-
-            // Draw our graph with the created data and options
-            graph.draw(nodes, edges, options);
+            graph = new vis.Graph(container, data, options);
         }
     </script>
 </head>

examples/graph/19_dot_language.html

@@ -6,7 +6,7 @@
     <script type="text/javascript" src="../../vis.js"></script>
 
     <style type="text/css">
-        html, body, #graph {
+        html, body, #mygraph {
             width: 100%;
             height: 100%;
             padding: 0;
@@ -15,18 +15,16 @@
     </style>
 </head>
 <body>
-<div id="graph"></div>
+<div id="mygraph"></div>
 
 <script type="text/javascript">
-    // create a network view
-    var graph = new vis.Graph(document.getElementById('graph'));
-
     // parse data in DOT-notation
     var dot = 'digraph {node[shape=circle]; 1 -> 1 -> 2; 2 -> 3; 2 -- 4; 2 -> 1 }';
     var data = vis.Graph.util.DOTToGraph(dot);
 
-    // draw the data
-    graph.draw(data.nodes, data.edges, data.options);
+    // create a graph
+    var container = document.getElementById('mygraph');
+    var graph = new vis.Graph(container, data);
 
     // resize the network when window resizes
     window.onresize = function () {

examples/graph/20_dot_language_playground.html

@@ -33,7 +33,7 @@
             border: 1px solid #d3d3d3;
         }
 
-        #graph {
+        #mygraph {
             float: left;
             width: 100%;
             height: 100%;
@@ -69,7 +69,7 @@
             <textarea id="data"></textarea>
         </td>
         <td>
-            <div id="graph"></div>
+            <div id="mygraph"></div>
         </td>
     </tr>
 </table>
@@ -90,22 +90,18 @@
     // parse and draw the data
     function draw () {
         try {
-            // create a graph
-            graph = new vis.Graph(document.getElementById('graph'));
-
             txtError.innerHTML = '';
 
             // parse the data from DOT-notation
             data = vis.Graph.util.DOTToGraph(txtData.value);
 
-            // draw the data in the graph view
-            var options = data.options;
-            options.width = '100%';
-            //options.links.length = options.links.length;
-            options.height = '100%';
-            //options.nodes.radius = 20;
-            //options.links.width = 2;
-            graph.draw(data.nodes, data.edges, options);
+            // create a graph
+            var container = document.getElementById('mygraph');
+            var options = {
+                width: '100%',
+                height: '100%'
+            };
+            graph = new vis.Graph(container, data, options);
         }
         catch (err) {
             // set the cursor at the position where the error occurred

src/graph/graph.js

@@ -3,8 +3,12 @@
  * Create a graph visualization connecting nodes via edges.
  * @param {Element} container   The DOM element in which the Graph will
  *                                  be created. Normally a div element.
+ * @param {Object} data         An object containing parameters
+ *                              {Array} nodes
+ *                              {Array} edges
+ * @param {Object} options      Options
  */
-function Graph (container) {
+function Graph (container, data, options) {
     // create variables and set default values
     this.containerElement = container;
     this.width = "100%";
@@ -79,46 +83,58 @@ function Graph (container) {
 
     // create a frame and canvas
     this._create();
-};
+
+    // apply options
+    this.setOptions(options);
+
+    // draw data
+    this.setData(data);
+}
 
 /**
  * Main drawing logic. This is the function that needs to be called
  * in the html page, to draw the Network.
  *
  * A data table with the events must be provided, and an options table.
- * @param {Array} [nodes]     The data containing the nodes.
- * @param {Array} [edges]     The data containing the edges.
- * @param {Array} [packages]  The data containing the packages
- * @param {Object} options                                     A name/value map containing settings
- */
-Graph.prototype.draw = function(nodes, edges, packages, options) {
-    var nodesTable, edgesTable, packagesTable;
-    // correctly read the parameters. edges and packages are optional.
-    if (options != undefined) {
-        nodesTable = nodes;
-        edgesTable = edges;
-        packagesTable = packages;
-    }
-    else if (packages != undefined) {
-        nodesTable = nodes;
-        edgesTable = edges;
-        packagesTable = undefined;
-        options = packages;
-    }
-    else if (edges != undefined) {
-        nodesTable = nodes;
-        edgesTable = undefined;
-        packagesTable = undefined;
-        options = edges;
-    }
-    else if (nodes != undefined) {
-        nodesTable = undefined;
-        edgesTable = undefined;
-        packagesTable = undefined;
-        options = nodes;
-    }
-
-    if (options != undefined) {
+ * @param {Object} data    Object containing parameters:
+ *                         {Array} nodes     Array with nodes
+ *                         {Array} edges     Array with edges
+ *                         {Options} [options] Object with options
+ */
+Graph.prototype.setData = function(data) {
+    if (data.options) {
+        this.setOptions(data.options);
+    }
+
+    // set all data
+    this.hasTimestamps = false;
+    this.setNodes(data.nodes);
+    this.setEdges(data.edges);
+    this.setPackages(data.packages);
+
+    this._reposition(); // TODO: bad solution
+    if (this.stabilize) {
+        this._doStabilize();
+    }
+    this.start();
+
+    // create an onload callback method for the images
+    var network = this;
+    var callback = function () {
+        network._redraw();
+    };
+    this.images.setOnloadCallback(callback);
+
+    // fire the ready event
+    this.trigger('ready');
+};
+
+/**
+ * Set options
+ * @param {Object} options
+ */
+Graph.prototype.setOptions = function (options) {
+    if (options) {
         // retrieve parameter values
         if (options.width != undefined)           {this.width = options.width;}
         if (options.height != undefined)          {this.height = options.height;}
@@ -189,35 +205,13 @@ Graph.prototype.draw = function(nodes, edges, packages, options) {
                 }
             }
         }
-    }
 
-    this._setBackgroundColor(options.backgroundColor);
+        this._setBackgroundColor(options.backgroundColor);
+    }
 
     this._setSize(this.width, this.height);
     this._setTranslation(0, 0);
     this._setScale(1.0);
-
-    // set all data
-    this.hasTimestamps = false;
-    this.setNodes(nodesTable);
-    this.setEdges(edgesTable);
-    this.setPackages(packagesTable);
-
-    this._reposition(); // TODO: bad solution
-    if (this.stabilize) {
-        this._doStabilize();
-    }
-    this.start();
-
-    // create an onload callback method for the images
-    var network = this;
-    var callback = function () {
-        network._redraw();
-    };
-    this.images.setOnloadCallback(callback);
-
-    // fire the ready event
-    this.trigger('ready');
 };
 
 /**

vis.js

@@ -6810,8 +6810,12 @@ Timeline.prototype.getItemRange = function getItemRange() {
  * Create a graph visualization connecting nodes via edges.
  * @param {Element} container   The DOM element in which the Graph will
  *                                  be created. Normally a div element.
+ * @param {Object} data         An object containing parameters
+ *                              {Array} nodes
+ *                              {Array} edges
+ * @param {Object} options      Options
  */
-function Graph (container) {
+function Graph (container, data, options) {
     // create variables and set default values
     this.containerElement = container;
     this.width = "100%";
@@ -6886,46 +6890,58 @@ function Graph (container) {
 
     // create a frame and canvas
     this._create();
-};
+
+    // apply options
+    this.setOptions(options);
+
+    // draw data
+    this.setData(data);
+}
 
 /**
  * Main drawing logic. This is the function that needs to be called
  * in the html page, to draw the Network.
  *
  * A data table with the events must be provided, and an options table.
- * @param {Array} [nodes]     The data containing the nodes.
- * @param {Array} [edges]     The data containing the edges.
- * @param {Array} [packages]  The data containing the packages
- * @param {Object} options                                     A name/value map containing settings
- */
-Graph.prototype.draw = function(nodes, edges, packages, options) {
-    var nodesTable, edgesTable, packagesTable;
-    // correctly read the parameters. edges and packages are optional.
-    if (options != undefined) {
-        nodesTable = nodes;
-        edgesTable = edges;
-        packagesTable = packages;
-    }
-    else if (packages != undefined) {
-        nodesTable = nodes;
-        edgesTable = edges;
-        packagesTable = undefined;
-        options = packages;
-    }
-    else if (edges != undefined) {
-        nodesTable = nodes;
-        edgesTable = undefined;
-        packagesTable = undefined;
-        options = edges;
-    }
-    else if (nodes != undefined) {
-        nodesTable = undefined;
-        edgesTable = undefined;
-        packagesTable = undefined;
-        options = nodes;
-    }
-
-    if (options != undefined) {
+ * @param {Object} data    Object containing parameters:
+ *                         {Array} nodes     Array with nodes
+ *                         {Array} edges     Array with edges
+ *                         {Options} [options] Object with options
+ */
+Graph.prototype.setData = function(data) {
+    if (data.options) {
+        this.setOptions(data.options);
+    }
+
+    // set all data
+    this.hasTimestamps = false;
+    this.setNodes(data.nodes);
+    this.setEdges(data.edges);
+    this.setPackages(data.packages);
+
+    this._reposition(); // TODO: bad solution
+    if (this.stabilize) {
+        this._doStabilize();
+    }
+    this.start();
+
+    // create an onload callback method for the images
+    var network = this;
+    var callback = function () {
+        network._redraw();
+    };
+    this.images.setOnloadCallback(callback);
+
+    // fire the ready event
+    this.trigger('ready');
+};
+
+/**
+ * Set options
+ * @param {Object} options
+ */
+Graph.prototype.setOptions = function (options) {
+    if (options) {
         // retrieve parameter values
         if (options.width != undefined)           {this.width = options.width;}
         if (options.height != undefined)          {this.height = options.height;}
@@ -6996,35 +7012,13 @@ Graph.prototype.draw = function(nodes, edges, packages, options) {
                 }
             }
         }
-    }
 
-    this._setBackgroundColor(options.backgroundColor);
+        this._setBackgroundColor(options.backgroundColor);
+    }
 
     this._setSize(this.width, this.height);
     this._setTranslation(0, 0);
     this._setScale(1.0);
-
-    // set all data
-    this.hasTimestamps = false;
-    this.setNodes(nodesTable);
-    this.setEdges(edgesTable);
-    this.setPackages(packagesTable);
-
-    this._reposition(); // TODO: bad solution
-    if (this.stabilize) {
-        this._doStabilize();
-    }
-    this.start();
-
-    // create an onload callback method for the images
-    var network = this;
-    var callback = function () {
-        network._redraw();
-    };
-    this.images.setOnloadCallback(callback);
-
-    // fire the ready event
-    this.trigger('ready');
 };
 
 /**