Skip to main content
RSS feed Subscribe to feed

 

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

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:

Parameter assignment C# equivalent
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″ }
Illegal syntax Comment
X = foo bar;
X = { A, { B } };
Missing quotes
Nested lists not supported

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.

Configuration block syntax

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:

Element Type Parameterized Property
Column Column Calculation Expression
Aggregate Column Calculation Expression
Filter Condition Expression
Filter Filter Condition Expression
Procedure Input Parameter Value
Information Link Static Filter
Edited SQL
  • Pre-update
  • Query
  • Post-update
Data Source Open Session Commands
Close Session Commands

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:

Parameter Type Default Description
filteringName String From active page Specifies the filtering scheme
tableName String From active plot Specifies the table
tableId String From active plot  
columnName String - The column name identifies the filter
searchPattern String - The search pattern for a TextFilter or ListBoxFilter
values StringList - Specifies a list of values
path StringList - The parent node of a hierarchy filter
lowValue String No change The low value for a range filter
highValue String No change The high value for a range filter
includeEmpty Bool No change Include empty (invalid) values
operation Enum Replace Replace, Add, AddAll, Remove, RemoveAll, Reset

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:

Parameter Type Default Description
markingName String From active page Specifies the marking
tableName String From active plot Specifies the table
tableId String From active plot  
whereClause String - Restricted SQL statement that selects a set of rows. The syntax is the same as the one used in expressions; see the Expression Language section in the TIBCO® Spotfire® - User's Manual for more information.
operation Enum Replace Replace, Add, Subtract, Toggle, Intersect

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

Configuration block syntax: block

param_def

Configuration block syntax: param_def

param_value

Configuration block syntax: param_value

atom

Configuration block syntax: atom

list

Configuration block syntax: list

config_call

Configuration block syntax: config_call

config_param

Configuration block syntax: config_param

id

Configuration block syntax: id

PATH

Configuration block syntax: PATH

LETTER

{Configuration block syntax: LETTER

STRING

Configuration block syntax: STRING

INTEGER

Configuration block syntax: block

REAL

Configuration block syntax: REAL

DIGIT

Configuration block syntax: DIGIT

WHITESPACE

Configuration block syntax: WHITESPACE