TIBCO Spotfire® Document Model Framework API Overview
Last updated:
12:45am May 10, 2017

Back to main C# extensions page

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 the 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. 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 cover 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 readonly

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.

Feedback (1)

Are there other articles written on the other namespaces?  I have searched but haven't found any.  This is a good overview for Spotfire.Dxp.Framework.DocumentModel.  Trying to get started in the Spotfire API is darn near impossible without information like this.

jsebby 8:42pm Oct. 04, 2018