The plug-in entry point

Every i2 Notebook plug-in has an entry point, which is a JavaScript file that the i2 Notebook web client runs when it starts up. The entry point is responsible for several important aspects of a plug-in's functionality, including:

  • Registering and surfacing commands
  • Registering tool views
  • Arranging access to chart data
  • Telling i2 Notebook that initialization of the plug-in is complete

Conventionally, the entry point file is named entrypoint.js, but you can choose its name and location when you specify it in the "entryPointUrl" field of the plug-in manifest.

Accessing the entry point API

To perform any of its tasks, the entry point must get access to the entry point API that the i2 Notebook web client makes available through the IEntryPointApi interface.

To access the interface, you use the getEntryPointApi() function, which you can call in one of two ways:

  • If you build the entry point file using a bundler such as webpack or parcel, you can import the getEntryPointApi() function directly from the @i2analyze/notebook-sdk package.

  • If you use an unbundled entry point file, you can call the getEntryPointApi() function on the global notebook object.

getEntryPointApi() is asynchronous. On completion, it returns an entry point API object, through which you can access the rest of the API.

Checking compatibility

When you call getEntryPointApi(), you can use the apiVersion parameter to check that the i2 Notebook web client you're communicating with supports the Notebook API version that you need. If the web client doesn't support the requested API version, you'll see an error message in the browser console.

For example, imagine that you've been using version 2.4 of the i2 Notebook SDK to develop your plug-in, but that you then attempt to use it with a client that supports supports only API version 2.3. Your call to getEntryPointApi() might look like this:

const api = await notebook.getEntryPointApi('00000000-0000-0000-0000-000000000000', '2.4');

This call will fail, because the web client doesn't support API version 2.4.

On the other hand, if your call to getEntryPointApi() specifies version 2.2, then the call will succeed and you'll receive an entry point object that supports version 2.3 of the API.

Note: Requesting API version 2.2 doesn't guarantee that the object you receive supports exactly that version. On success, getEntryPointApi() always returns the latest version of the API that the Notebook web client implements. New minor versions of the Notebook API are backward-compatible with old versions.

You can find out which version of the API an interface, a type, or other functionality was introduced in by checking for the Introduced keyword in the documentation or the @since indicator in the type definition file. For example:

/**
 * An example type.
 * @since Major.Minor
 */
export type Message = string;

See the related documentation topic for more information about i2's policy on SDK and API versioning.

Registering commands

The entry point is where you register the commands that your plug-in adds to the i2 Notebook web client user interface. You can arrange for a command to display a tool view that your plug-in implements, or to perform a task in its own right.

By integrating with the web client's event system, you can make commands appear in the application ribbon and the chart pop-up menu. And you can disable or enable commands according to the current context.

Registering tool views

The entry point is also where you register the tool views through which your plug-in can display its own user interface, inside the i2 Notebook web client.

Tool views consist of HTML pages and code for performing custom user tasks. In the entry point, you must provide the web client with the location of that code.

Accessing chart data

The IEntryPointApi interface provides full access to all chart data and metadata: the data that records contain, their visual representation, the schema that defines their types, and whether they are currently selected.

The same interface gives your plug-in code the ability to subscribe to events in the i2 Notebook web client, so that your code is called when data or selections change.

Entry point lifecycle

After the entry point file loads, it must perform command and tool view registrations quickly. The i2 Notebook web client blocks its startup until these registrations are complete, so that it can render its user interface in one go without elements shifting around.

When your registrations are complete, your entry point must call the initializationComplete() method on the IEntryPointApi interface. Failure to do so delays the start of the i2 Notebook web client, and causes your plug-in to be shut down. After the call to initializationComplete(), no further commands or tool views can be registered or surfaced.