Jump to content
We've recently updated our Privacy Statement, available here. ×
  • Spotfire® Document Model Framework API 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 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.


    User Feedback

    Recommended Comments

    There are no comments to display.

  • Create New...