Groups

Use the Group class to treat a collection of Nodes and Links as if they were a single Node. Those nodes and links are members of the group; together they constitute a subgraph.

A subgraph is not another Diagram, so there is no separate HTML div element for the subgraph of a group. All of the Parts that are members of a Group belong to the same Diagram as the Group.

Groups can also be collapsed and expanded, to hide or show the member parts. This is distinct from collapsing and expanding trees.

The member parts of a group are available via the Group.memberParts property. Conversely, the Part.containingGroup property refers to the group, or null if the part is a top-level part. A part can be member of at most one group at a time. You can set that property in order to add that part to a group. However you must make sure that no group contains itself, either directly or indirectly through other groups.

Because every Group is a Node, you can have nested groups. Although member Nodes and Links belong to the Group that contains them, they are not in the visual tree of the group -- their GraphObject.panel is null and no member part is in the group's Panel.elements collection. No Part can be in the visual tree of another Part. Parts normally do belong directly to one Layer.

See samples that make use of Groups in the samples index.

Simple Groups

In a GraphLinksModel the Model.nodeDataArray holds node data, each of which could be represented by a Group rather than by a regular Node. You can declare that it should be a group by setting the isGroup data property to true. You can declare that a node data be a member of a group by referring to the group's key as the group data property value.

Here is a group containing two nested groups as well as two regular nodes. If you move a group, its member parts move along. If you copy a group, its member parts are copied too. If you delete a group, its member parts are deleted too. If you move a member node, its containing group inflates or shrinks to cover the area occupied by all of the members.

Groups and Links

Because Groups are Nodes, a Link may connect with a group as well as with a plain node.

Here is a simple example of four regular nodes and one group node. In this example the link from "Alpha" goes directly to the "Beta" node, but the link to "Delta" actually comes from the "Omega" group rather than from any particular member of the group.

If you drag the "Delta" node around you can see how the link from the "Omega" group appears to come from the center of the group and start at the group's edge rather than at any member node. This is different than for the link from "Alpha" to "Beta".

Note also how the link from "Beta" to "Gamma" is effectively owned by the "Omega" group because both of the nodes are owned by that group. Copying the group automatically copies the link too.

This example did not set any of the following properties: Diagram.nodeTemplate, Diagram.groupTemplate, and Diagram.linkTemplate, in order to demonstrate the default templates for Nodes, Groups, and Links.

Group templates

Here is an example of how one might define templates for nodes and for groups. The node template is very simple: some text inside an ellipse. The group template is different from a node template in several aspects.

First, the group template builds a go.Group, not a go.Node or go.Part. The group can use a number of the panel types, just as a node may use various panel types.

Second, the group template includes a Placeholder object. The group template can have at most a singular Placeholder object within its visual tree. The Placeholder assumes the size and position of the union of the bounds of all of the group's member parts, plus some padding. The use of a Placeholder results in the Group surrounding the collection of group members, no matter where the member nodes are placed.

Note how when you move the "Beta" or "Gamma" nodes the "Omega" group automatically resizes so that the TextBlock on the group stays below and on the right side of the "RoundedRectangle" shape.

Groups as subgraphs

There are some common ways of treating the nodes and links that are the members of a group as if it were its own graph. One way to declutter a diagram is to "collapse" a Group to hide the subgraph that it holds.

A Group has its own Group.layout that is responsible for the positioning of member Nodes and the routing of member Links. This is exactly like a Diagram having its own Diagram.layout that positions top-level Nodes and routes top-level Links.

Keep in mind that subgraphs are not separate Diagrams and that Groups are just one way of organizing Parts. Because subgraphs are collections of Nodes and Links in the same Diagram as the Group itself, it is possible to have Links that connect Nodes that are inside a Group with Nodes that are outside of the group. It is also possible to have links that connect nodes with the group of which they are a member.

Layouts of subgraphs

You can specify a Layout that applies to a group's subgraph by setting the Group.layout property. This operates on the group's member nodes and links as if it were its own diagram. A diagram layout of nodes that include groups with their own layout will treat those groups as if they were simple nodes, albeit probably larger than normal nodes.

In this example each of the groups has a unique layout which are all different than the layout for the overall diagram.

The default layout for a Group is an instance of Layout, just as it is for Diagram. If you do not specify a value for Group.layout the default layout for the group will position all member nodes that do not have a real Part.location.

If you explicitly set Group.layout to null, the Diagram will be responsible for laying out all of Nodes and Links as if the Group did not exist. This is possible because a subgraph is not another Diagram.

Collapsing and expanding Groups

One common technique to visually simplify a diagram is to hide parts of them by "collapsing" them. In the case of Groups, it may make sense to be able to hide the subgraph.

To collapse a group, set or bind Group.isSubGraphExpanded to false. To make sure it is expanded, set that property to true.

It is commonplace to provide a button on a group to allow users to collapse and expand groups as they wish. GoJS makes this easy to implement by providing a predefined kind of Panel, named "SubGraphExpanderButton", that acts as a button to collapse and expand Groups. This button changes the visibility of the member nodes and links but does not change the visibility of the group itself. When the group's visual tree includes a Placeholder, the placeholder will automatically shrink when the member parts become invisible and will inflate when the member parts become visible again.

Click on the expander button to collapse or expand the group. Changing the size of the group also invalidates the layout that is responsible for positioning the group as a single node. Often the size of the group changes greatly, so a layout usually needs to be performed again.

If you do not want a layout to be performed again when the group changes size, you can set the Part.layoutConditions property to control the circumstances under which the layout will be invalidated.

The following example demonstrates a Group with a header holding a button and some text. Note how when collapsing the group, the link from "Alpha" to "Beta" changes to appear to connect with the Group rather than with the now hidden "Beta" Node.