Create a Configuration Block in TIBCO Spotfire®
Last updated:
4:23am Feb 27, 2017

Introduction

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 setting document properties, 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.
     
  • 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.

Where to Use a Configuration Block

Configuration Blocks can be used in the following in the following places:

  • In a web page using the TIBCO Spotfire® JavaScript API

  • In a Custom C# Extension

  • In a URL when opening a Spotfire analysis in a browser. for example:

    • http://spotfire.cloud.tibco.com/spotfire/wp/OpenAnalysis?file=/Gallery/Introduction%20to%20Spotfire&configurationBlock=SetFilter(
      tableName=%22World%20Bank%20Data%22,columnName=%22Region%22,values=%7B%22North%20America%22%7D);

    • Note: When used in a URL, the configuration block  must be URL encoded. For example: values={"North America"} needs to be replaced with values=%7B"North America"%7D, where ", , { and } have been replaced with %22, %20, %7B and %7D respectively.

Parameter Assignments

When opening a parameterized analysis, all mandatory parameters within the analysis must be assigned to values via the API. Any missing mandatory parameters will result in an error. The parameters are also 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.

Parameters and Document Properties

A configuration block parameter is automatically assigned to a document property, if a document property with the same name and data type is defined in the analysis. This is a convenient way to parameterize many different items in the analysis. One common use is to have document properties values as parameters to IronPython scripts.

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.

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
Aggregated Column Calculation Expression
Filter Condition Expression
Filter Filter Condition Expression
Information Link Static Filter
Edited SQL (pre-update, query, post-update)
Procedure Input Parameter Value
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

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 Specified the table
columnName String - Identifies the filter
searchPattern String - Used for TextFilter and 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:

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 Specifies the table
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);