You may be interested in Cytoscape.js, a newer HTML5-based JavaScript library with an updated API and new features.

Introduction

This tutorial guides you through the process of getting Cytoscape Web up and running within a HTML page. Once you have Cytoscape Web working, you can continue on in the tutorial to see how to interact with Cytoscape Web. Additionally, visual styles are presented as a more complex example of how to interact with Cytoscape Web.

Getting started

What you need

All the files you need are in the latest version of the Cytoscape Web distribution archive. Get the latest version of the archive, and extract the files.

When opening the examples as a local files in your browser, you may not be able to see Cytoscape Web. This is due to Flash security settings. Make sure to allow Flash to run from the local filesystem (file://*) in the security settings panel. You do not need to change the security settings if you deploy Cytoscape Web on a web server, such as Apache.

What to do

The best way to familiarise yourself with setting up Cytoscape Web is to go through an example.

It is important to note that Cytoscape Web does not load remote files for you. So if you have a graph file you want to load from a server, you must load the file into a string, either by hardcoding the graph into your code or loading the graph file via AJAX first. We recommend you take a look at jQuery. It makes Javascript really easy, especially AJAX.

Now, take a look at this example. It has everything needed to get Cytoscape Web up and running.

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html>
    
    <head>
        <title>Cytoscape Web example</title>
        
        <!-- JSON support for IE (needed to use JS API) -->
        <script type="text/javascript" src="/js/cytoscape_web/json2.min.js"></script>
        
        <!-- Flash embedding utility (needed to embed Cytoscape Web) -->
        <script type="text/javascript" src="/js/cytoscape_web/AC_OETags.min.js"></script>
        
        <!-- Cytoscape Web JS API (needed to reference org.cytoscapeweb.Visualization) -->
        <script type="text/javascript" src="/js/cytoscape_web/cytoscapeweb.min.js"></script>
        
        <script type="text/javascript">
            window.onload=function() {
                // id of Cytoscape Web container div
                var div_id = "cytoscapeweb";
                
                // you could also use other formats (e.g. GraphML) or grab the network data via AJAX
                var networ_json = {
                    data: {
                        nodes: [ { id: "1" }, { id: "2" } ],
                        edges: [ { id: "2to1", target: "1", source: "2" } ]
                    }
                };
                
                // initialization options
                var options = {
                    // where you have the Cytoscape Web SWF
                    swfPath: "/swf/CytoscapeWeb",
                    // where you have the Flash installer SWF
                    flashInstallerPath: "/swf/playerProductInstall"
                };
                
                // init and draw
                var vis = new org.cytoscapeweb.Visualization(div_id, options);
                vis.draw({ network: networ_json });
            };
        </script>
        
        <style>
            /* The Cytoscape Web container must have its dimensions set. */
            html, body { height: 100%; width: 100%; padding: 0; margin: 0; }
            #cytoscapeweb { width: 100%; height: 100%; }
        </style>
    </head>
    
    <body>
        <div id="cytoscapeweb">
            Cytoscape Web will replace the contents of this div with your graph.
        </div>
    </body>
    
</html>

The code above is embedded below. If you are following along, you can copy and paste the code above and adjust the script tag references to the path where you extracted Cytoscape Web. When loaded in your browser, the file you would have made would look just like the embedded code below.

Interacting with Cytoscape Web

Now that you are able to embed Cytoscape Web into a page, you can use the Javascript API to interact with it. You have already used the class representing the embedded visualisation in the first example. What remains is to interact with the visualisation once it has been drawn.

The main thing to keep in mind is that you can not interact with most of Cytoscape Web until the graph is drawn. Thus, you can interact with Cytoscape Web by using the ready callback function, which is called when Cytoscape Web is finished drawing the graph.

This example interacts with Cytoscape Web by getting attributes values that were set for the nodes and edges in the graph. This is achieved by registering with the addListener function for click events.

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html>
    
    <head>
        <title>Cytoscape Web example</title>
        
        <script type="text/javascript" src="/js/cytoscape_web/json2.min.js"></script>
        <script type="text/javascript" src="/js/cytoscape_web/AC_OETags.min.js"></script>
        <script type="text/javascript" src="/js/cytoscape_web/cytoscapeweb.min.js"></script>
        
        <script type="text/javascript">
            window.onload = function() {
                // id of Cytoscape Web container div
                var div_id = "cytoscapeweb";
                
                // create a network model object
                var network_json = {
                        // you need to specify a data schema for custom attributes!
                        dataSchema: {
                    		nodes: [ { name: "label", type: "string" },
                    		         { name: "foo", type: "string" }
           		         	],
							edges: [ { name: "label", type: "string" },
							         { name: "bar", type: "string" }
							]
                    	},
                    	// NOTE the custom attributes on nodes and edges
                        data: {
                            nodes: [ { id: "1", label: "1", foo: "Is this the real life?" },
                                     { id: "2", label: "2", foo: "Is this just fantasy?" }
                            ],
                            edges: [ { id: "2to1", target: "1", source: "2", label: "2 to 1", bar: "Caught in a landslide..." }
                            ]
                        }
                };
                
                // initialization options
                var options = {
                    swfPath: "/swf/CytoscapeWeb",
                    flashInstallerPath: "/swf/playerProductInstall"
                };
                
                var vis = new org.cytoscapeweb.Visualization(div_id, options);
                
                // callback when Cytoscape Web has finished drawing
                vis.ready(function() {
                
                    // add a listener for when nodes and edges are clicked
                    vis.addListener("click", "nodes", function(event) {
                        handle_click(event);
                    })
                    .addListener("click", "edges", function(event) {
                        handle_click(event);
                    });
                    
                    function handle_click(event) {
                         var target = event.target;
                         
                         clear();
                         print("event.group = " + event.group);
                         for (var i in target.data) {
                            var variable_name = i;
                            var variable_value = target.data[i];
                            print( "event.target.data." + variable_name + " = " + variable_value );
                         }
                    }
                    
                    function clear() {
                        document.getElementById("note").innerHTML = "";
                    }
                
                    function print(msg) {
                        document.getElementById("note").innerHTML += "<p>" + msg + "</p>";
                    }
                });

                // draw options
                var draw_options = {
                    // your data goes here
                    network: network_json,
                    // hide pan zoom
                    panZoomControlVisible: false 
                };
                
                vis.draw(draw_options);
            };
        </script>
        
        <style>
            * { margin: 0; padding: 0; font-family: Helvetica, Arial, Verdana, sans-serif; }
            html, body { height: 100%; width: 100%; padding: 0; margin: 0; }
            body { line-height: 1.5; color: #000000; font-size: 14px; }
            /* The Cytoscape Web container must have its dimensions set. */
            #cytoscapeweb { width: 100%; height: 50%; }
            #note { width: 100%; height: 50%; background-color: #f0f0f0; overflow: auto;  }
            p { padding: 0 0.5em; margin: 0; }
            p:first-child { padding-top: 0.5em; }
        </style>
    </head>
    
    <body>
        <div id="cytoscapeweb">
            Cytoscape Web will replace the contents of this div with your graph.
        </div>
        <div id="note">
            <p>Click nodes or edges.</p>
        </div>
    </body>
    
</html>

Now that you know how to initialise and interact with Cytoscape Web, you can look to the API reference to customise Cytoscape Web exactly to your liking. Have fun!

If you would like a bit more in the way of instruction, see the next section on how to set the visual style. The example there is a bit more complex, but it should give you the opportunity to become more familiar with the Cytoscape Web API.

Visual styles

Visual styles configure the way that the graph is visually displayed. You can create a visual style statically or programattically, by setting the visual style at initialisation or by using the visualStyle function.

This example changes the visual style of the graph from the previous examples.

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html>
    
    <head>
        <title>Cytoscape Web example</title>
        
        <script type="text/javascript" src="/js/cytoscape_web/json2.min.js"></script>
        <script type="text/javascript" src="/js/cytoscape_web/AC_OETags.min.js"></script>
        <script type="text/javascript" src="/js/cytoscape_web/cytoscapeweb.min.js"></script>
        
        <script type="text/javascript">
            window.onload = function() {
                // id of Cytoscape Web container div
                var div_id = "cytoscapeweb";
                
                // NOTE: - the attributes on nodes and edges
                //       - it also has directed edges, which will automatically display edge arrows
                var xml = '\
                <graphml>\
                  <key id="label" for="all" attr.name="label" attr.type="string"/>\
                  <key id="weight" for="node" attr.name="weight" attr.type="double"/>\
                  <graph edgedefault="directed">\
                    <node id="1">\
                        <data key="label">A</data>\
                        <data key="weight">2.0</data>\
                    </node>\
                    <node id="2">\
                        <data key="label">B</data>\
                        <data key="weight">1.5</data>\
                    </node>\
                    <node id="3">\
                        <data key="label">C</data>\
                        <data key="weight">1.0</data>\
                    </node>\
                    <edge source="1" target="2">\
                        <data key="label">A to B</data>\
                    </edge>\
                    <edge source="1" target="3">\
                        <data key="label">A to C</data>\
                    </edge>\
                  </graph>\
                </graphml>\
                ';
                
                function rand_color() {
                    function rand_channel() {
                        return Math.round( Math.random() * 255 );
                    }
                    
                    function hex_string(num) {
                        var ret = num.toString(16);
                        
                        if (ret.length < 2) {
                            return "0" + ret;
                        } else {
                            return ret;
                        }
                    }
                    
                    var r = rand_channel();
                    var g = rand_channel();
                    var b = rand_channel();
                    
                    return "#" + hex_string(r) + hex_string(g) + hex_string(b); 
                }
                
                // visual style we will use
                var visual_style = {
                    global: {
                        backgroundColor: "#ABCFD6"
                    },
                    nodes: {
                        shape: "OCTAGON",
                        borderWidth: 3,
                        borderColor: "#ffffff",
                        size: {
                            defaultValue: 25,
                            continuousMapper: { attrName: "weight", minValue: 25, maxValue: 75 }
                        },
                        color: {
                            discreteMapper: {
                                attrName: "id",
                                entries: [
                                    { attrValue: 1, value: "#0B94B1" },
                                    { attrValue: 2, value: "#9A0B0B" },
                                    { attrValue: 3, value: "#dddd00" }
                                ]
                            }
                        },
                        labelHorizontalAnchor: "center"
                    },
                    edges: {
                        width: 3,
                        color: "#0B94B1"
                    }
                };
                
                // initialization options
                var options = {
                    swfPath: "/swf/CytoscapeWeb",
                    flashInstallerPath: "/swf/playerProductInstall"
                };
                
                var vis = new org.cytoscapeweb.Visualization(div_id, options);
                
                vis.ready(function() {
                    // set the style programmatically
                    document.getElementById("color").onclick = function(){
                        visual_style.global.backgroundColor = rand_color();
                        vis.visualStyle(visual_style);
                    };
                });

                var draw_options = {
                    // your data goes here
                    network: xml,
                    
                    // show edge labels too
                    edgeLabelsVisible: true,
                    
                    // let's try another layout
                    layout: "Tree",
                    
                    // set the style at initialisation
                    visualStyle: visual_style,
                    
                    // hide pan zoom
                    panZoomControlVisible: false 
                };
                
                vis.draw(draw_options);
            };
        </script>
        
        <style>
            * { margin: 0; padding: 0; font-family: Helvetica, Arial, Verdana, sans-serif; }
            html, body { height: 100%; width: 100%; padding: 0; margin: 0; background-color: #f0f0f0; }
            body { line-height: 1.5; color: #000000; font-size: 14px; }
            /* The Cytoscape Web container must have its dimensions set. */
            #cytoscapeweb { width: 100%; height: 80%; }
            #note { width: 100%; text-align: center; padding-top: 1em; }
            .link { text-decoration: underline; color: #0b94b1; cursor: pointer; }
        </style>
    </head>
    
    <body>
        <div id="cytoscapeweb">
            Cytoscape Web will replace the contents of this div with your graph.
        </div>
        <div id="note">
            <span class="link" id="color">Color me surprised</span>
        </div>
    </body>
    
</html>

The style is set at initialisation. Additionally, clicking the link changes the visual style programattically by changing the background color to a randomly selected color for each click.

This example has used only a few visual properties for the sake of simplicity. However, there are many visual properties that exist in Cytoscape Web that can be used to control exactly how things are visually displayed. Take a look at the visualStyle function for more information.

Compound Nodes

With Cytoscape Web it is very easy to create compound nodes (i.e. nodes within nodes), and you can choose one of the folowing options:

  1. XGMML: This XML format supports subgraphs by allowing <graph> tags to be nested into a node's <att> tag.
  2. GraphML: also supports nested graphs.
  3. NetworkModel: Cytoscape Web's native format is a simple option. You just need to set the parent node ID in the nodes' data, like in the example bellow.
  4. At any moment, you can create compound nodes by adding new nodes to another node.

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html>
    
    <head>
        <title>Cytoscape Web example</title>
        
        <script type="text/javascript" src="/js/cytoscape_web/json2.min.js"></script>
        <script type="text/javascript" src="/js/cytoscape_web/AC_OETags.min.js"></script>
        <script type="text/javascript" src="/js/cytoscape_web/cytoscapeweb.min.js"></script>
        
        <script type="text/javascript">
            window.onload = function() {
                // id of Cytoscape Web container div
                var div_id = "cytoscapeweb";
                
                var network_json = {
                        // NOTE the parent attribute
                        data: {
                            nodes: [ { id: "1" },
                                     { id: "2", parent: "1" },
                                     { id: "3", parent: "1" },
                                     { id: "4", parent: "2" },
                                     { id: "5", parent: "6" },
                                     { id: "6" },
                                     { id: "7" },
                                     { id: "8", parent: "1" }
                            ],
                            edges: [ 
                                    { target: "3", source: "5" },
                                    { target: "3", source: "8" },
                                    { target: "2", source: "7" }
                            ]
                        }
                };
                
                // NOTE the "compound" prefix in some visual properties
                var visual_style = {
                    nodes: {
                        shape: "DIAMOND",
                        compoundShape: "RECTANGLE",
                        label: { passthroughMapper: { attrName: "id" } } ,
                        compoundLabel: { passthroughMapper: { attrName: "id" } } ,
                        borderWidth: 2,
                        compoundBorderWidth: 1,
                        borderColor: "#666666",
                        compoundBorderColor: "#999999",
                        size: 25,
                        color: "#ffffff",
                        compoundColor: "#eaeaea"
                    }
                };
                
                // initialization options
                var options = {
                    swfPath: "/swf/CytoscapeWeb",
                    flashInstallerPath: "/swf/playerProductInstall"
                };
                
                var vis = new org.cytoscapeweb.Visualization(div_id, options);

                vis.ready(function() {
                    // set the style programmatically
                    document.getElementById("layout").onclick = function(){
                        vis.layout("CompoundSpringEmbedder");
                    };
                });
                
                var draw_options = {
                    // your data goes here
                    network: network_json,
                    // this is the best layout to use when the network has compound nodes 
                    layout: "CompoundSpringEmbedder",
                    // set the style at initialisation
                    visualStyle: visual_style,
                    // hide pan zoom
                    panZoomControlVisible: false 
                };
                
                vis.draw(draw_options);
            };
        </script>
        
        <style>
            * { margin: 0; padding: 0; font-family: Helvetica, Arial, Verdana, sans-serif; }
            html, body { height: 100%; width: 100%; padding: 0; margin: 0; background-color: #f0f0f0; }
            body { line-height: 1.5; color: #000000; font-size: 14px; }
            /* The Cytoscape Web container must have its dimensions set. */
            #cytoscapeweb { width: 100%; height: 90%; }
            #note { width: 100%; text-align: center; padding-top: 0.5em; }
            .link { text-decoration: underline; color: #0b94b1; cursor: pointer; }
        </style>
    </head>
    
    <body>
        <div id="cytoscapeweb">
            Cytoscape Web will replace the contents of this div with your graph.
        </div>
        <div id="note">
            <span class="link" id="layout">Recalculate layout</span>
        </div>
    </body>
    
</html>

To learn more about how to work with compound nodes, take a look at these related API functions and options:

You can also play with the compound nodes demo.

Conclusion

This tutorial should allow you to have Cytoscape Web up and running and interacting with other components in your page. You should now be sufficiently capable of using the API reference to customise Cytoscape Web to your specific needs.

If you still have questions, take a look at the FAQ. Most likely, your question has already been answered there.