# SubTrees

Tree diagrams can get very large. One way to simplify the diagram is to hide branches of the tree. "Collapsing" a tree node means making all of its children and the links to them not visible, and recursively collapsing all of the children that have children.

To collapse a node in a tree, set Node.isTreeExpanded to false; to make sure it is expanded, set that property to true. You should not set this property to true on a Node that is not GraphObject.visible.

It is commonplace to provide a button on a node to allow users to collapse and expand subtrees as they wish. GoJS makes this easy to implement by providing a predefined kind of Panel, named "TreeExpanderButton", that acts as a button to collapse and expand the subtree of a node. This button changes the visibility of all parts of the subtree except for the node itself.

Clicking on an expander button also invalidates the layout that is responsible for the node. Collapsing a subtree often results in a large empty area, and expanding a subtree often results in overlapping nodes, so a new layout ought to be performed again to make the tree look better.

    diagram.nodeTemplate =
      new go.Node("Horizontal")
        .add(
          new go.Panel("Auto")
            .add(
              new go.Shape("Ellipse", { fill: "white" }),
              new go.TextBlock()
                .bind("text", "key")
            ),
          go.GraphObject.make("TreeExpanderButton")
        );

    diagram.layout = new go.TreeLayout();

    const nodeDataArray = [
      { key: "Alpha" }, { key: "Beta" }, { key: "Gamma" }, { key: "Delta" },
      { key: "Epsilon" }, { key: "Zeta" }, { key: "Eta" }, { key: "Theta" }
    ];
    const linkDataArray = [
      { from: "Alpha", to: "Beta" },
      { from: "Beta", to: "Gamma" },
      { from: "Beta", to: "Delta" },
      { from: "Alpha", to: "Epsilon" },
      { from: "Epsilon", to: "Zeta" },
      { from: "Epsilon", to: "Eta" },
      { from: "Epsilon", to: "Theta" }
    ];
    diagram.model = new go.GraphLinksModel(nodeDataArray, linkDataArray);

Notice that if you first collapse the "Beta" node and then collapse the "Alpha" root node, if you then expand the "Alpha" node, the "Beta" node remains collapsed, whereas the "Epsilon" node remains expanded. This is because the collapsing operation remembers the state of nodes within the subtree, as the property Node.wasTreeExpanded. The expanding operation respects the value of that property when recursing through the subtree.

You may also want to start off the tree mostly or completely collapsed. First, set Node.isTreeExpanded to false in the template. That will cause only the roots of the tree to be shown. Second, if you want to show some levels of the tree, call Node.expandTree on each root node.

    diagram.nodeTemplate =
      // by default each node is collapsed
      new go.Node("Horizontal", { isTreeExpanded: false })
        .add(
          new go.Panel("Auto")
            .add(
              new go.Shape("Ellipse", { fill: "white" }),
              new go.TextBlock()
                .bind("text", "key")
            ),
          go.GraphObject.make("TreeExpanderButton")
        );

    diagram.layout = new go.TreeLayout({ });

    const nodeDataArray = [
      { key: "Alpha" }, { key: "Beta" }, { key: "Gamma" }, { key: "Delta" },
      { key: "Epsilon" }, { key: "Zeta" }, { key: "Eta" }, { key: "Theta" },
      { key: "Iota" }, { key: "Kappa" }, { key: "Lambda" }
    ];
    const linkDataArray = [
      { from: "Alpha", to: "Beta" },
      { from: "Beta", to: "Gamma" },
      { from: "Beta", to: "Delta" },
      { from: "Alpha", to: "Epsilon" },
      { from: "Epsilon", to: "Zeta" },
      { from: "Epsilon", to: "Eta" },
      { from: "Eta", to: "Theta" },
      { from: "Gamma", to: "Iota" },
      { from: "Iota", to: "Kappa" },
      { from: "Iota", to: "Lambda" }
    ];
    diagram.model = new go.GraphLinksModel(nodeDataArray, linkDataArray);

    // After the nodes and links have been created,
    // expand each of the tree roots to 3 levels deep.
    diagram.findTreeRoots().each(r => r.expandTree(3));