Event Handlers in the Spotfire® API - A Minimal Example

Introduction

When programming for TIBCO Spotfire® using the C# API it is likely that there will at some point be a need to react to changes in the Document model in the analysis file, whether it is properties of the Document itself of if it is changes in the properties of a custom node that has been added as part of an extension to Spotfire.

Prerequisites

• Visual Studio 2013 or later
• TIBCO Spotfire® Analyst installation or Portable
• TIBCO Spotfire® Server
• TIBCO Spotfire® SDK

Document Model

The event system is designed around the document model, and is related to the undo/redo functionality in Spotfire. All properties that can trigger an event must be directly or indirectly based off of document node properties that are declared with the serializable attribute and implement the serializable interface. These properties are tighly related with the undo/redo system of Spotfire, as everything state that can be saved must be seralizable, including the undo/redo stack.

An indepth discussion about the document model, undoable properties and serialization is however out out of the scope for this article. Please see TIBCO Spotfire® Document Model Framework API for further details on the document model.

Document Nodes

The document model is a tree-structure consisting of document nodes. Creating an extension in Spotfire usually means to extend an abstract Custom* class that inherits from DocumentNode class but also adds specific base functionality, such as the CustomVisual class. It is also a common task to create custom nodes or custom container nodes by extending e.g. CustomNode class DocumentNodeList classes.

Document Properties

Once a document node has been defined the next step is to define document properties on the node that will be the origin of the event. Some node types in the document will already have properties and property names defined already.

This example declares a property for the Table property of the model class of the example and defined a property name in an inner PropertyNames class as

private readonly UndoableCrossReferenceProperty<DataTable> table;

...

public new abstract class PropertyNames : CustomNode.PropertyNames
{
    public static readonly PropertyName Table = CreatePropertyName("Table");
...
}

The property is then created in the constructor as below.

 CreateProperty(PropertyNames.Table, out table, default(DataTable));

It is now possible to create a Trigger for the Table property of the model class (see Triggers below).

The combined information of the document node (often refered to as the model class) whose changes will be listened to, and the relevant property name of will be used to create the Trigger needed to generate the change event. This allows for the construction of event relays (a logical node property that represents one or more properties on a node's sub-nodes).

Triggers and Events

For an event to occur in the first place, there must first be a trigger created for a specific property. In the most simple case the trigger factory method must know the owner node object of the propery and its property name to be able to create a trigger for the property we want to listen to changes on.

 Trigger.CreatePropertyTrigger(model,
     CustomWebPanelMarkingNode.PropertyNames.Table)

The above code snippet creates a trigger that will fire on any change of the models Table property (see example zip for full code example).

Please see Using Events with the TIBCO Spotfire® Document Model Framework API for further details on Spotfire events.

Event Handlers

There are two different types of event handlers available in the Spotfire API. External event handlers, for listening to changes to the document from UI components and internal event handlers for listening to changes to the document from another document node.

Internal Event Handlers

Internal event handlers are declared by overriding the DocumentNode's DeclareInternalEvent method.

protected override void DeclareInternalEventHandlers(InternalEventManager eventManager)
{
	base.DeclareInternalEventHandlers(eventManager);

	eventManager.AddEventHandler (MarkingChanged,                                           
		Trigger.CreateMutablePropertyTrigger<DataMarkingSelection> (
			this,
			PropertyNames.Marking,
			DataMarkingSelection.PropertyNames.Selection ) );
}

Internal event handlers are run before external eventhandlers and provide an opportunity make sure the document is in a consistent state before the UI is updated by external event handlers.

External EventHandlers

External eventhandlers enables a UI component, such as a dialog or a custom visual to react to changes in the document. They are registered by creating an ExternalEventManager instance and performing subsequent calls to the AddEventHandler method on the event manager instance.

It is good form to always provide a dispose method for any external event handlers. In the example above, adding the external eventmanager to the Windows Forms components collection, Windows will automatically dispose the event manager when the Form is disposed. If this is not done, the Dispose() method needs to be defined manually.

Sample Project

The attached sample project consists of a VisualStudio solution with a custom web panel implementation. It will react to marking changes and display wikipedia pages generated from a user specified columns data.

There are two projects in the visual studio project

1. CustomWebPanelPlugin, the custom node that reacts to marking changes via an internal event handler
2. CustomWebPanelFormsPlugin, the UI that allows the user to set up which table and column to generate the Wikipedia URL from. This UI demonstrates updating a UI via external event handlers

More information about extending the Spotfire software using the Spotfire SDK and client API is available here; Extending TIBCO Spotfire.

Download the customwebpanel.zip file from resource

customwebpanel.zip