Supported mutation operations

As Changing data from a plug-in describes, the i2 Notebook Web API provides the ability to write data to the chart and to change the state of the i2 Notebook application.

The types of changes that you can make through the API are:

  • Record creation
  • Record editing
  • Record removal
  • Item type creation
  • Item type editing
  • Selection changes
  • Node position changes
  • Node and edge style changes
  • View changes

A single mutation can contain any number of these changes, in any combination. The changes are typically applied when the mutation itself is committed.

The i2 Notebook SDK includes a mutations tutorial that demonstrates how to make some of these changes.

Creating and editing records

The mutation handler that you pass to IApplication.runTrackedMutations() can create entity and link records through the addEntityRecord() and addLinkRecord() methods of the ITrackedMutations object that it receives. To each method, you provide the features of the new record including its item type, its notes, its security settings, and values for its properties.

Both add methods return a "pending" record object that represents the new record in the mutation, before it is added to the chart. This object implements the IRecordEditor interface, which allows you to make further edits before you commit.

To make changes to a record that is already on the chart, you can use the ITrackedMutations.editRecord() method, which also returns an object that implements IRecordEditor.

Note: New records, and changes to existing records, do not exist on the chart (and will not be seen in IChart collections) until you commit the mutation. Pending records and record editors are only valid in the mutation handler where they were created.

Value factories

When you create or edit a record from a mutation handler, you can provide values for its properties. Some of these values - temporal and geospatial ones, for example - have reasonably complex structures. To help you construct valid values, ITrackedMutations.valueFactory provides an IValueFactory object that contains helper methods for creating objects of the following types:

  • IGeopoint
  • IDecimal
  • ILocalDate
  • ILocalDateTime
  • ILocalTime
  • ISecuritySettings
  • IZonedDateTime

Removing records and elements

Just as a mutation handler can create and edit records, it can also remove them from the chart, through the ITrackedMutations.removeRecords() method.

You can also remove visual nodes and edges from the chart by calling the ITrackedMutations.removeElements() method. Doing so implicitly removes any records that an element contains, while removing a node also removes any connected edges.

Creating and editing item types

When you create a record, you specify its item type. Often, you will use an item type that already exists in the chart schema, but you can also use a tracked mutation handler to create item types and to edit existing ones.

For item types that you create, you can configure their behavior and add and edit property types both during and after creation. For existing item types, you can only add or edit custom property types.

To create a custom entity type in the chart schema, you call the ITrackedMutations.addEntityType() method. To create a custom link type, you call ITrackedMutations.addLinkType().

You can use the ITrackedMutations.editItemType() method to modify the custom item types that you create, or to add custom property types to existing item types. There is no method to remove a custom item type, although you can use the undo action to reverse creation if you do so immediately afterwards.

For information about the item types that are added or changed in the chart schema, you can:

Changing selection

You can change the selection state of the chart through tracked and untracked mutation handlers. ITrackedMutations and IUntrackedMutations both inherit IMutationsBase.selection, which provides an implementation of the ISelectionEditor interface.

Note: Selection changes in untracked mutations are not explicitly added to the undo stack, but the next tracked mutation can capture the current selection as part of its undoable state.

Moving nodes on the chart

From a tracked mutation handler, you can arrange the nodes on the chart by changing their positions one-by-one, or as a group:

Changing the style of nodes and edges on the chart

You can change the visual appearance of node and edges displayed on a chart by using the ITrackedMutations.editNode() and ITrackedMutations.editEdge() methods.

Local style and label changes

You can use untracked mutations (IUntrackedMutations) to make local changes to the appearance of nodes and edges on the chart. Changes like these are not sent to the server, and exist only on the browser page displaying the current chart.

For example, you can set the label of an edge summary by using the IUntrackedMutations.editEdgeSummary().setLabel() method.

Untracked mutations are also not added to the undo/redo stack, which makes them useful in plug-ins that want to alter the appearance of chart elements temporarily without affecting the user's workflow.

If you want an untracked mutation to survive an undo operation, you can reapply it in response to a chartchange event.

Changing the view

Finally, you can use tracked or untracked mutations to change the current view of the chart by moving its center point or changing the zoom level.

ITrackedMutations and IUntrackedMutations both inherit IMutationsBase.view, which provides an implementation of the IViewEditor interface.

Validation

The parameters of all calls to mutation methods are validated to ensure that the correct value types are passed, and that any record and type identifiers are associated with existing objects.

A validation failure results in an error notification in the i2 Notebook user interface that provides information about which argument was incorrect.