Home Extending the Spotfire Platform Creating Extensions to the Spotfire Platform Creating a Configuration Block

©Spotfire 2008

Creating a Configuration Block

A configuration block configures the initial state of an analysis. It has two sections: a list of parameter assignments and a list of configuration statements.

Overview

Parameterizing an analysis means to inject parameters into the process of opening the file, and optionally configure the analysis further before it becomes interactive to the user. Both actions are defined in a configuration block.

A configuration block is a script-like piece of text. In the following example, the first two lines are parameter assignments, the following lines are configuration statements:

Region = "West";
Acme.Limits = { 10, 100, 1000 };
SetPage(pageTitle = "Overview");
ApplyBookmark(bookmarkName = "UserRegionOnly");
SetFilter(tableName = "Table 1", columnName = "Column 1", values = { "A", "B" });
SetMarking(tableName = "Table 2", whereClause = "Gender = 'Male' AND GeekFactor = 'High'");

Parameter assignments and configuring statements are applied when an analysis containing a configuration block is opened.

• Parameter assignments are used for parameterized analyses, analyses containing data sources, Parameterized Information Links or transformations with parameters.
  The parameters come into scope before data is loaded. They can be retrieved via the API at any time.
  Parameters assignments are mandatory whenever the analysis makes use of parameters.
• Configuration statements consist of a method name followed by an argument list.
  Configuration statements are interpreted after data has been loaded, but before the command history is activated. When the configuration statements have been interpreted, they are discarded.
  Configuration statements are always optional. Nothing in an analysis requires configuration statements to be defined.

In the API, a configuration block is represented by a text property in the DocumentOpenSettings and DocumentSaveSettings classes, which are used by the AnalysisApplication.Open and AnalysisApplication.Save methods respectively.

Additional Uses

In addition to opening a file with a configuration block, it is possible to save an analysis with an embedded configuration block. A typical scenario is the automatic generation of a set of similar files for users with slightly different needs, such as sales managers responsible for different regions. When an analysis with an embedded configuration block is opened, the effect is the same as if the block had been passed as a parameter to the Open call.

It is also possible to combine an embedded block with an external block passed as a parameter. The embedded block is interpreted before the external block. In this way the external block can be used to override settings defined by the embedded block. A typical scenario is to open an analysis with a configuration block from an external application, where the values for the parameter assignments are automatically derived in that application. In this case the Open call is done through COM using an automation interface.

Tutorial

• How to Configure the Initial State of the Analysis
  This tutorial describes how to open a parameterized analysis using values from an existing analysis.

Parameter Assignments

When opening a parameterized analysis, all parameters within the analysis must be assigned to values via the API. Any missing parameters will result in an error. The parameters are managed by the ParameterManager class, and can be retrieved using the API. The parameter manager is not part of the document, but resides at the application level where it can be retrieved as a service.

Parameter names are like identifiers in many computer languages. Case is significant, but only in the sense that parameter names are stored the way they were defined. The lookup method in the parameter manager is case insensitive, and all parameter names must be unique even in the case-independent sense to reduce the risk for confusion.

Parameter values are either strings or lists of strings. All lists are flat and may not contain other lists. Strings can be written without quotes if they do not contain whitespace or special characters:

A = ″my name is Bob″
B = 17
C = ″2007-11-08″
D = 100.23
E = { 1, 2, 3 }
F = { ″A″ }

string A = ″my name is Bob″
string B = ″17″
string C = ″2007-11-08″
string D = ″100.23″
string[] E = { ″1″, ″2″, ″3″ }
string[] F = { ″A″ }

Parameterized Information Links

Parameter assignments are commonly and conveniently used with Parameterized Information Links created in the Spotfire Information Designer tool. These Information Links may contain a number of server-defined parameters. Such a parameter is defined by name and type in the Information Designer. The type can be either single-valued or a list type. Information link parameters reference the names in the configuration block using the following syntax:
?param_name where param_name is a path like Acme.Limits in the example above.

Refer to the syntax section for syntax diagrams.

When data is loaded from a parameterized information link, values for the parameters are retrieved from the ParameterManager. The table below lists the properties in the different information link elements where parameters may be included:

For details on how to create a parameterized Information Link, see the Parameterized Information Links topic in the TIBCO® Spotfire® - User's Manual.

Configuring Statements

A configuring statement is applied in two steps. First the method name and the ensuing parameter list making up a configuration statement is parsed and used to create an instance of the corresponding configurator class. Then the configurator is validated and executed.

The following list defines the set of available configuration statements:

• SetPage: Specifies the initial page of an analysis
• ApplyBookmark: Applies a bookmark
• SetFilter: Specifies the initial setting of a filter of an arbitrary type
• SetMarking: Initializing a marking

There is no extension point to add custom configuration statements.

SetPage

The SetPage configuration statement is used to specify the initial page of an analysis. It takes a single parameter which can be a zero-based page index, a page guid, or a page title:

SetPage(pageIndex = 2);
SetPage(pageId = "5462f26a-8e02-11dc-8314-0800200c9a66");
SetPage(pageTitle = "The Intro Page");

The SetPage configurator uses the PageCollection of the document to find a matching page. It will search for a match in the order listed, first using the page index if provided, then the page id, and finally the page title.

If no matching page is found, the configurator will add a note to the issue list, but it will not break.

ApplyBookmark

The ApplyBookmark configuration statement is used to specify the initial state of an analysis. The bookmark is identified by its display name or id:

ApplyBookmark(bookmarkId = "5462f26a-8e02-11dc-8314-0800200c9a66");
ApplyBookmark(bookmarkName = "Streamlined");

The ApplyBookmark configurator uses the BookmarkCollection of the document to find a matching bookmark. It will search for a match in the order listed, first id and then name.

If no matching bookmark is found, the configurator will add a note to the issue list, but it will not break.

SetFilter

The SetFilter configuration statement is used to specify the initial setting of a filter of an arbitrary type. The following parameters can be used in various combinations:

Check box filter or list box filter

The settings for a CheckBoxFilter or ListBoxFilter are specified like this:

// Check A and B, uncheck all other values:
SetFilter(columnName = "C", values = { "A", "B" });

// Uncheck A, leave other check boxes as is:
SetFilter(columnName = "C", values = { "A" }, operation = Remove);

// Uncheck all boxes and exclude empty values:
SetFilter(columnName = "C", operation = RemoveAll, includeEmpty = false);

// Reset the filter:
SetFilter(columnName = "C", operation = Reset);

// The following applies only to the ListBoxFilter.
// Select A and BA, hide all items not ending with �A�:
SetFilter(columnName = "C", values = { "A", "B" }, searchPattern = "*A");

Item filter or radio button filter

The settings for an ItemFilter or RadioButtonFilter are specified like this:

// Select a specified value:
SetFilter(columnName = "C", values = { "A" });

// Select all values, leave includeEmpty as is:
SetFilter(columnName = "C", operation = AddAll);

// Select no values, leave includeEmpty as is:
SetFilter(columnName = "C", operation = RemoveAll);

Range filter

The settings for a RangeFilter are specified like this:

// Select a range of values:
SetFilter(columnName = "C", lowValue = "100", highValue = "1000");

// Set the upper limit, leave the lower limit as is:
SetFilter(columnName = "C", highValue = "1000");

// Select the full range of values:
SetFilter(columnName = "C", operation = AddAll);

Hierarchy filter

The settings for a CheckBoxHierarchyFilter are specified like this:

// Select the May 1988 subtree only:
SetFilter(columnName = "C", path = { "1988" }, values = { "May" });

// Add the May 1988 subtree to the included values:
SetFilter(columnName = "C", path = { "1988" }, values = { "May" }, operation = Add);

// Remove two days in May from the selection:
SetFilter(columnName = "C", path = { "1988", "May" }, values = { "1", "2" }, operation = Remove);

Text filter

The settings for a TextFilter are specified like this:

// Select all items ending with 'A':
SetFilter(columnName = "C", searchPattern = "*A");

// Reset the filter:
SetFilter(columnName = "C", operation = Reset);

SetMarking

The SetMarking configuration statement is used to initialize a marking. It takes the following parameters:

A SetMarking configuration statement is used like this:

// Replace the current marking by the one specified:
SetMarking(tableName = "T1", whereClause = "Region = 'West' and Broker = 'John'");

// Add a set of rows to the current marking:
SetMarking(tableName = "T1", whereClause = "Region = 'East'", operation = Add);

Syntax diagrams

block

param_def

param_value

atom

list

config_call

config_param

id

PATH

LETTER

STRING

INTEGER

REAL

DIGIT

WHITESPACE

© 2008 TIBCO Software Inc. – About this site – Contact Us – Terms of use – Last updated Nov 20