Subscribe to feed

 

Document Model Framework

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.

Overview

The view, that is the user interface, derives its state from the model. And just like Windows® Forms is a framework for building user interfaces, another kind of framework is required to build models. The Document Model Framework builds and maintains the open document in a running Spotfire instance.

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.