Using Document Nodes with the Spotfire® Document Model Framework API

Overview

This article describes how to use document nodes with the Spotfire® Document Model Framework API.

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

The key entity of document model is the document node. It is defined in an abstract base class:

• DocumentNode provides all functionality required by a document node. Every custom document model class inherits from it.

A document node is created via its constructor. At this stage it does not support undo actions, the event machinery is disabled and application level services are not available. To become fully functional the node has to be attached to the model.

Attaching a node

When a node is attached all the nodes it recursively owns are also attached. The sub tree spanned by the node is attached. A sub tree can be attached to the document in two ways:

1. By adding the root of the sub tree to a collection in the document. For example, if a new page node is added to the collection of pages.
    
2. By assigning the root of the sub tree to a property of an attached node.

In addition, the document is attached when it is created, or, if it is persisted, when loaded.

Configuring a node

When a new sub tree is attached the sub tree it is configured, except when a persisted documents is loaded. The purpose of the configuration is to make it possible for the sub tree to configure itself with respect to the existing document.

A document node can configure itself by overriding two methods:

• OnConfigure is invoked when a sub tree is configured, traversing the sub tree according to the depth-first (DFS) algorithm.
   
• OnConfigured is invoked on the way up in the recursion when all sub trees of the node have been fully configured.

The node owner is always set when these methods are invoked, thereby enabling access to the entire document and lookup services.

It is possible to modify both the attaching sub tree and the existing document, but it is strongly recommended not to modify nodes outside of the attaching sub tree.

Detaching a node

When a node is removed from the document it becomes detached. It is not allowed to modify a node after it has been detached, since it has become a part of the undo stack. After a transaction has been completed the nodes are eventually serialized into the undo stack file and the node is disposed.

TIP: A node that has been detached may be attached to the document again, provided that it is attached during the same transaction in which it was removed. In this way a visualization can be moved from one page to another.