Creating a plug-in that changes the colors of nodes

This tutorial takes you through writing a plug-in for the i2 Notebook web client that can change the color of nodes on a chart.

You can find a full version of the source code for this tutorial in the samples/color-plugin folder.

Prerequisities

This tutorial requires a running instance of i2 Analyze on which you have permission to use the i2 Notebook web client.

To follow the tutorial, you must install at least version 12 of Node.js on your development machine. For downloads and more information about Node.js, visit the project website at https://nodejs.org.

The tutorial also requires you to create GUIDs for a number of its elements. The project files use some sample fixed GUIDs (00000000-0000-0000-0000-000000000001, 00000000-0000-0000-0000-000000000002, and so on), but you should always create real GUIDs for real projects.

Note: A suitable GUID generator is available online at https://www.guidgenerator.com.

Create a basic plug-in

To arrive at the starting point for this tutorial, follow the instructions in the basic plug-in tutorial, up to but not including the section named Add a ribbon command to the plug-in.

In entrypoint.js, change the requested API version to 1.2:

const api = await notebook.getEntryPointApi('00000000-0000-0000-0000-000000000001', '1.2');

Make sure that you have a working plug-in before you continue.

Add a ribbon command

Starting from the essentially empty plug-in, we'll add a new command to the ribbon that will eventually change the color of nodes that contain vehicle records to the colors of those vehicles.

In entrypoint.js, just before the call to initializationComplete(), create a command and surface it on the Home tab:

const colorVehicleNodes = api.commands.createCommand({
  id: '00000000-0000-0000-0000-000000000002',
  name: 'Color vehicle nodes',
  type: 'application',
  icon: {
    type: 'inlineSvg',
    svg: '<svg viewBox="0 0 16 16"><rect width="8" height="8" x="4" y="4"/></svg>',
  },
  onExecute() {},
});

const homeTab = api.commands.applicationRibbon.homeTab;
const searchInfoStoreCommand = homeTab.systemGroups.searchInfoStore;

homeTab.after(searchInfoStoreCommand).surfaceCommands(colorVehicleNodes);

So far, this command is almost identical to the one that you would have added, if you had continued with the basic plug-in tutorial.

Reload i2 Notebook and check that the command is visible in the application ribbon.

Set node colors

To set the color of a node, we'll use a mutation (see Supported mutation operations) that requires the NodeSpecifier of the node, and the color to change the node to.

In the sections that follow, we will:

Find all records of the vehicle entity type on the chart.
Retrieve the color of the vehicle from each vehicle record.
Set each vehicle record's node element to the color of the vehicle.

Find all vehicle records on the chart

Elements on the chart surface are defined by and contain records that store data (see Record data). We can gain access to the chart and all the entity records via the argument of type app.IApplicationContents passed to the onExecute() event handler.

To determine whether a record has a particular type, we need to specify which type we're looking for! We'll search the item types in the chart's schema object (see Schema data) for the one that corresponds to vehicle records.

Specify the type identifier of the vehicle item type in the i2 Analyze schema.
Access the chart schema through the onExecute() application contents parameter, and get the chart item type that corresponds to that type identifier.
Access all of the chart entityRecords through the onExecute() application contents parameter.
Find the records with the vehicle item type.

If there are no vehicle records, just return.

const vehicleAnalyzeTypeId = 'ET3';
...
onExecute(applicationContents) {
   const vehicleItemType = applicationContents.chart.schema.getItemType(vehicleAnalyzeTypeId);

   const allEntityRecords = applicationContents.chart.entityRecords;

   const vehicleRecords = allEntityRecords.filter(
     (record) => record.itemType === vehicleItemType
   );
},
...

At this point, we now have all the vehicle type entity records, and we're ready to retrieve the color property for each record.

Retrieve a color from each vehicle record

We will now find the color for each vehicle. Instead of accessing the item types in the schema, we'll need to access the property types in the vehicle item type.

Specify the type identifier of the color property type of the vehicle item type.
Use the vehicleItemType object to get the property type that corresponds to that type identifier.
Gain access to mutations by calling api.runTrackedMutations() and setting a handler function.
Inside the mutation handler, loop over every vehicle entity record.

Use the color property type to retrieve the color of the vehicle that the record represents.

const vehicleColorAnalyzeTypeId = 'VEH9';
...
const colorPropertyType = vehicleItemType.getPropertyType(vehicleColorAnalyzeTypeId);

api.runTrackedMutations((_, mutations) => {
  for (const vehicleRecord of vehicleRecords) {
    const vehicleColor = vehicleRecord.getProperty(colorPropertyType);
    ...

Set the record's element to the color of the vehicle

Finally, for each vehicle record we found, we'll use a mutation to set the color of the node element that contains it to the color of the vehicle.

Retrieve the record's containing element using the element property.
Use the mutations parameter to call the editNode() method, and then the setColor() method.

Return an ITrackedMutationCommit object from the runTrackedMutations() method call.

...
api.runTrackedMutations((_, mutations) => {
  for (const vehicleRecord of vehicleRecords) {
    const vehicleColor = vehicleRecord.getProperty(colorPropertyType);

    const vehicleElement = vehicleRecord.element;
    mutations.editNode(vehicleElement.id).setColor(vehicleColor?.toString());
  }

  return {
    type: 'commit',
    actionDisplayName: 'Set vehicle node colors',
  };
});
...

Note: This implementation assumes that the vehicle color value in the record property is in a format that the setColor() method supports.

Now, if a chart contains one or more nodes with a vehicle record, clicking the ribbon button changes the color of all those nodes to their vehicle color.