Reading time: 4 minutes and 45 seconds.

Action mod parameter types

Action mod parameter types

An action mod parameter is defined as an object in the parameters array of the mod manifest. The type is defined using the type property and is required (cannot be undefined).

All parameter types (except Boolean and String with enum defined) support setting the parameter to optional. An optional parameter of type T is passed to the script as T? (see “Optional Properties”). Some parameter types support additional properties, such as: enum, array, singleColumn, allowedDataTypes, disableLimitations etc.

Boolean

A parameter of type Boolean is passed to the script as a Boolean. Booleans cannot be optional because such a use case is more clearly modeled by String enum with three possible values.

String

A parameter of type String is passed to the script as a String. Strings can be empty (or undefined if the optional property of has been set).

The String parameter type supports the following additional property:

• enum - An array of valid values for the string. When this property is specified, custom expressions are no longer allowed and the configuration UI has a drop-down list instead of a text input field.

Numerics

A parameter of type Integer (32-bit integer), LongInteger (64-bit integer), SingleReal (32-bit floating point decimal), Real (64-bit floating point decimal), or Currency (128-bit floating point decimal) is passed to the script as a Number (64-bit floating point decimal). Note that this means that LongInteger and Currency might exhibit precision loss when passed to a script. The type of the numeric restricts the possible custom expressions which the parameter accepts. For example, a parameter of type Integer cannot take a custom expression that evaluates to a LongInteger.

Starting in API version 2.1, numerics can be restricted to a range via the range property. For example, an integer can be restricted to be positive by setting "range": { "min": 0 }. The property supports defining min and max, and if the numeric is floating point, you can also define if the min/max value should be included or excluded from the range via minExcluded and maxExcluded.

Time

A parameter of type DateTime, Date, or Time is passed to the script as a System.DateTime object. A parameter of type TimeSpan is passed as a System.TimeSpan object.

Page

A parameter of type Page is passed to the script as a Page object. The page will always be attached to the document at the start of the script execution. To get the active page in a script, use Document.ActivePageReference, but note that the active page might be null if the document contains no pages.

Visualization

A parameter of type Visualization is passed to the script as a Visual object. The visual will be attached to a page which can be reached via its document node context, that is page.Context.GetAncestor(Page). To get the active visualization (useful for instance if your script is attached to a visualization as a floating button) use Document.ActiveVisualReference.

To validate that the visual is of a specific type, use the Visual.As method and check the return value for null:

const { ScatterPlot } = Spotfire.Dxp.Application.Visuals;
const scatterPlot = visual.As(ScatterPlot);
if (!scatterPlot) {
    throw new Error("Expected the visual to be a scatter plot");
}

// Do scatter plot stuff.

DataTable

A parameter of type DataTable is passed to the script as a DataTable object. To get the active or default data table, use Document.ActiveDataTableReference or DataTableCollection. See the DataViewDefinition parameter type in cases where you are interested in tables built from column expressions.

DataColumn

This parameter type was introduced in API version 2.1.

A parameter of type DataColumn is passed to the script as a DataColumn object. The object corresponds to an actual data column in the document. The data table which contains the column can be retrieved via its document node context, i.e. dataColumn.Context.GetAncestor(DataTable).

The DataColumn parameter type supports the following additional properties:

• allowedDataTypes - An array of parameter types that the data column should be restricted to. The array can contain the special “All” or “AllNumeric” values¹. If left undefined, then no type restrictions apply. Note that this is different from defining allowedDataTypes: [“All”] which behaves according to apiVersion.
• array - If set to true, then the parameter will support an arbitrary amount of columns. The argument is passed to the script as an Iterable<DataColum>.

DataViewDefinition

This parameter type was introduced in API version 2.1.

A parameter of type DataViewDefinition is passed to the script as a ActionDataViewDefinition object. This parameter requires that the allowedDataTypes property is specified.

An argument of this type can be passed directly as an input to a data function via DataFunctionInputCollection.SetInput, see snippet “Add a data function using a data view definition” for an example.

The DataViewDefinition parameter type supports the following additional properties:

• allowedDataTypes - An array of parameter types which the data column should be restricted to. Note that the behavior matches the behavior for data functions, meaning that if a non-allowed type can be cast to the correct type then it is allowed. All types can be cast to string. The array can contain the special “All” or “AllNumeric” values¹.
• singleColumn - If the data view should be restricted to a single column expression. This property is required in order to pass the argument to a data function expecting a column.
• disableLimitations - If limitations should be disabled, this guarantees that the entire row count is present in the view.