Accessing data from a plug-in

The i2 Notebook Web API provides access to a range of information about the application as a whole, and the data on the chart in particular. In your plug-in code, you can use the API to retrieve this data, as well as to engage with the events happening on the chart. Often, you'll need to do both at the same time.

Application data

Data that's relevant to the whole application, such as user, theme, and locale data, is available through both the entry point API and the tool view API. Both extend the IApplication interface that defines precisely what information is available.

Because the API is asynchronous, however, it can take some time for application data to become available. A delay might be a problem when you are creating a tool view and you want to render something straight away, without waiting for the API. To address this issue, the i2 Notebook web client makes some application data available in the URL that it passes to a new tool view. Specifically, you can retrieve theme and locale data from the following query parameters:

?baseTextDirection
?flowDirection
?formattingLocale
?translationLocale
?themeName
?appearance

No matter how you access it, application data is stable and cannot become inconsistent. It is available to your plug-in code at all times, in any context where you need it.

Chart data

Unlike application data, the data in and around an i2 Notebook chart can change quickly. For example, users can add and remove records from the chart, or change the selection, or change what the current view contains.

To ensure that data does not change while you access or manipulate it from your plug-in code, you can only access chart data when i2 Notebook passes it to you in the arguments to callback methods.

You can register for the i2 Notebook web client to call your methods in three different circumstances:

As a handler for events that take place in the application, such as chart and selection changes
As a handler that runs when a user invokes a command through the user interface
As a handler that i2 Notebook calls when you specifically ask it to start a transaction

Most handlers can receive a payload that implements the IApplicationContents interface, which provides access to all of the schema, visual, and record data for the chart. Some handlers can also receive contextual data, such as information about the changes to records that caused the handler to be called.

Schema data

Every chart in the i2 Notebook web client has a set of schemas that define what types of records can appear on the chart, and the rules that govern records' properties, notes, and security settings.

In a handler that receives an application contents object, you can retrieve schema information from the IApplicationContents.chart.schema property.

Visual data

Visual data in the i2 Notebook web client comes in two flavors. First, there's what the chart itself looks like: its center, its extent, and its zoom level. That information is available as part of the application contents, through the IApplicationContents.chart.view property.

The second kind of visual data is about the elements - that is, the nodes and edges - that users interact with on the chart surface. This information is also available from the application contents, through IApplicationContents.chart.elements and other properties.

In addition to the application contents, some event handlers receive more specific visual data. For example, the payload of the chartselectionchange event includes an object that implements the ISelection interface, while the chartviewchange event provides direct access to the IChartView interface.

Record data

Every element on an i2 Notebook chart can contain records. Each record contains:

Property data
Metadata, including:
- Creation date and time
- Display name and principal name
Notes, source references, and security information

As with the other kinds of chart data, you can get information about all the records on the chart from the application contents, this time through IApplicationContents.chart.records and other properties.

But like the visual data, some event handlers also receive more specific record data. For example, for small changes to the chart, the payload of the chartchange event contains an object that contains the records (and the elements) that changed. Additionally, the onExecute() method that runs when a user invokes a command can receive an IRecordsContext object representing the records that were selected at the time.