Diagram Layouts

In general terms, a "layout" is a way of sizing and positioning a collection of objects. HTML has its own layouts for its HTML elements. In GoJS you have already seen many examples of Panel layout, such as Auto or Table, which sizes and positions GraphObjects within a Panel. GoJS also provides Diagram layouts, which position Nodes and route Links within a Diagram or a Group.

Naturally the principal purpose of each diagram Layout is to position nodes, typically by calling Part.move. But layouts also may also result in custom routing of the links, by setting properties on each Link. For example TreeLayout also ensures that links are routed in the expected direction by setting Link.fromSpot and Link.toSpot depending on the TreeLayout.angle. (However, that behavior can be disabled by setting TreeLayout.setsPortSpot and TreeLayout.setsChildPortSpot. The same is true for some other layouts.)

Diagram layouts can be accomplished in several manners. Manual layouts occur because the user moves nodes, thereby establishing new positions for those nodes. Such layouts might be saved in some persistent data format and later loaded using data binding or assignments in code. Programmatic layouts happen when some code executes to set the Part position or location. Automatic layouts are programmatic layouts that are implemented by the Layout class or its subclasses.

Default Layout

The value of Diagram.layout defaults to an instance of Layout. This kind of layout is unlike all of the other layout subclasses, in that it only sets the position of nodes that do not already have a position -- i.e. where the X or Y of the GraphObject.actualBounds is NaN. It leaves unmodified all nodes that do have a defined position, and it ignores all links.

Many of the examples you have seen so far do not set Diagram.layout and thus use the default layout. Some of the examples data bind the Part.location or GraphObject.position to a data property. Those examples are basically using manual layout, but with the node positions coming from the node data rather than from arrangement by the user.

However many of the examples just allow the standard behavior of the Layout class to assign positions to the nodes in the order in which they are seen by the layout. Those examples are exhibiting automatic layout behavior.

Automatic Layouts

GoJS offers several kinds of automatic layouts, including:

• GridLayout
• TreeLayout
• ForceDirectedLayout
• LayeredDigraphLayout
• CircularLayout

There are samples for each of these layouts, demonstrating the effects of setting various detailed layout properties:

• GridLayout Sample
• TreeLayout Sample
• ForceDirectedLayout Sample
• LayeredDigraphLayout Sample
• CircularLayout Sample

You can set Diagram.layout in a JavaScript statement:

diagram.layout = new go.ForceDirectedLayout();

. Or you can initialize that property using GraphObject.make:

var diagram = $(go.Diagram, "myDiagramDiv",
                {
                  initialContentAlignment: go.Spot.Center,
                  layout: $(go.TreeLayout,
                            { angle: 90, nodeSpacing: 10, layerSpacing: 30 })
                });

We recommend using GraphObject.make whenever you can because of the error checking that it does for property names.

In the following pages you will see many examples that make use of automatic layout by setting the Diagram.layout property. Search the sources of the samples for many more examples.

Layout Invalidation

A layout is considered "valid" when it has performed its positioning of its nodes and (perhaps) routed its links. However some kinds of changes cause a layout to become "invalid", thereby causing it to be performed again in the near future. Because layouts can be computationally expensive, automatic layouts are not performed as soon as a layout is invalidated. Instead they are typically performed at the end of a transaction.

The most common reasons for a layout to be invalidated are because a node or a link has been added or removed from the collection of nodes and links that a layout is responsible for, or because a node or a link has changed visibility, or because a node has changed size. If you do not want an automatic layout to happen when such a change occurs, it may be easiest to set Layout.isOngoing to false.

But if you do not want a change to a particular Node or Link to cause an automatic layout, yet you do want that for the other Nodes or Links, you can set the Part.layoutConditions property to the combination of Part "Layout..." flags that suits your needs. It is most common to not want a layout for the Part.LayoutNodeSized condition. Parts that are not visible or that are in layers that are Layer.isTemporary also never invalidate any Layout.

Finally, you can set Part.isLayoutPositioned to false in order for the Layout to completely ignore that Part.