The easiest way to get started with Thinkmap is to create a project based on one of our templates. Simply click on the Templates & Examples tab above and select a template to use as your starting point. If this is your first project, try using the "Mesh Tutorial" -- it's a simple project that will help you to understand the basics of how to work with the Thinkmap API.
Your new project will be unpacked into a directory of your choosing on your computer. There, you can then view and edit the files with your favorite text editor, or if you use Eclipse as your IDE (we recommend it), you can import the project into your Eclipse Workspace.
If you are developing using Thinkmap, it helps to be familiar with the following technologies:
A Thinkmap is made up of Entities. Entities are either nodes (data items that represent things) or edges, which are the connections between nodes.
An entity can have a type, which makes it convenient to treat different entities collectively. For example, a node might have the type 'actor'. Types are hierarchical, so both an 'actor' and a 'director' can be a 'person'.
If you're using the Thinkmap server, type information is determined by the datasource you are connecting to.
The heart of any Thinkmap is the graph. A graph is collection of entities. If you are using Thinkmap Server, you may connect a graph to a datasource, which means that the graph will load data from the server on-demand. This allows you to navigate and query enormous graphs and only transfer the data incrementally as it is needed. If you do not use a Thinkmap Server, generally you will need to load all your data into the graph at startup time.
Here's how you would create a very simple graph:
var graph = new thinkmap.graph.Graph(); // construct a graph
var node1 = graph.createNode({name:'node1'}); // create a node
graph.add(node1); // add it to the graph
var node2 = graph.createNode({name:'node2'}); // create a second node:
graph.add(node2); // add it to the graph
// create an (undirected) edge linking node1 to node2
var edge1 = graph.createEdge(node1,node2);
graph.addEdge(edge1); // add it to the graph
Graphs can be backed by a Thinkmap datasource, at which point all the information in the datasource is accessible to the graph. In this case, the graph loads information from the Thinkmap Server as necessary based on queries.
var graph = new thinkmap.graph.Graph(); // construct a graph
// connect it to a Thinkmap Datasource at the following URL
graph.datasource('/moviedb.tas');
// do a graph query for "Tom Cruise" and log the results
graph.query({$search:'Tom Cruise'})
.execute()
.oncomplete(function( resultGraph ) {
console.log( resultGraph.toArray() );
});
As you can see from the example above, it is easy to perform queries on a graph in Thinkmap.
Graphs are queried using the Thinkmap query language, a language optimized for querying the type of node-edge graphs that Thinkmap is usually used to display.
For example, let's say you wanted to get all the paths that connect Tom Cruise to movies he is connected to via an edge:
graph.query([{$search:'Tom Cruise'},'edge','movie'])
.execute()
.oncomplete(function( resultGraph ) {
console.log( resultGraph.toArray() );
});
We can also create a more general query and tell Thinkmap to start
with a particular entity (or set of entities). Let's say the variable
myNode is pointing to a node (e.g. "Tom Cruise"). We could
execute the following to see all the nodes that myNode is connected to.
graph.query(['node','edge','node']) // query for nodes connected to nodes
.execute( myNode ) // start the query at myNode
.oncomplete(function( resultGraph ) {
console.log( resultGraph.toArray() );
});
For more information about Thinkmap Queries, please see the Query Language Documentation.
A Thinkmap Display is a graph that renders its nodes and edges on the screen. The Thinkmap display handles rendering as well as other behaviors associated with the screen such as scrolling, scaling, and dragging. When someone clicks on a node in a typical Thinkmap, we query an underlying graph, and add the results of the query to a display, thereby causing them to be rendered on the screen.
Here's an example:
// Query the graph for all nodes (and edges) connected to "startNode"
graph.query(['node','edge','node']).execute(startNode)
.oncomplete(function(resultGraph) {
// add the results to the display
display.add(resultGraph);
// remove the entities in the display that are not in resultGraph
display.retainOnly(resultGraph);
// layout the display
display.layout();
});
To render the nodes and edges on the screen, the Display uses a series of templates.
Templates are defined using the template() method of thinkmap.display.Display.
Templates work by adding SVG elements to the screen when nodes and edges are added to the Display.
Template functions are always passed a thinkmap.selection.Selection (a Thinkmap
object that makes it easy to manipulate SVG in Javascript), and an entity (the entity being added
to the display).
Let's look at a couple of examples:
// represent all nodes as a 4px radius circle
display.template('node').as(function(selection,node) {
selection.append('circle').attr("r","4px");
});
// of course you can always use properties of the data in your template
display.template('employee').as(function(selection,node) {
selection.append('circle').attr("r", node.data.salary / 1000);
selection.append('text')
.text( node.data.lastname + ', ' + node.data.firstname );
});
// templates can also be defined in an external Javascript template file
// here, we'll render all movies using an external file called 'movie.jst'
display.template('movie').as('movie.jst');
// some templates are built-in to Thinkmap. Most of the time, when you
// render edges, you'll want to use one of our built-in edge styles
// here, we'll make all edges appear as straight lines drawn between nodes
display.template('edge').as( thinkmap.edgestyle.linear() );
A Tree is a special type of graph that maintains a tree structure. It is
represented in Thinkmap by the class thinkmap.graph.Tree.
A tree is a hierarchical structure where all nodes in the tree are the descendant of a single root node "the root". Every node in a tree can have only 1 parent, with the exception being the root which has no parents.
Every node in a tree can have 0 or more children. A node without any children is considered a "leaf" node.
One of the important characteristics of a tree is that each node has a depth. The depth refers to how many ancestors a node is removed from the root. If a node has the root for a parent, then its depth will be 1 and its children will have a depth of 2. The root has a depth of 0.
Trees are used to back the treeLayout and the radialLayout, these layouts require you to provide them with a Tree so that they know how to arrange the nodes that they are laying out.
A Layout is an object in the Thinkmap API that works with a Display to position and arrange entities. Each layout is bound to one Display, and a Display may have multiple layouts. Typically, each layout that is bound to a Display is listening for the Display's "layout" event. When that event is fired, each layout will attempt to position the entities that it is responsible for. Some layouts position entities continuously, while other calculate the position of entities once and smoothly animate them into place.
Thinkmap comes with several pre-defined layouts:
Thinkmap uses the concept of a selection in a number of places within the API. Selections, in general, are a way to conveniently manipulate many things at one time, whether they be DOM elements, or entities (nodes and edges) in a graph.
thinkmap.graph.Selection)Created through calling thinkmap.graph.Graph.select(), graph selections are used for manipulating elements in a graph. Selections can operate on other selections, using set operations. So one selection can difference, complement, intersect, and union another selection, and return the results of the operation. To learn more about Graph Selections, read our guide to understanding Graph Selections.
thinkmap.selection.Selection)DOM Element Selections are used to manipulate the DOM using a convenient API. Most of the time, users of Thinkmap will use them to manipulate a display entity's assigned SVGElements (e.g. append a text element, change the radius of a circle, set a CSS class). However, these selections can also represent the non-thinkmap areas of the DOM such as divs, headings, and links. To learn more about DOM Element Selections, read our guide to understanding Element Selections.
Because the Thinkmap visualization component is a web based component, many events happen asynchronously. For example, when we perform a query, that query may take some time to complete and may need to contact a remote datasource for information. If we performed these tasks synchronously, the browser would seem to "lock-up" and the user experience would be bad. Instead, we perform them asynchronously, so the user can do other things while our tasks complete.
Dealing with asynchronous programming in Javascript can be tricky,
which is why we created the thinkmap.async module. It
includes a number of functions and classes for easily dealing with
asynchronous behavior.
The core of the thinkmap.async module is the thinkmap.async.Future
class. It represents a value which will be computed sometime in the future.
Many functions within Thinkmap operate on Futures, but the one that you will most commonly use is the ResultSet, which is a Future graph that is returned when a query is executed on a graph. As a query executes, a callback function (onresult) is called for each result (traversal path). When the query is complete, the oncomplete handler is called and it is passed a resultant graph, which contains all the paths through the input graph that were traversed by the query.
This getting started guide was designed to give you a brief tour of some of the concepts that are key to understanding how Thinkmap works. For more information on the full client-side Thinkmap API, you sohuld read the Client API Documentation.