Accessing the Document using the Spotfire® Document Model Framework API

Overview

This page describes how to access the nodes of an open document in Spotfire® using the Document Model Framework API.

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

Navigating the document

The root node of the document is accessible from the Document property of the application object:

 Document document = mainApplication.Document;

You can now traverse the node tree in several ways:

Navigating downwards

Traversing the node tree downwards you typically iterate through collections. The page collection of the root node is common starting point:

 foreach (Page page in document.Pages) {     // Do something }

Navigating upwards

To traverse the node tree upwards, you can call the GetAncestor method. It is available through the Context property that exists on every document node. The method locates the closest enclosing parent node of a specific type. For example, to get the page of a particular visualization:

 Page page = visual.Context.GetAncestor<Page>();

Navigating using services

Finally, you can shortcut through the node tree to key nodes by getting hold of them as services. You access a service using the GetService method that is available via the Context property on every document node. The data manager is a useful node, and it is available as a service:

 DataManager dataManager = visual.Context.GetService<DataManager>();

If a node cannot provide the service itself it forwards the request to its parent node. The root node forwards requests to the application.

Reading the document

To read, for instance, the name of a page, you first acquire the object representing the page and then read the Name property of the object:

 string pageName = page.Name;

Modifying the document

The document is typically accessed and modified as a response to events. The Event and Transaction concepts are crucial to the use of the document model, as is the understanding of nodes and how to create them:

• 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.

   

• Triggers

  Event triggers specify the modifications that shall invoke specific event handlers.