Class Node

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:

• GraphObject.fromSpot, GraphObject.toSpot
• GraphObject.fromEndSegmentLength, GraphObject.toEndSegmentLength
• GraphObject.fromShortLength, GraphObject.toShortLength
• GraphObject.fromLinkable, GraphObject.toLinkable
• GraphObject.fromLinkableDuplicates, GraphObject.toLinkableDuplicates
• GraphObject.fromLinkableSelfNode, GraphObject.toLinkableSelfNode
• GraphObject.fromMaxLinks, GraphObject.toMaxLinks

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:

• findTreeParentNode
• findTreeChildrenNodes
• findTreeParentLink
• findTreeChildrenLinks
• findTreeRoot
• findTreeParentChain
• findTreeParts
• findCommonTreeParent
• isInTreeOf
• findTreeLevel

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.