Adding a script action to a text area or visualization item

As a Spotfire Analyst user (and a script author), you can define your own scripts and add them to action controls in a text area, or as an on-click action for certain visualization items, using the installed client. By using scripts included in an action mod, analysts who do not create scripts themselves can add shared scripts developed by trusted signers. The scripts allow you to incorporate simple actions or tools into your analysis without having to deploy complete AddIns to the server. The scripts have full access to the Spotfire API.

About this task

See Developing mods for more information about action mods.

For security reasons, there are some restrictions for using scripts. For more information, see Usage of scripts and data functions. Script authors should also make sure to save trusted scripts to the library, so that other users can benefit from their work. For even better shareability, scripts can be included in a signed action mod. See Manage trust for more information.

See also IronPython Scripting in Spotfire on the Community for more examples on using scripts in Spotfire.

In HTML mode it is also possible to add some functionality using JavaScript by editing the HTML of the text area. See JavaScript example scripts for more information.

Tip: On the Community, the article Best Practices for Writing Custom JavaScript Code in Text Areas gives an introductory overview of how you can use JavaScript in text areas in Spotfire.

Note: Text areas must be authored in the installed client.

Before you begin

You must have some data loaded in the analysis (in the installed client) and the analysis must be in Editing mode.

Follow the steps in Adding actions to a text area or Adding actions performed when clicking on visualization items and make sure you select Script in step 3.

Procedure

In the Action Control or Action Settings dialog, under Available scripts, click the script of interest. If you do not have any scripts available in the analysis, you can Add existing scripts from an action mod file (*.mod), from an action mod in the library, or add a script that has previously been saved in an analysis file, either locally or in the library. You can also define a new script, if you have the required permissions. For tips on how to define a new script, see Example script workflows below.

Note: Spotfire compares the scripts you are trying to import with already existing scripts. A script whose script body is identical to an existing script will not be imported even if it has a different name.

The Remark field can contain information about whether a script is trusted or not. Scripts that you have created yourself are trusted, and so are scripts saved as trusted to the library by a member in the Script Author group. Scripts from an action mod can be either trusted or not trusted, depending on whether you, or the administrator, have trusted the mod or the signer in advance.
If you receive an analysis file containing a script directly from another person, the script will be listed as "Not trusted". This does not necessarily mean that the script contains any unsafe material, but you should determine whether you trust the script by inspecting it in the Edit Script dialog. By clicking OK in the Edit Script dialog, the script will be trusted. If you know all scripts are safe, you can go to Manage trust and click Trust all.

However, due to security reasons, scripts cannot be used in a TIBCO Cloud Spotfire web client environment unless they come from trusted action mods. In a Spotfire on premises web client environment, scripts can be executed if they come from trusted action mods or are saved as trusted by a member in the Script Author group.
Click each parameter (if there are any) in the Necessary input for the selected script field and specify the Input for the selected parameter. If the script needs some kind of input values, then these must be specified before the script can be executed. Different parameter types have different input settings.
For value parameters, you can choose whether to type a text-based or numeric Value directly, to associate the selected parameter with a Property, or to calculate the value via an Expression. Other parameters might need a specification of a visualization, a page, or a data table to work with.
When all script parameters have been defined, click OK.
If you are adding an action to a text area, click Save when you are finished.
If you are adding an action to a text area, click Close in the upper-right corner to exit the Edit Text Area dialog.

Example script workflows

Below are more details about how to create and use a few example scripts in Spotfire. These steps can also serve as instructions for how you should work when creating your own scripts. See also IronPython example scripts.

Creating the "Change visualization title" script

This example shows how you can add a script that changes the title of a visualization.

About this task

See Adding actions to a text area for information about how to reach the Action Control dialog.

Procedure

In the Action Control dialog, click Add > New script.
In the New Script dialog, type the Script name Change visualization title.
In the Script field, type or paste the script:
```
visual.Title = title
```
Click Add.
In the Add Script Parameter dialog, enter title as the Name, and under Type, select String.
The title must be a string which can be defined either by a simple text value, a string property or an expression.
If desired, add a Debug value which can be used for testing the script.
Click OK.
The "title" parameter is added to the Script parameters list.
Click Add to define the second parameter, and in the Add Script Parameter dialog, enter visual as the Name, and under Type, select Visualization.
This parameter is used to point out which visualization to change the title on.
Select a Debug value visualization to use when testing the script.
Click OK.
The "visual" parameter is added to the Script parameters list.
If desired, test the script by clicking Run Script.

The selected visualization title is updated with the provided debug value. Click Undo in the New Script dialog to revert to the old title.
Click OK.

Results

The "Change visualization title" script is added to the Available scripts list in the Action Control dialog and the defined parameters are shown in the Necessary input for the selected script list (as long as the script is selected in the Available scripts list).

Tip: To instead change the title of the active visualization, use the following script:

Document.ActiveVisualReference.Title = title

Using the "Change visualization title" script in a text area

When you use a script in an action control you can define how to provide the necessary input for all parameters of the script. This example shows how you can use the script from the previous example on a button in a text area.

Procedure

Follow the step instructions above and make sure the "Change visualization title" script is selected in the Action Control dialog.
In the Action Control dialog, under Necessary input for the selected script, click the parameter title.
Under Input for the selected parameter, you determine whether to define the title using a predefined Value, a Property or an Expression. In this example, click Property to be able to change the title using a property control.
Click Select Property.
In the Select Property dialog, on the Document Properties tab, click New.
In the New Property dialog, type a suitable Property name, for example, visualization.title.
From the Data type drop-down list, select String.
Type a Value to be the first (default) value of the property. For example, My Visualization Title.
Click OK to close all dialogs.
The action control is added to the text area.
Click Save when you are done editing the text area, and then close the Edit Text Area dialog.
Test the action control by clicking it in the text area.

Tip: The property controlling the visualization title could in turn be modified using a property control (for example, an input field) in the text area. See Adding a property control to a text area and Using document, data table or column properties in an analysis for examples of how you can add property controls.

Creating the "Change filtering scheme" script

This example shows how you can add a script that changes the filtering scheme.

About this task

See Adding actions to a text area

Procedure

In the Action Control dialog, click Add > New script.
In the New Script dialog, type the Script name Change filtering scheme.

In the Script field, type or paste the script:

from Spotfire.Dxp.Application.Filters import FilterPanel

# Get hold of the filters panel for the current page.
panels = Document.ActivePageReference.Panels
# The return value and out parameters are returned as a tuple
# in IronPython and can be bound with pattern matching.
(found, filterPanel) = panels.TryGetPanel[FilterPanel]()

# Find the filtering selection named "Filters2"
# and set it as current.
for filteringScheme in Document.FilteringSchemes:
   filteringSelection = filteringScheme.FilteringSelectionReference
   if filteringSelection.Name == "Filters2":
       filterPanel.FilteringSchemeReference = filteringScheme

The included example script expects to find a filtering scheme called "Filters2" and changes the filtering scheme of the active page to the Filters2 filtering scheme.

Click OK to close the New Script dialog.

Using the "Change filtering scheme" script in a text area

This example shows how you can use the script created in the previous example on a button in a text area.

Procedure

Make sure that the "Change filtering scheme" script is selected in the Action Control dialog.
Click OK.
This script requires no input from the end users, but if there is no "Filters2" filtering scheme in the analysis, then nothing will happen when the action control is clicked.
Click Save when you are finished editing the text area, and then close the Edit Text Area dialog.
Test the action control by clicking it in the text area.