Introduction
In this tutorial, you'll learn the basics of how to work with graphs and displays in Thinkmap.
If you view the source of this page, you can see the code that makes up this example in its entirety, but we'll go through it section-by-section here.
Setting Up
In order to work with Thinkmap, you'll need to include the thinkmap.js
client Javascript library and the mesh.js javascript file, which contains the
code for this example. We do that by adding two script tags to the page's
<head> section:
<head> ... <script src="thinkmap.js"></script> <script src="mesh.js"></script> ... </head>
The thinkmap.js file is automatically provided and served by the Thinkmap Server - you will not
find it if you look in your project folder.
However, if we look inside the mesh.js file, we can see it starts with the following:
thinkmap.onready(function(){
// ... omitted code ...
});
The thinkmap.onready() function is the way that the
Thinkmap API tells us that it has been loaded and is ready to go. It's common for all the code in your project to be contained in a single
function that is called back when Thinkmap has loaded. Functions registered via the "onready" function
are not be called until both Thinkmap is loaded and the DOMContentReady event has fired in the browser.
Also, it's worth mentioning here that the way that you interact with the Thinkmap API is always through the global "thinkmap" object. In fact, the only side-effect of loading the Thinkmap library is that a single object called "thinkmap" is added to the Window object (if that object doesn't already exist).
Building a graph
At the heart of every Thinkmap project is a graph. A graph is a collection of nodes and edges (links) that connect nodes. To construct and populate the graph, we do the following:
// construct a graph var graph = new thinkmap.graph.Graph(); // create a 10x10 mesh of nodes and edges createMesh(graph, meshSize, meshSize);
Now let's look at the create mesh function:
// this function populates a graph with a mesh of nodes and edges
function createMesh(graph,width,height) {
// first we create a unique index on all nodes on the properties {x,y}
// this will speed up the queries we use to build the edges
graph.createIndex({x:1,y:1},true,'node');
for (var x=0;x<width;x++) {
for (var y=0;y<height;y++) {
// create the node
var newNode = graph.createNode({x:x,y:y});
// add the node
graph.add(newNode);
// add a horizontal edge, linking "newNode" to the node to
// the left of it
if (x>0) {
var leftNode = graph.selectOne({x:x-1,y:y});
graph.add(graph.createEdge(leftNode,newNode));
}
// add a vertical edge, linking "newNode" to the node above it
if (y>0) {
var aboveNode = graph.selectOne({x:x,y:y-1});
graph.add(graph.createEdge(aboveNode,newNode));
}
}
}
}
Creating the Display
Now that we have created a mesh in our graph, we want to show it someplace on the screen. To do that, we are going to need a Thinkmap Display.
The Thinkmap thinkmap.display.Display object is used to
put a Thinkmap visualizations on the page.
A Display is actually a type of Graph, Which means you can do all the operations that you can do on Graphs on a Display. But, a Display is much more than just a Graph. A Display decides how your project will look, where on the page it will be located, and how your user will interact with it.
When you construct a display, you give it the HTML DOM Element that it will attach itself to. That element should typically be a <div> element that you have placed somewhere on your page. Here's how we create our Display for this project:
// construct a thinkmap display
var display = new thinkmap.display.Display( document.getElementById('map') );
display.draggable(true); // allow the user to drag nodes
display.zoomOnWheel(true); // use the mouse wheel to zoom
Setting up Templates
Next we will define some display templates that determine how our mesh will be rendered on the screen:
// define the template for nodes to be a circle
display.template('node').as(function(svgSelection,node) {
// whenever a node is created in the display,
// append an <svg:circle r="4px" /> element
svgSelection.append('circle').attr("r", "4px");
});
// edges should be drawn as straight lines (linear is a built-in edge style)
display.template('edge').as(thinkmap.display.edgestyle.linear());
Defining a Layout
Our next step is to define how the mesh will be arranged on screen. We do that with the help of a Thinkmap layout.
// Layout using the spider layout. This is a built-in layout that // uses a particle simulation model to lay out the graph in real-time. var layout=thinkmap.layout.spiderLayout(display,true); // set the target length of edges to the meshSpacing (15 pixels) layout.edgeForce().length(meshSpacing); //don't let nodes float off the edge of the screen layout.enforceBounds();
PUTTING IT ALL TOGETHER
Finally, we want to add our mesh to the display and establish an initial position for everything.
// add the entire graph to the display
display.add(graph);
// establish a position for each node
display.nodes().position(function(node){
// this function will be called once for every node in the display
// we return an object that contains the x,y pixel coordinates
// for each node
return { x: node.data.x * meshSpacing,
y: node.data.y * meshSpacing };
});
// scroll the display to center the mesh
display.scroll((display.width()/2),(display.height()/2));
display.scroll( -((meshSize-1) * meshSpacing)/2,
-((meshSize-1) * meshSpacing)/2 );
// scale the display by 1/2 to make it fit nicely
display.scale(.5);
Adding some fun
For fun, let's add a feature that allows you to randomly remove nodes over time.
First, we'll write a function that randomply removes a node from the
display (and returns true if there are more nodes to remove):
function removeOneNode() {
var nodes = display.nodes().toArray();
if (nodes.length) {
display.remove(nodes[parseInt(Math.random()*nodes.length)]);
}
return nodes.length > 1;
}
Next we'll set up a thinkmap.async.Future that will remove a node
after waiting for a delay:
// this is a "future" we will use when removing nodes randomly
var removeNextNode;
// this function will cause nodes to be removed from the display one-at-a-time
function slowlyRemove(delay) {
// call removeOneNode in the future, after a delay
removeNextNode = thinkmap.async.later(removeOneNode,delay);
// when that's done, either...
removeNextNode.then(function(hasMore) {
if (hasMore) {
slowlyRemove(delay); // remove another node
} else {
reset(); // or start over
}
});
}
Start all over again
Of course, we want to give the user a way to reset things, so we'll write a function that resets the display:
function reset() {
// if we are removing nodes randomly, cancel that future
if (removeNextNode) removeNextNode.cancel();
// remove everything from the display
display.select().remove();
// add the graph back into the display
display.add(graph);
// re-establish a position for all the nodes
display.nodes().position(function(n){
return { x: n.data.x*meshSpacing, y: n.data.y*meshSpacing };
});
}
Hook up the buttons
The last thing we need to do complete our project is to hook up the "Randomly Remove Nodes" and "Start Over" buttons. Here's how we do that:
// hook up the 'restart' button's onclick handler
document.getElementById('restartButton').onclick=reset;
// hook up the 'remove' button's onclick handler
document.getElementById('removeButton').onclick=function() {
slowlyRemove(100);
};
SUMMARY
In this tutorial, you learned about the basics of the Thinkmap API. You learned how to construct a Graph, configure a Display, and create a layout. Finally, you learned how you can interact with a running Thinkmap visualization via the API.