Monte Gardner - 2011-12-05

The graph.js library in Viewpoint handles two related functions.
Manages an internal set of Connection objects representing directed connections between DOM Nodes (pieces of HTML code).
Manages a canvas-based interface in which the DOM nodes become free-form draggable pieces that can have connections drawn between them.

To construct a graph, you first need an HTML container with a <canvas> tag as its first child, an ID and children nodes like so:

<div id = "graphContainer">

<canvas id="graphCanvas"></canvas>
<ul>

<li>alpha</li>

<li>beta</li>

<li>charlie</li>

</ul>

</div>

Then, in your javascript, call the Graph constructor in the jquery load function like so:

jQuery(window).load(function(){

var myGraph = new Graph(document.getElementById("graphContainer"), document.getElementById("graphCanvas"), "li");

});

(dont do this in the ready() function because IE has some problems with that). The first argument is a reference to the containing node. The 2nd parameter is a reference to the canvas object within it, the 3rd parameter is a jQuery filter string describing the set of elements within the container that are to become draggable, connectible nodes. This filter is interpreted from the reference point of the container, not the top-level document.

Upon construction, the graph will set the display attribute of each such child node to 'relative'. This will usually cause them to initially float near the bottom of the container. The user can then drag each element into the canvas. Dragging a node on top of another node will make a connection from the drop target to the dropped node. Alternatively, the user may left click on one node, then left click another node to draw a connection from the first to the second. These connections will be represented visually by arrows drawn between nodes. The user can also delete a connection by moving the mouse over one of these lines (user should see a 'scissors' icon for the mouse cursor) and left clicking on the line.

Graph Structural Functions

removeNode(node) removes the given node from the graph.  Also disconnects any connections to or from that node.
addNode(node) adds the given node to the graph
addConnection(from,to) Makes a connection between the given nodes
removeConnection(from,to) If a connection between the given nodes exists, this function will delete that connection and return true. Otherwise, this function will return false
disconnectAll(node) disconnects any connections to or from the given node.

These functions will trigger a 'change' event on the container that you provided in the constructor. So, if you want to run your own function each time a node is added or removed or a connection is made or removed, you can do so like this:

jQuery(containerReference).change(functionReference);

Graph Query Functions

graph.container - a reference to the Container object
graph.canvas - a reference to the canvas object
graph.ctx - a reference to the canvas context, used for calling the drawing functions
graph.connections an Array of Connection objects, each of which has a from and a to attribute
graph.nodes an Array of the nodes in the graph.
graph.isConnected(from,to) - Returns true if and only if there is a connection between the given nodes.
graph.getNodesConnectedFrom(node) - Returns all nodes such that there is a connection from the given node to that node.
graph.getNodesConnectedTo(node)  -  Returns all nodes such that there is a connection to the given node from that node.
graph.getRootNodes() -  Returns all nodes which have no connections going to them. (may have connections going from them)(note that a graph doesn't have root nodes in the traditional sense)(if there are cycles, no node in the cycle will be included in the result)
graph.findPaths(startNode,endNode) - recursive algorithm. If there are 1 or more paths from the given startNode to the given endNode, this function will return an array of paths, a path being an array of Connection objects. If there are no such paths, this function will return an empty array.  Call the function clearTraversal() prior to calling this function or it wont work right.
getCyclicalPaths() - Returns an array of all paths in this graph that are circular, (begin and end at the same node).

Line Styles

You may want to change the color or style of the arrows drawn between nodes. You can do this by calling the setLineStyle of a Connection object (in the graph.connections array). This means that you can set different line styles for different connections based on whatever conditions you want. This function takes a lineStyle object as a function. A lineStyle object may have the following attributes:

lineWidth : an integer
lineCap : one of the strings: butt, round, or square (http://www.html5canvastutorials.com/tutorials/html5-canvas-line-caps/)
strokeStyle : a color string such as "#ffffff"
head: an image object (with the .src attribute previously set). This is optional. If it is set, the line will be drawn with the given image used as  an arrowHead.  The base image should be pointing downward in order for the rotation stuff to work.
dashPattern: an integer array describing a pattern of dashes and blanks.  For example dashPattern:[5,5] will draw a 5 pixel line then go blank for 5 pixels, then repeat.   If you want a solid line, set this value to null.

For an example of how this can work, see the function markCycles() in create.js, used to make circular paths a thick red line.

Affordance

The graph has the option of placing a small icon at the top, bottom, left, and center edges of each node. This can be used to give a more professional, 'visio' like look to your graph. To do this, create an Image object, set it's src attribute to a valid URL, then set graph.affordance to that Image object.