Constraints

WebCoLa supports three types of constraints:

Separation Constraints
Alignment Constraints
Group Constraints

Separation and alignment constraints are set as follows:

d3cola.constraints(myconstraints);

myconstraints is an array of objects, each of which represents a constraint.

Group constraints, however, are set the following way:

d3cola.groups(groups);

groups is an array of objects, each of which represents a group.

Some examples of each type of constraint are given below.

Separation constraints

These constraints enforce a minimum (inequality) or exact (equality) gap between a pair of nodes along a specified axis.

The type: "separation" property is optional, but recommended for clarity.

Inequality separation constraints

{
    type: "separation",
    axis: "y",
    left: 0,
    right: 1,
    gap: 25
}

This says that the center of graph.nodes[0] must be at least 25 pixels above the center of graph.nodes[1]. To be more precise, it is an inequality constraint that requires:

graph.nodes[0].y + gap <= graph.nodes[1].y

An example of and further information about inequality separation constraints can be seen at the page bounds constraints sample: Demo, Code

For more information on inequality separation constraints, for now see:

Known issues:

Cycles in the constraint graph will not work

Equality separation constraints

You can turn an inequality constraint into an equality one simply by adding an extra attribute like this:

{
    type: "separation",
    axis: "y",
    left: 0,
    right: 1,
    gap: 25,
    equality: true
}

This would impose the constraint:

graph.nodes[0].y + 25 == graph.nodes[1].y

Alignment constraints

Alignment constraints ensure that certain nodes are aligned along a specified axis.

{
    type: "alignment",
    axis: "x",
    offsets: [
        {node: 1, offset: 0},
        {node: 2, offset: 0},
        {node: 3, offset: 0}
    ]
}

This sample constraint will ensure that the nodes in d3cola.nodes() with indices 1, 2, and 3 will all have their centers aligned along the x-axis.

For alignment constraints, the type: "alignment" property is mandatory to discriminate them from separation constraints.

An "offset" of 0 will make all the nodes in the alignment be precisely aligned by their centers. Non-zero offsets can be specified to make nodes align by displacements from their centers. For example, to force a bunch of nodes of different widths to be aligned by their left-hand-sides, specify an offset for each node proportional to half its width.

For further info, see the "Alignment" example: Demo, Code

Group constraints

Group constraints force certain nodes to be placed together inside a rectangular group.

{
    leaves: [0, 1, 2],
    padding: 20
}

This sample makes the nodes with indices 0, 1, and 2 form a group that has a padding of 20. The padding parameter can be omitted to get a default padding of 1.

For more information on this, see the "Simple Groups" example: Demo, Code

{
    leaves: [0],
    groups: [
        {leaves: [1, 2]}
    ]
}

This sample describes a nested group structure, with the node with index 0 being placed inside an outer group. That outer group contains an inner group with node indices 1 and 2 as its contents.

Groups can be nested arbitrarily deep. The padding parameter from the sample above may of course also be applied to nested groups, but was omitted here for clarity.

For an example of nested groups, see the "Grouped Layout" example: Demo, Code

Provide feedback

Saved searches