Skip to main content
  1. Index

GraphObject manipulation

Programmatically interacting with Nodes

This guide will show you some basic ways of programmatically interacting with GoJS nodes and links and model data. Throughout this page, we will use the following diagram setup as our starting point:

Finding single nodes: Diagram.findNodeForKey

You can use Diagram.findNodeForKey(key) to get a reference to a Node in JavaScript. Key values in GoJS can be either strings or numbers. You can then use the Node reference to inspect and manipulate the Node or its data.

js

However Diagram.findNodeForKey may return null if no node data object uses that key value. It only looks at the model to find a node data object that uses the given key value, from which it finds the corresponding Node in the Diagram. It does not look at the text values of any TextBlocks that are within the nodes, so it can work even if no text is shown at all, or if the node is not visible. And it does not look at any programmatically added parts that were not created from model data, such as titles or legends.

Once you have a Node, you can get its key either via the Node.key property or by looking at its data: someNode.data.key, just as you can look at any of the data properties.

Diagrams have several properties and methods that return GoJS iterators describing collections of Parts. Both Nodes and Links are kinds of Parts. Diagram.nodes and Diagram.links return iterators of all Nodes and Links in the Diagram, respectively. Diagram.selection returns an iterator of selected Parts (both selected Nodes and selected Links).

There are also more specific methods for common operations, such as Diagram.findTreeRoots which returns an iterator of all top-level Nodes that have no tree-parent node.

This next example uses Diagram.nodes and shows how to iterate over the collection.

js

As a result we have very scaled-down nodes, except for Beta:

Named GraphObjects and Panel.findObject

Often we want to manipulate a property that belongs to one of the Node's elements, perhaps an element arbitrarily deep in the template. In our example Diagram, each Node has one Shape, and if we want to change the color of this Shape directly we would need a reference to it. To make it possible to find, we can give that Shape a name:

js

Names allow us to easily find GraphObjects inside of Panels (all Nodes are also Panels) using Panel.findObject, which will search the visual tree of a Panel starting at that panel. So when we have a reference to a Node, we can call someNode.findObject("SomeName") to search through the node for a GraphObject with that name. It will return a reference to the named GraphObject if it is found, or null otherwise.

Using this, we could make an HTML button that changes the fill of the Shape inside of a selected Node:

js

Changing properties and updating the Model using data bindings

Looking again at our Node template, we have the Shape.fill property data-bound to the "color" property of our Node data:

js

Changing the Shape's fill property inside our node will not, as the Node template currently stands, update the model data.

js

This is undesirable in many cases. When we want the change to persist after saving and loading, we will want the model data updated too.

However, in some situations this lack of persistence might be a good thing. For instance if we want the color change for only cosmetic purposes, such as changing the color of a button when hovering over it with the mouse, we would not want to modify the model data that might be saved.

In this case, suppose that we do want to update the model. The preferred way to do this is to modify the data in the model and depend on the data binding to automatically update the Shape. However, we cannot modify the data directly by just setting the JavaScript property.

js

Instead we should set the data property using the method Model.set(data, propertyName, propertyValue). As always, changes should always be performed within a transaction. There should only be a single transaction for all changes that need to be made at the same time, from the user's point of view. A convenient way to perform a transaction is to call Model.commit.

js

Note that there is no longer any need to name the Shape "SHAPE", because there is no longer any need to call Panel.findObject to look for the particular Shape. Data binding will automatically update properties, so we do not have to do that ourselves.

js

Subjects mentioned and further reading

You may want to read more tutorials, such as the Learn GoJS tutorial and the Interactivity tutorial.

If you want to explore by example, have a look at the samples to get a feel for what's possible with GoJS.