Spotfire® Document Model Framework API Overview

Overview

The Document Model Framework provides the building blocks of a Spotfire document in a running instance of Spotfire. It guarantees the integrity of the document model.

The document

The document is structured as a tree. The tree corresponds to the structure of the user interface: The root holds a collection of nodes for each page, and each page has a collection of visualizations, and so forth.

In a running Spotfire client, the tree is represented by an object graph. Each object in the graph represents an entity in the document such as a page, a plot, or a filter. You can access and modify the document in a running Spotfire instance.

The Document Model Framework classes are collected in Spotfire.Dxp.Framework.DocumentModel namespace. They implement different aspects of the model, collecting several functions into one structure.

Document Model Framework features

The Document Model Framework provides the following key features:

• Undo and redo functionality

  The document model records any change to the document and represents it in a way allowing the change to be reversed.

• An event mechanism.

  Events related to UI and document updates respectively are conceptually distinct. Both can be used, separately or in concert.

• A mechanism for lazy computations to optimize performance

  UI elements sometimes require heavy computing to render. The use of Runtime Properties may prevent excessive calculating.

Document Model Framework constructs

Behind these features stand Document Model Framework constructs such as:

• A single base class for all document nodes

  Capabilities common to all nodes are collected into a single base class.

• A set of data structures to handle document nodes and sub trees

  Data structures such as lists, dictionaries, and sets provide efficient access to the nodes in the collections.

• A notion of document transactions

  Transactions govern when the UI is updated and define the smallest unit of change registered in the undo and redo stacks.

• A serialization pattern

  The pattern unambiguously defines serialization and de-serialization, thereby enforcing consistent saving and loading.

Note: Application state not related to the document, such as preferences, is not handled by the Document Model Framework.

Controlling the document

To programmatically handle Spotfire often boils down to manipulating the document. It is mainly controlled through three types of actions: Traversing the node tree to access public API methods, bundling actions into transactions to modify the document in concert with the UI, and handling events as the key moment of event-driven programming.

• Accessing the Document 

  The document node tree is easily traversed downwards and upwards. Particularly useful nodes are available as services.

• Transactions 

  A transaction encapsulates a sequence of modifications to the model that make up a single action in the view. The small set of transaction types together covers all possible actions in the view.

• Events 

  The Document Model Framework separates internal and external events. Internal events update the model to a consistent state. External events update the view to reflect the state of the model.

Extending the document

The Document Model Framework records every change to the document. Hence, no document node may be changed without notifying the framework. This restriction is enforced by a rule that at first may seem harsh in the extreme:

Every field of a custom document node must be read-only

So, how can a document node ever be modified? How can one create a custom document node class? The answer is that the document is extended by deriving from a special node class. Then additional document model-compatible classes and properties are added. A limited number of concepts define the whole node tree:

• Extending the Document 

  The document model is a node tree. It is extended by adding new nodes.

• Document Nodes 

  DocumentNode is the abstract base class for all types in the model. The document is extended by creating, attaching and configuring nodes.

• Property Names 

  Every property of a custom document node must have an associated identifier, a Property Name.

• Undoable Nodes 

  Document nodes must not be modified. Instead they may contain Undoable Nodes, a special, modifiable kind of nodes.

• Readonly Properties 

  Some properties stored in ordinary readonly fields never change after initialization. They nevertheless must be initialized in a special way for the Document Model Framework to keep track of them.

• Runtime Properties 

  A runtime property is defined at runtime. It can be computed from other properties in the document.