In this, the final installment of our three-part series on animating visualizations, we will look at how to create controls to allow users to pass in parameters into a custom-built tool. We will go through three options for doing this: using the APIs, Preferences, and Document Properties.
APIs
One option for passing in parameters to a custom tool is to create properties inside your custom tool class which can be set remotely from the Script. This would allow authors to create property controls, and then via a script, pass in those values into the Custom Tool.
If you want to keep the complexity of your tool to a minimum, you would not create these properties as values that get persisted with the document. This means when you reopen the file, the properties are not maintained. You could add this capability in, but this requires a lot more work to make the custom tool persist values, as it requires building a custom node which get serialized in the Spotfire Analysis Document. So, it is possible, but not what I would recommend for this solution.
Preferences
We can also use Preferences to get configurable values into our custom tool. According to the API information on our Spotfire Technology Network:
Preferences are used by add-ins to persist one or more values, for example last used settings, user preferred values, etc. An object of this type can contain one or more such values, referred to as Preference Properties. Thus to create a set of preference properties, extend this class and populate that class with the properties that shall be persisted.
When a user is logged on, the preference is populated with its persisted values, if such exist. If not, the preference is given default values while waiting for the user to set its values. When preferences are saved, their values are persisted using .Net serialization on the client and on the server depending on the settings of the preference.
Preferences properties can be applied to single users or to user groups. Preferences applied to a group are inherited by all members of the group. The users can, however, choose to override the properties with custom values. In the same way, a group can override the properties inherited from its parent groups. If the group has more than one parent group, the value from the Primary parent group (as defined using the TIBCO Spotfire Administration Manager).
This solution would work well if we wanted to set global defaults, or a different default for each group of users. In our case, we want a solution where we can set the properties differently in each analysis file and for each user, so I would not recommend this approach for this situation.
Document Properties
The final solution would be to define Document Properties in our analysis file. Then in our custom tool, we will search for the existence of these properties and read the values. If the properties do not exist, we will use the default value, which is built into the tool.
We can then create property controls to allow the users to configure the values of these properties directly in the analysis file. The benefit of this approach is that we allow the users to change the values per analysis file, those values are persisted automatically, and we have very little updates that are required to our custom tool. This is the approach I will recommend for our solution.
First, we need to create the properties and controls. We will create two: the first will allow the user to set the speed at which we will automate through the filters. We will call this property stepRate and will expose it via a slider control:
The second property will allow users to select which column they want to filter through. We will call this property whichColumn and expose it via a drop-down control:
After we create the properties and the controls, we need to update our custom tool to read these values. The code snippets below go in the constructor of our RefreshDocumentWorker class inside our custom tool. We also need to add a new private field called stepRate, as shown below:
string whichColumn = Convert.ToString(this.application.Document.Properties["whichColumn"]);
this.stepRate = Convert.ToDouble(this.application.Document.Properties["stepRate"]);
To see the updated example work in the Web Player, visit the following URL:
http://spottrain.tibco.com/SpotfireWeb/ViewAnalysis.aspx?file=/kevin/AnimateFiltersWithControl.dxp
If you are interested in learning how to complete a tool like this yourself, consider taking our Developer Bootcamp. If you would like to have Spotfire build this tool or a similar tool for you, please contact Professional Services. If you have ideas or concepts you would like to see in future tip of the week articles, please contact me with your idea.
