Class TreeModel<NodeDataType, SharedDataType>

Add an item at the end of a data array that may be data bound by a Panel as its Panel.itemArray, in a manner that can be undone/redone and that automatically updates any bindings.

This also calls raiseChangedEvent to notify all listeners about the ChangeType.Insert.

If you want to add a new node or part to the diagram, call addNodeData.

Register an event handler that is called when there is a ChangedEvent.

This registration does not raise a ChangedEvent. In case a Diagram's Model may be replaced, you may prefer calling Diagram.addModelChangedListener instead of this method.

Event listeners are not written out by toJson.

Do not add or remove Changed listeners during the execution of a Changed listener.

When you want to add a node or group to the diagram, call this method with a new data object. This will add that data to the nodeDataArray and notify all listeners that a new node data object has been inserted into the collection.

To remove a node from the diagram, you can remove its data object by calling removeNodeData.

To add or remove an object or value from an item array, call insertArrayItem or removeArrayItem.

Add to this model all of the node data held in an Array or in an Iterable of node data objects.

Modify this model by applying the changes given in an "incremental" model change in JSON format generated by toIncrementalJson. The expected properties of the argument are described at toIncrementalJson. Incremental changes must be applied in the same order that the changes occurred in the original model.

This requires the "incremental" property to be present and to be a number, as specified by toIncrementalJson. All of the top-level properties in the JSON, such as nodeKeyProperty, must be the same as for this model. Note that if the model is a GraphLinksModel, you will have to have set GraphLinksModel.linkKeyProperty to the name of a property, the same both in the Diagram.model as well as in the data that you pass to this method.

This conducts a transaction.

This is similar to Object.assign, but safely calls set for each property other than a key property. This does not delete any properties on the DATA object, although properties may be set to undefined if they are set that way on the PROPS object.

Clear out all references to any model data. This also clears out the UndoManager, so this operation is not undoable. This method is called by Diagram.clear; it does not notify any Diagrams or other listeners. This method does not unregister any Changed event listeners.

Instead of calling this method, you may prefer to set nodeDataArray to an empty JavaScript Array. If this model is a GraphLinksModel, you would also want to set GraphLinksModel.linkDataArray to a separate empty JavaScript Array.

Deeply copy an object or array and return the new object. This is typically called on a nodeDataArray or GraphLinksModel.linkDataArray or data objects within them.

By default, this method will make deep clones of arrays and JavaScript objects and maintain any shared or cyclic references. It will properly copy any Date or RegExp object, and will call a copy function on any object where one exists. It also handles certain GoJS classes: Point, Size, Rect, Margin, Spot, List, Set, and Map. It will not handle instances of Diagram, Layer, GraphObject, Tool, CommandHandler, AnimationManager or subclasses or related classes.

This method may be overridden. Please read the Learn page on Extensions for how to override methods and how to call this base method. Only override this method when the default behavior doesn't suit the data.

Starts a new transaction, calls the provided function, and commits the transaction. Code is called within a try-finally loop. If the function does not return normally, this rolls back the transaction rather than committing it. Example usage:

model.commit(m => m.addNodeData({ counter: myCounter++ }), "Added Node");
Copy

Note that setting skipsUndoManager to true for a nested transaction will prevent model changes from being recorded, but if Diagram.skipsUndoManager is still false during an outer transaction, any Diagram changes will still be recorded.

Commit the changes of the current transaction. This just calls UndoManager.commitTransaction.

Decide if a given node data object is in this model, using reference equality.

If you do not have a reference to the particular data object that is in the nodeDataArray, you may need to search for it by iterating through that Array, or by finding the desired Node or simple Part in a Diagram and getting that node's Panel.data, or most likely by calling findNodeDataForKey.

Given a number or string, find the node data object in this model that uses the given value as its unique key.

Find the category of a given node data, a string naming the node template or group template or part template that the Diagram should use to represent the node data.

Given a node data object return its unique key: a number or a string. This returns undefined if there is no key value.

It is possible to change the key for a node data object by calling setKeyForNodeData.

Add an item to a data array that may be data bound by a Panel as its Panel.itemArray, given a new data value and the index at which to insert the new value, in a manner that can be undone/redone and that automatically updates any bindings.

This also calls raiseChangedEvent to notify all listeners about the ChangeType.Insert.

If you want to add a new node or part to the diagram, call addNodeData.

This method is called when a node data object is added to the model to make sure that getKeyForNodeData returns a unique key value.

The key value should be unique within the set of data managed by this model: nodeDataArray. If the key is already in use, this will assign an unused number to the nodeKeyProperty property on the data.

If you want to customize the way in which node data gets a unique key, you can set the makeUniqueKeyFunction functional property.

If the node data object is already in the model and you want to change its key value, call setKeyForNodeData and give it a new unique key value.

Take an Array of node data objects and update nodeDataArray without replacing the Array and without replacing any existing node data objects that are identified by key.

For node data objects that have the same key value, this makes calls to set to update the existing node data object. For new keys, this calls cloneDeep to copy the data and then addNodeData to add a new node to the model. For existing nodes that have keys that are not present in the given Array, this calls removeNodeData to remove the existing node from the model.

This method is typically used when GoJS is being used within an application that is maintaining state related to the diagram model. When state is updated, this method can be called to keep the GoJS model synchronized. Any updates to the data should use new references since this method will use reference equality to check if a node data object needs to be updated.

This method does not conduct a transaction.

Call this method to notify that the model or its objects have changed. This constructs a ChangedEvent and calls all Changed listeners.

Call this method to notify about a data property having changed value. This constructs a ChangedEvent and calls all Changed listeners.

You should call this method only if the property value actually changed. This method is called by set.

Remove an item from a data array that may be data bound by a Panel as its Panel.itemArray, given the index at which to remove a data value, in a manner that can be undone/redone and that automatically updates any bindings.

This also calls raiseChangedEvent to notify all listeners about the ChangeType.Remove.

If you want to remove a node from the diagram, call removeNodeData.

Note that there is no version of this method that takes an item value instead of an index into the array. Because item arrays may hold any JavaScript value, including numbers and strings, there may be duplicate entries with that value in the array. To avoid ambiguity, removing an item from an array requires an index.

Unregister an event handler listener.

This deregistration does not raise a ChangedEvent. In case a Diagram's Model may be replaced, you may prefer calling Diagram.removeModelChangedListener instead of this method.

When you want to remove a node or group from the diagram, call this method with an existing data object. This will remove that data from the nodeDataArray and notify all listeners that a node data object has been removed from the collection.

If you do not have a reference to the particular data object that is in the nodeDataArray, you may need to search for it by iterating through that Array, or by finding the desired Node or simple Part in a Diagram and getting that node's Panel.data, or most likely by calling findNodeDataForKey.

Removing a node data from a model does not automatically remove any connected link data from the model. Removing a node data that represents a group does not automatically remove any member node data or link data from the model.

To add a node to the diagram, you can add its data object by calling addNodeData.

To add or remove an object or value from an item array, call insertArrayItem or removeArrayItem.

Remove from this model all of the node data held in an Array or in an Iterable of node data objects.

Rollback the current transaction, undoing any recorded changes. This just calls UndoManager.rollbackTransaction.

Change the category of a given node data, a string naming the node template or group template or part template that the Diagram should use to represent the node data.

Changing the node template for a node data will cause the existing Node, Group, or Part to be replaced with a new instance of the same class created by copying the new node template and applying any data-bindings. That means that the templates in the Diagram.nodeTemplateMap or Diagram.groupTemplateMap must be instances of the same class -- one cannot convert a Node into a Group or vice-versa by setting the category.

Binding sources should not be (or depend in a conversion function on) the category of the data if you might be modifying the category, because then some bindings might be evaluated before or after the category has been changed.

A synonym for set

Change the unique key of a given node data that is already in this model. The new key value must be unique -- i.e. not in use by another node data object. You can call findNodeDataForKey to check if a proposed new key is already in use.

This operation will check all data objects in the model and replace all references using the old key value with the new one.

If this is called on a node data object that is not (yet) in this model, this unconditionally modifies the property to the new key value.

Begin a transaction, where the changes are held by a Transaction object in the UndoManager. This just calls UndoManager.startTransaction.

Produce an object representing the changes in the most recent Transaction. The structure of the object follows the same format as the JSON output from toIncrementalJson.

Note that these incremental changes include the results of undo and redo operations.

For GraphLinksModels, this method requires that GraphLinksModel.linkKeyProperty is not an empty string. If GraphLinksModel.linkKeyProperty is the empty string, that property will automatically be set to "key", and each link data object will get a unique key value, before producing the resulting data.

Any node or link data objects contained in the "modified..." properties will be deep copies of the data in the model. The objects will contain proper copies of certain GoJS classes, and some common built-in objects such as Dates and RegExps. Other classes will just be copied as plain Javascript objects, so it is best to avoid using special classes in one's data.

This method is most commonly used when GoJS must communicate with some external data source and maintain integrity between the two while avoiding serialization/deserialization.

  myDiagram.addModelChangedListener(e => {
    if (e.isTransactionFinished) {
      const dataChanges = e.model.toIncrementalData(e);
      ... update React state/save to database ...
    }
  });
Copy

Caution: don't call JSON.stringify on the resulting object, because that will not properly handle any instances of JavaScript classes that are referenced by the object's properties. Instead call toIncrementalJson, which will produce a more compact textual serialization.

Produce a JSON-format string representing the changes in the most recent Transaction. This writes out JSON for a model, but recording only changes in the given Transaction, with the addition of the "incremental" property to mark it as different from a complete model. Instead of the "nodeDataArray" property (and "linkDataArray" property for GraphLinksModels), this will have "inserted...", "modified...", and "removed..." properties that are non-empty Arrays.

The "modifiedNodeData" Array holds JavaScript objects. The "insertedNodeKeys" and "removedNodeKeys" Arrays hold keys (numbers or strings) of data, not whole objects, that have been added and/or deleted. The "modelData" property holds the Model.modelData object, if it was modified.

Note that it is entirely plausible for the same object be in or referenced by all three Arrays, because a single Transaction can include adding a node, modifying it, and removing it.

The purpose of this method is to make it easier to send incremental changes to the server/database, instead of sending the whole model. Whereas it has always been easy to perform "batch" updates or "file saves":

  myDiagram.addModelChangedListener(e => {
    if (e.isTransactionFinished) {
      const json = e.model.toJson();
      // save the whole model upon each transaction completion or undo/redo
      ... send to server/database ...
    }
  });
Copy

You can now easily send "incremental" updates:

  myDiagram.addModelChangedListener(e => {
    if (e.isTransactionFinished) {
      const json = e.model.toIncrementalJson(e);
      // record each Transaction as a JSON-format string
      ... send to server/database ...
    }
  });
Copy

Note that these incremental changes include the results of undo and redo operations. Also, when you might call applyIncrementalJson, you will need to disable your Changed listener, so that it does not send spurious changes to your database during the process of apply incremental changes from the database.

For GraphLinksModels, this method requires that GraphLinksModel.linkKeyProperty is not an empty string. If GraphLinksModel.linkKeyProperty is the empty string, that property will automatically be set to "key", and each link data object will get a unique key value, before producing the resulting text. The incremental JSON for GraphLinksModels will include "modifiedLinkData", "insertedLinkKeys", and "removedLinkKeys" properties that are non-empty Arrays.

The same restrictions on data property names and data property values applies to this method as it does to toJson.

Generate a string representation of the persistent data in this model, in JSON format, that can be read in later with a call to Model.fromJson.

Object properties that are not enumerable or whose names start with "_" are not written out.

Functions are not able to be written in JSON format, so any properties that have function values will not be saved in the JSON string.

There must not be any circular references within the model data. Any sharing of object references will be lost in the written JSON.

Most object classes cannot be serialized into JSON without special knowledge and processing at both ends. The toJson and Model.fromJson methods automatically do such processing for numbers that are NaN and for objects that are of class Point, Size, Rect, Margin, Spot, Brush (but not for brush patterns), and for Geometry. For instances of those classes, special objects are written out with a property named "class" whose value will be one of the special cases that will be substituted by Model.fromJson: "NaN", "Date", "go.Point", "go.Size", "go.Rect", "go.Margin", "go.Spot", "go.Brush", "go.Geometry".

However, we recommend that you use Binding converters (static functions named "parse" and "stringify") to represent Points, Sizes, Rects, Margins, Spots, and Geometries as string values in your data, rather than as Objects. This makes the JSON text smaller and simpler and easier to read.

As a special case when serializing an object, if the property is named "points" and the property value is a List of Points, it will write an Array of numbers.

Note that this is a method on the Model class. It cannot render unmodeled Parts such as the background grid or any Parts that you have added directly to a Diagram.

Typical usage:

const modelAsText = myDiagram.model.toJson();
// now save this text string by sending it to your database
Copy

Find a Part corresponding to the given data and call its Panel.updateTargetBindings method, in each Diagram that uses this Model.

Caution: setting a data property without calling set and then calling this updateTargetBindings method will update GraphObjects that are bound to the property, but such data settings will not be recorded in the UndoManager and therefore will not be undone/redone, causing an inconsistency between the GraphObjects and the part data.

This static function parses a string in JSON format that was written by Model.toJson, and then constructs, initializes, and returns a model with that information.

Note that properties with values that are functions are not written out by toJson, so reading in such a model will require constructing such a model, initializing its functional property values, and explicitly passing it in as the second argument.

In order to serialize instances of some classes and enumerated values and some other cases, Model.toJson writes out special Objects that this Model.fromJson function substitutes with the intended values. Those special objects will have a property named "class" whose value will be one of the special substitution cases: "NaN", "Date", "go.EnumValue" (for compatibility), "go.Point", "go.Size", "go.Rect", "go.Margin", "go.Spot", "go.Brush", "go.Geometry".

As a special case when deserializing an object, if the property is named "points" and the property value is an Array with an even number of numbers, it will substitute a List of Points.

Typical usage:

const modelAsText = ...;  // fetch the model in textual format from a database
myDiagram.model = go.Model.fromJson(modelAsText);
Copy