Options
All
  • Public
  • Public/Protected
  • All
Menu

Class Node

Hierarchy

A Node is a Part that may connect to other nodes with Links, or that may be a member of a Group.

Group inherits from Node, enabling nodes to logically contain other nodes and links.

For a more general discussion of how to define nodes, see Introduction to Nodes.

Although you can create a Node and Diagram.add it to a Diagram, this does not update the Model. It is more common to create a node by adding a node data object to the model by calling Model.addNodeData. For example:

myDiagram.startTransaction("make new node");
myDiagram.model.addNodeData({ key: "Omega" });
myDiagram.commitTransaction("make new node");

This will cause a Node or simple Part to be created (copying the template found in Diagram.nodeTemplateMap), added to the Diagram in some Layer (based on Part.layerName), and bound to the node data (resulting in Panel.data referring to that node data object). If you do not keep a reference to that JavaScript object, as the above code does not, you can retrieve it later by calling Model.findNodeDataForKey.

It is very common to initialize a Diagram by setting Model.nodeDataArray to a JavaScript Array of JavaScript objects holding the properties that you need in your model. Nearly all of the samples do this kind of initialization.

You can delete a Node by either calling Diagram.remove or by calling Model.removeNodeData. The latter obviously will modify the Model; the former does so if the Node was created from model data. Commands such as CommandHandler.deleteSelection call these methods within a transaction.

You can find all of the Links that are connected with a Node by calling findLinksConnected. Because links normally have a direction, you can find all of the links that have their Link.toNode be a given Node by calling findLinksInto. Similarly, you can call findLinksOutOf to find all of the links coming out from a node; such links have their Link.fromNode be that node. For tree-structured graphs, use findTreeChildrenLinks or findTreeParentLink.

If you are not so interested in the links but are interested in the nodes at the other end of the links connecting with a node, there are other methods that you can call. findNodesConnected returns all of the nodes that are at the other end of the links that connect with a given node. findNodesInto and findNodesOutOf return the subsets of those nodes considering only those links that go into or come out of the given node. For tree-structured graphs, use findTreeChildrenNodes or findTreeParentNode.

For example, to operate on the data of all of the destination nodes:

var it = somenode.findNodesOutOf();
while (it.next()) {
var child = it.value;
if (child.data.text.indexOf("special") >= 0) { ... }
}

You can link two nodes by creating a new Link, setting its Link.toNode and Link.fromNode (in either order), and Diagram.adding it to the diagram. But it is more common to add a link data object to the Diagram.model by calling GraphLinksModel.addLinkData. Just creating and adding a Link will not update the model.

Thus to add a link when using a GraphLinksModel you should do something like:

myDiagram.startTransaction("make new link");
myDiagram.model.addLinkData({ from: "Alpha", to: "Beta" });
myDiagram.commitTransaction("make new link");

Where you would substitute the keys of the actual nodes that you want to connect with a link. If you are using a TreeModel, there are no link data objects, so you just need to call TreeModel.setParentKeyForNodeData to specify the "parent" node's key for a "child" node data.

To find a Link given a link data object in the GraphLinksModel, call Diagram.findLinkForData. When using a TreeModel, call either Diagram.findNodeForData or Diagram.findNodeForKey to get a Node, and then call findTreeParentLink to get the Link, if any exists.

To find a link that connects two nodes, call findLinksTo or findLinksBetween. With the former method, the direction matters; with the latter method it returns links in either direction.

As links connect with a node or are disconnected, you may want to update the appearance of the node. You can set the linkConnected and linkDisconnected properties to be functions that are called. These functions must not modify any link relationships -- the properties just exist to update the appearance of the node. A typical usage would be to change the color or figure of a shape.

You can control whether the user may draw a new link or reconnect a link between a pair of Nodes by affecting the result of LinkingBaseTool.isValidLink. You can override that predicate on LinkingTool and RelinkingTool, but it is easier to set the linkValidation or LinkingBaseTool.linkValidation functional property.

For a more general discussion of validation, see Introduction to Validation.

Nodes also support the ability to provide logical and physical distinctions in the connection points that links use at a node. These connection objects are called "ports". By default the port object will be the whole Node. However, you can set the GraphObject.portId property on any GraphObject in the visual tree of a node to cause that element to be treated as a "port". The "port id" is just a string that ought to be unique amongst all of the port elements in the node.

In the case of a node only having a single port, you should set the GraphObject.portId as an empty string. When there is no such element declared as the default port, it uses the whole node. You can use the port property to get the only port element.

When a node should have multiple ports, i.e. multiple GraphObjects acting as separate connection points for links, you should set each port's GraphObject.portId to a string value that is unique for the node. When there may be multiple ports on a node, you can get a collection of elements representing ports by using the ports property. Use the findPort method to find a particular port element by name.

Note: the only kind of model that can save port information, i.e. portIds that are not an empty string, for links is a GraphLinksModel whose GraphLinksModel.linkFromPortIdProperty and GraphLinksModel.linkToPortIdProperty have been set to name properties on the link data objects.

For a more general discussion of ports, see Introduction to Ports.

All of the "findLinks..." and "findNodes..." methods mentioned above take an optional port id argument. When no argument is passed, these methods consider all links connecting with the node. When a port id argument is provided, these methods only consider links that connect with that port in the given node. Thus when navigating through the diagram, you can easily look at all of the nodes that links coming out of a given node go to. Or you can just look at those nodes at the ends of links coming out of a particular port.

You can also control the default connecting behavior of Links at each port. Because a port can be any GraphObject, they are all properties on GraphObject. The properties are duplicated so that you can guide the "from" ends of links differently from the "to" ends of links. The properties include:

The "...Spot" and "...Length" properties control the position and routing of links at a port. The "...Linkable..." and "...MaxLinks" properties control whether or not users can draw a new link or reconnect an existing link from or to a port. (The "...Spot" and "...Length" properties also exist on Link, to override for a particular link the default values that come from a port element.)

For a more general discussion of link points, see Introduction to Link Connection Points.

When the graph is tree-structured, you can use several functions for traversing the tree:

Determining whether a tree grows from the root via links that go out to the children or vice-versa is controlled for the whole diagram by the Diagram.isTreePathToChildren property. However an individual link will be ignored by the above functions if Link.isTreeLink is false.

The Node class also supports the notion of expanding and collapsing a subtree of nodes and links, causing those nodes and links to be shown or hidden. Principally this is a matter of setting Node.isTreeExpanded. Of course if the diagram's graph is not tree-structured, these concepts and properties might not apply.

If you want to change the appearance of the node you can do so in a function that you assign to the treeExpandedChanged property. This function must not modify any link relationships or expand or collapse any subtrees -- the property just exists to update the appearance of the node.

There is an option for link routing to try to avoid crossing over nodes: Link.routing = Link.AvoidsNodes. You can control whether such links should avoid or ignore a node by setting avoidable. Set avoidableMargin to control the area beyond the GraphObject.actualBounds where AvoidsNodes links should not go.

For more discussion and examples, see Nodes, Ports, and Link Points.

For more about trees, see Trees, and SubTrees.

To customize user-resizing behavior, please read Introduction to the ResizingTool. To customize user-rotating behavior, please read Introduction to the RotatingTool.

Only Nodes that are in Diagrams can have connections via Links. Templates should not be connected with Links, be labels of Links, be members of Groups, or have any Adornments.

Index

Inherited Members

Properties

Methods

Constructors

  • Constructs an empty Node of the given type. Default type is Panel.Position. The panel type must be one of the enumerated values defined on the Panel class, including: Panel.Position, Panel.Vertical, Panel.Horizontal, Panel.Table, Panel.Auto, Panel.Spot, or Panel.Viewbox. The string value such as "Auto" may also be used.

    Usage example:

    // Constructs a Node, sets properties on it,
    // adds a data binding to it,
    // and adds two GraphObjects to the Node:
    const n = new go.Node("Auto", {
    margin: 5,
    background: "red"
    })
    .bind("location", "loc")
    .add(new go.Shape("RoundedRectangle"))
    .add(new go.TextBlock("Some Text"))

    Parameters

    • Optional type: string | PanelLayout

      Panel Type as either a string or PanelLayout. such as "Vertical", "Auto", or Panel.Vertical, Panel.Auto, are accepted. If not supplied, the default Panel type is "Position".

    • Optional init: Partial<Node>

      Optional initialization properties.

    Returns Node

  • Constructs an empty Panel. Default type is Panel.Position.

    Parameters

    • Optional init: Partial<Node>

      Optional initialization properties.

    Returns Node

Properties

  • Gets or sets the margin around this Node in which avoidable links will not be routed.

    You may need to increase the fromEndSegmentLength and toEndSegmentLength in order to prevent link routes from turning within the avoidable area around the Node.

    Value must be of type Margin. The default margin is Margin(2,2,2,2)

  • This read-only property is true when this Node is a label node for a Link.

    If this is true, then n.labeledLink will be a Link and n.labeledLink.isLabeledLink will be true.

    see

    labeledLink

  • Gets or sets whether the subtree graph starting at this node is expanded. Changing this property's value will call collapseTree or expandTree, and also will call the value of treeExpandedChanged if it is a function.

    The initial value is true -- "tree-child" nodes, and the links to them, are shown.

    There is an analogous property for expanded/collapsed Groups: Group.isSubGraphExpanded.

  • Gets whether this node has no tree children.

    The initial value is true, meaning that there are no links connected with child nodes in the direction given by Diagram.isTreePathToChildren. This value changes automatically as link connections are added to or removed from this node. Links for which Link.isTreeLink is false are ignored.

  • Gets or sets the Link for which this Node is acting as a smart label. Most nodes do not act as link labels, so this property will be null.

    A template should not be a label node for a link.

    see

    isLinkLabel

  • Gets or sets the function that is called after a Link has been connected with this Node. It is typically used to modify the appearance of the node. The first argument will be this Node. The second argument will be a Link that is now connected with this node. The third argument will be a GraphObject port indicating which port the link was connected with.

    If the value is a function, that function must not modify what this Node is connected with. The Link has already been added -- trying to remove it or another link may produce undefined behavior. However, the other end of the link may not yet have been connected with a node (and might never be), so you cannot depend on looking at what the link connects with.

    The default value is null -- no function is called.

  • Gets or sets the function that is called after a Link has been disconnected from this Node. It is typically used to modify the appearance of the node. The first argument will be this Node. The second argument will be a Link that had been connected with this node. The third argument will be a GraphObject port indicating which port the link had been connected with.

    If the value is a function, that function must not modify what this Node is connected with. The Link has already been removed -- trying to add it or another link may produce undefined behavior. The other end of the link may not yet have been disconnected from a node (and might never be), so you cannot depend on looking at what the link connects with.

    The default value is null -- no function is called.

  • Gets or sets a predicate that determines whether or not a Link may be connected with this node. If this is non-null, the predicate is called in addition to the predicate that is LinkingBaseTool.linkValidation on the LinkingTool and RelinkingTool. See LinkingBaseTool.isValidLink for more details.

    The default predicate is null, which is equivalent to simply returning true. The first argument will be the proposed "from" Node (may be null). The second argument will be the proposed "from" GraphObject port (may be null). The third argument will be the proposed "to" Node (may be null). The fourth argument will be the proposed "to" GraphObject port (may be null). The fifth argument may be null when asking about creating a new link, or may be a Link when asking about reconnecting an existing link.

    The function, if supplied, must not have any side-effects.

    since

    1.3

  • This read-only property returns an iterator over all of the Links that are connected with this node. This includes both links that are coming out of this node as well as links that are going into this node. Setting Link.fromNode or Link.toNode to refer to this Node will add that Link to this collection.

    Use the findLinksConnected, findLinksOutOf, or findLinksInto methods to get different subsets of the links, depending on direction or depending on connecting to a particular port.

    A template should not have any links connected with it.

  • This read-only property returns the primary GraphObject representing a port in this node. If there is a GraphObject whose GraphObject.portId is the empty string, return it. If there is no such element, just return this whole Node.

  • This read-only property returns an iterator over all of the GraphObjects in this node that act as ports.

  • Gets or sets the function that is called when isTreeExpanded has changed value. The argument to that function will be this Node.

    If the value is a function, that function must not expand or collapse any trees of nodes and links. The Node has already been expanded or collapsed -- trying to change it again may produce undefined behavior.

    The default value is null -- no function is called.

  • Gets or sets whether the subtree graph starting at this node had been collapsed by a call to expandTree on the parent node. The initial value is false.

    see

    isTreeExpanded

Methods

  • collapseTree(level?: number): void
  • Hide each child node and the connecting link, and recursively collapse each child node. This changes the value of Part.isVisible of the whole subtree and the parts owned by those nodes and links. However, this root node's visibility is unchanged.

    Links are assumed to go from the parent node to the children nodes, unless Diagram.isTreePathToChildren is false. Links for which Link.isTreeLink is false are ignored.

    This sets isTreeExpanded to false on this node and on all of the children nodes. For those child nodes that were expanded when they were collapsed, wasTreeExpanded is set to true.

    You can also pass in a number of levels to hide nodes beyond a certain level starting at this node. If you want to make sure that all nodes are expanded up to a particular level, call expandTree. If you want to do both, call expandTree before calling collapseTree to collapse nodes expanded due to the wasTreeExpanded flag.

    This method does not perform a transaction or start any animation. You may want to call the CommandHandler.collapseTree command, which does perform a transaction and raise a DiagramEvent.

    To collapse a Group's subgraph of Nodes and Links, use Group.collapseSubGraph.

    see

    expandTree, findTreeParts

    Parameters

    • Optional level: number

      How many levels of the tree, starting at this node, to keep expanded if already expanded; the default is 1, hiding all tree children of this node. Values less than 1 are treated as 1.

    Returns void

  • expandTree(level?: number): void
  • Show each child node and the connecting link, and perhaps recursively expand their child nodes. This may change the value of Part.isVisible of the whole subtree and the parts owned by those nodes and links. However, this root node's visibility is unchanged.

    This sets isTreeExpanded to true on this node and on all of the children nodes. Links are assumed to go from the parent node to the children nodes, unless Diagram.isTreePathToChildren is false. Links for which Link.isTreeLink is false are ignored.

    This will expand a tree child node only if its wasTreeExpanded property was true.

    You can also pass in a number of levels in order to be sure that all nodes starting at this node and up through that number of levels are visible. If you want to make sure that there are no nodes expanded after a particular level, call collapseTree. If you want to do both, call expandTree before calling collapseTree to collapse nodes expanded due to the wasTreeExpanded flag.

    This method does not perform a transaction or start any animation. You may want to call the CommandHandler.expandTree command, which does perform a transaction and raise a DiagramEvent.

    To expand a Group's subgraph of Nodes and Links, use Group.expandSubGraph.

    see

    collapseTree, findTreeParts

    Parameters

    • Optional level: number

      How many levels of the tree should be expanded; the default is 2, showing all tree children of this node and potentially more. Values less than 2 are treated as 2.

    Returns void

  • Find the Node that is the perhaps indirect tree parent of both this node and another one, or this node if it is an ancestor of the other node, or vice-versa.

    If you want to find the Group that contains two Parts, call Part.findCommonContainingGroup.

    see

    findTreeRoot, findTreeParentChain

    since

    1.5

    Parameters

    Returns Node

    may be null if in different trees, or may be itself if the OTHER argument is THIS node, or may be itself if the OTHER node is a descendant of THIS node, or may be the OTHER node if THIS node is in the tree of the OTHER node.

  • Return a collection of Links that connect with this Node or any in its subtree, excluding any isTreeLink Links. For trees this is the analog of Group.findExternalLinksConnected for Groups.

    since

    2.2

    Returns Iterator<Link>

  • findLinksBetween(othernode: Node, pid?: string, otherpid?: string): Iterator<Link>
  • Returns an iterator over all of the Links that go from this node to another node or vice-versa, perhaps limited to a given port id on this node and a port id on the other node.

    If you want all of the links between two nodes in just one direction, use findLinksTo.

    since

    1.2

    Parameters

    • othernode: Node
    • Optional pid: string

      A port identifier string; if null the link's portId is ignored and all links are included in the search.

    • Optional otherpid: string

      A port identifier string; if null the link's portId is ignored and all links are included in the search.

    Returns Iterator<Link>

  • Returns an iterator over all of the Links that connect with this node in either direction, perhaps limited to the given port id on this node.

    Parameters

    • Optional pid: string

      A port identifier string; if null the link's portId is ignored and all links are included in the search.

    Returns Iterator<Link>

  • Returns an iterator over all of the Links that go into this node, perhaps limited to the given port id on this node.

    Parameters

    • Optional pid: string

      A port identifier string; if null the link's portId is ignored and all links are included in the search.

    Returns Iterator<Link>

  • Returns an iterator over all of the Links that come out of this node, perhaps limited to the given port id on this node.

    Parameters

    • Optional pid: string

      A port identifier string; if null the link's portId is ignored and all links are included in the search.

    Returns Iterator<Link>

  • Returns an iterator over all of the Links that go from this node to another node, perhaps limited to a given port id on this node and a port id on the other node.

    If you want all of the links between two nodes in both directions, use findLinksBetween.

    since

    1.2

    Parameters

    • othernode: Node
    • Optional pid: string

      A port identifier string; if null the link's portId is ignored and all links are included in the search.

    • Optional otherpid: string

      A port identifier string; if null the link's portId is ignored and all links are included in the search.

    Returns Iterator<Link>

  • Returns an iterator over the Nodes that are connected with this node in either direction, perhaps limited to the given port id on this node.

    The results may include this node itself if there is a reflexive link connecting this node with itself.

    Parameters

    • Optional pid: string

      A port identifier string; if null the link's portId is ignored and all links are included in the search.

    Returns Iterator<Node>

  • Returns an iterator over the Nodes that are connected with this node by links going into this node, perhaps limited to the given port id on this node.

    Parameters

    • Optional pid: string

      A port identifier string; if null the link's portId is ignored and all links are included in the search.

    Returns Iterator<Node>

  • Returns an iterator over the Nodes that are connected with this node by links coming out of this node, perhaps limited to the given port id on this node.

    Parameters

    • Optional pid: string

      A port identifier string; if null the link's portId is ignored and all links are included in the search.

    Returns Iterator<Node>

  • Find a GraphObject with a given GraphObject.portId. If no such GraphObject is found, search for one with the empty string as its port identifier. Finally, when failing to find a port with either the given name or the empty string, this method returns this whole node itself.

    Parameters

    • pid: string

    Returns GraphObject

  • findTreeLevel(): number
  • Return a collection of Parts including this Node, its tree parent link and node, and so on up the chain to the root node.

    This calls findTreeParentLink and findTreeParentNode. Links for which Link.isTreeLink is false are ignored.

    This may result in undefined behavior if there are cycles of Links that are Link.isTreeLink.

    The result will include this node and the "root" node and all nodes and links in between. The root node is also accessible directly via findTreeRoot. If any of the nodes are Groups, their member parts are not included.

    see

    findTreeRoot, findTreeParts

    since

    1.7

    Returns Set<Part>

    A Set of Nodes and Links.

  • findTreeParentLink(): Link
  • findTreeParentNode(): Node
  • findTreeParts(level?: number): Set<Part>
  • Return a collection of Parts including this Node, all of the Links going to child Nodes, and all of their tree child nodes and links. Links for which Link.isTreeLink is false are ignored.

    Whether child nodes are found for a parent node by following links out of the parent node or by links coming into the parent node is determined by the value of Diagram.isTreePathToChildren.

    The result will include this, the "root" node. If any of the nodes are Groups, their member parts are not included.

    If you want to find the collection of Parts that are contained by a Group, use Group.findSubGraphParts.

    see

    findTreeChildrenNodes, findTreeChildrenLinks, findTreeParentChain

    Parameters

    • Optional level: number

      How many levels of the tree, starting at this node, to include; the default is Infinity, including all tree children of this node. Values less than 1 are treated as 1.

    Returns Set<Part>

    A Set of Nodes and Links.

  • findTreeRoot(): Node
  • findVisibleNode(): Node
  • Starting with this node, walk up the chain of containingGroups to find a node that is visible. This can be overridden to find a tree-parent/ancestor if the reason that this node is not visible is because of a collapsed tree rather than a collapsed group.

    since

    2.2

    Returns Node

  • isInTreeOf(node: Node): boolean
  • This predicate is true if this node is a child of the given Node, perhaps indirectly as a descendant.

    If this node is a child of the given node according to Diagram.isTreePathToChildren, this returns true. Otherwise this searches recursively the chain of tree parents of this node, ignoring links for which Link.isTreeLink is false. A node cannot be in its own subtree.

    If you what to find out whether this Node is (perhaps indirectly) contained by a Group, use Part.isMemberOf.

    see

    findTreeRoot, findTreeParentChain

    Parameters

    • node: Node

      the Node that might be a parent or ancestor of this node.

    Returns boolean

    true if the given node is an ancestor of this node, but false otherwise, including false if it is the same node.

Constants

This default value for Node.portSpreading indicates that links connecting with a port should be distributed evenly along the side(s) indicated by a Spot that is Spot.isSide.

This value for Node.portSpreading indicates that links connecting with a port should all connect at a single point on the side(s) indicated by a Spot that is Spot.isSide.

This value for Node.portSpreading indicates that links connecting with a port should packed together based on the link's shape's width on the side(s) indicated by a Spot that is Spot.isSide.