General API notes

Nodes and Links

Nodes are the shapes in a diagram, and are often called "vertices". Links are the lines between the shapes, and are often called "edges". These terms are interchangeable and you may find a mixture of these terms in the documentation and code. Similarly, "graph drawing", "network visualization", and "diagram layout" are usually synonyms.

Nodes have positions which are largely determined by the lengths of the links between them. Unlike many other graph drawing algorithms, WebCola also allows the specification of constraints to specify the layout. Constraints can operate directionally on a pair of nodes, or on a set of nodes. Read more about constraints here. In addition, you can define a hierarchy over the nodes in the graph by specifying (potentially) nested groups of nodes. The layout keeps these groups of nodes strictly within bounding boxes reflecting the containment hierarchy.

WebCola adopts a variation on the adjacency list representation used by d3.layout.force. When you setup the layout, you pass in arrays of node and link objects, and the link objects refer to the nodes through their source and target fields. Similarly, you can optionally pass in arrays of constraint and group objects.

These arrays of node, link, group and constraint objects are shared between the client and WebCola. WebCola will read some fields that you set on these objects, and will annotate the objects with other fields. Some of these are helpful to you as a client, such as position, and some of these are for the internal use of WebCola, such as variables for the constraint solver. For this reason, you should consistently use the same object to represent the same node or link (otherwise constraints can "leak", causing slowdown).

Following the D3 force layout convention, the source and target fields of the links can refer to the end nodes in two different ways: by integer index or by reference. If the field is of integer type, WebCola assumes it to be the index of the position of the node in the array of nodes, the same representation that d3.layout.force uses. Or if it is of object type, WebCola assumes the same node object was assigned to the array and to the source or target field.

Internally, WebCola always uses the reference form: if you supply integers they will be replaced with references. Similarly, WebCola expects each node object to have a field named index which holds the integer index. If it is not supplied, it will be added by the layout's start method. This has caused confusion in the past, but (for better or worse) it is consistent with the D3 force API.

Still to cover

• The loops of loops to solve lengths ("no constraints"), constraints, and overlaps
• How asynchronous layout works (tick and end events)
• ...