Using Script Controls can really increase the analytic power of your Spotfire files and make it easier for people to search for insight. Since an entire script is wrapped in a single transaction, tasks like looping through filters will only update the document once at the end. This means, to perform tasks where you want to update the document multiple times, the users must execute the script multiple times. One problem with this is that scripts do not maintain state between uses. To solve this , we will use a property to store our state.
Consider the following example. Assume we are analyzing Unemployment rates by County in the United States from 1999 – 2009. We can display this on a Map Chart as shown below.
This is nice and very useful to visualize, but a consumer may not want to see the unemployment rates summed up for all 11 years, they may want to see how the rates change year from year instead. Sure, they can use the filter panel to move the year filter one year at a time, but it would be nice to wrap this in a Script so the consumer just has to click a button. At the same time, we can also perform some helpful updates while we are in there.
To start, create a Script Control in a Text Area. The Script is going to pass in a visualization parameter that refers to the Map Chart.
The script will retrieve the ‘Year’ Column Filter as an Item Filter and will move the Item Filter by one step. We need to use a property to store the current step so we can just increment it by one next time the Script is executed.
Below is the full script:
import Spotfire.Dxp.Application.Filters as filters
from Spotfire.Dxp.Application.Filters import ItemFilter, FilterTypeIdentifiers
from Spotfire.Dxp.Data import DataProperty, DataType, DataPropertyAttributes, DataPropertyClass
myPanel = Document.ActivePageReference.FilterPanel
myFilter= myPanel.TableGroups[0].GetFilter("Year")
myFilter.FilterReference.TypeId = FilterTypeIdentifiers.ItemFilter
itemFilter = myFilter.FilterReference.As[filters.ItemFilter]()
whichCol = itemFilter.DataColumnReference
if (whichCol.Properties.PropertyExists("CurrentStep") == False):
myProp = DataProperty.CreateCustomPrototype("CurrentStep",0,DataType.Integer,DataPropertyAttributes.IsVisible|DataPropertyAttributes.IsEditable)
Document.Data.Properties.AddProperty(DataPropertyClass.Column, myProp)
whichCol.Properties.SetProperty("CurrentStep",0)
else:
whichVal = whichCol.Properties.GetProperty("CurrentStep")
print whichVal
print itemFilter.Values.Count
if (whichVal == itemFilter.Values.Count):
whichCol.Properties.SetProperty("CurrentStep",0)
else:
itemFilter.Value = itemFilter.Values.Item[whichVal]
if (itemFilter.Value):
vis.Title = "Overall Unemployment by Country in " + itemFilter.Value
else:
vis.Title = "Overall Unemployment by Country from 1999 to 2009"
whichCol.Properties.SetProperty("CurrentStep",whichVal+1)
The end result? Consumers can click on the button and it will step through the Year filter so that they can see the unemployment rates for the given year one year at a time. In addition the title of the Map Chart is updated to include the year for the current step.
Below is the result of the visualization and Filter Panel when the Script is executed to the point where the year column is 2007.
For more information on Script Controls, consider taking our blended training course dedicated to them.