Subscribe to feed

 

Creating a Tool

A tool performs an analytic action. It operates in the context it is defined for.

Overview

A tool performs an action in a context. The context may be the Spotfire application itself, the document, or a particular visualization type. Custom tools can be grouped both on menu and context menu level, but they may also be hidden from the user interface.

When implementing tools, consider the general tool characteristics:

• Tools are static.
  There is only one instance of a tool. The instance receives a handle to its context from the context argument of the Execute() method invoking it.
• Tools are stateless.
  To save state in the document, use a custom Document Node.
• Tools perform an action.
  Usually, the action ought to result in one undo state on the undo stack. Therefore all tools that change the state of the document should wrap their action in a Transaction.

Tutorials

• How to Automate a Data Transformation
  This example project implements a custom document tool that opens an information link and performs two transformations, a predefined pivot followed by a predefined unpivot.
• How to Create an Information Link Tool
  An information link is a configured request to a database. Information link configuring and opening can be automated. The API provides methods to find a link, to get and set its parameters, and launch the browse information link user interface. This tutorial describes a tool populating parameters on an informaton link.

Tool Contexts

A custom tool specifies the CustomTool base class in its declaration, passing the tool context as type parameter:

public sealed class MyTool : CustomTool<TContext>

Application

CustomTool<AnalysisApplication>

From Spotfire 2.0 application tools are available from the Tools menu. Tool AnalysisApplication tools are enabled when Spotfire has been started. The indicated tools are SDK application tools:

• Examples\Extensions\SpotfireDeveloper.InformationLinkToolExample
  The Open Parameterized Analysis... tool passes parameter values from an open analysis into another analysis to be opened.
  • Refer to How to Create an Information Link Tool tutorial for details and implementation steps.
• Examples\Extensions\SpotfireDeveloper.ParameterizedAnalysisToolExample
  The Information Link Tool Example tool enables the user to browse for an information link, populating and displaying its parameters.
  • Refer to How to Configure the Initial State of the Analysis tutorial for details and implementation steps.
• Examples\Extensions\SpotfireDeveloper.CustomToolsExample\MyApplicationTool.cs
  The Open C:\myfile.csv tool opens the indicated file if it exists, and handles the case that is does not exist.
• Examples\Extensions\SpotfireDeveloper.CustomToolsExample\AutomationToolExample.cs
  The Automation Example tool performs a series of actions using common API methods.
• Examples\Extensions\SpotfireDeveloper.CustomToolsExample\CustomHelpExample.cs
  The Custom Help dialog tool displays a dialog with buttons launching a custom CHM help.

Document

CustomTool<Document>

From Spotfire 2.0 document tools are available from the Tools menu. Tool menu entries are enabled when a document is opened:

• Examples\Extensions\SpotfireDeveloper.HtmlPrintToolExample
  • Refer to the How to Create an Export Tool tutorial for details.
• Examples\Extensions\SpotfireDeveloper.CalculationToolExample\AddNewTableExample\AddNewTableExampleTool.cs
  This tool is available from the Tools > Add New Table Example... menu. It copies the selected columns to a new table:
• Examples\Extensions\SpotfireDeveloper.CalculationToolExample\BasicExample\BasicExampleTool.cs
  This tool is available from the Tools > Basic Example... menu. It calculates the average based on a column selection, and adds a result column to an existing table:
  
• Examples\Extensions\SpotfireDeveloper.CalculationToolExample\PivotTool\PivotTool.cs
  Implements two related tools available from the Tools menu, Pivot Calculation (Manual)... and Pivot Calculation (Auto update).... Each tool performs a pivot calculation and adds the resulting table to Spotfire, one requiring manual update, indicated by a refresh icon (), while the other is automatically updated.
• Examples\Extensions\SpotfireDeveloper.CustomWorkerExample
  The Suffix Worker... and Chained Worker... tools exemplify how to create and use a basic worker, and a worker delegating to another worker respectively.
  • Refer to How to Create a Thread tutorial for details and implementation steps.
• Examples\Extensions\SpotfireDeveloper.TransformationToolExample\TransformationTool.cs
  Select Tools > Transformation Tool Example to run the tool. It performs transformations on data import.
  • Refer to How to Automate a Data Transformation tutorial for details and implementation steps.
• Examples\Extensions\SpotfireDeveloper.CustomToolsExample\NavigateToPageTool.cs
  Select Tool > TIBCO Spotfire Custom Tools > Navigato To Page... to run the tool. It opens a dialog with a drop-down list of all pages in the document, enabling quick page selection:
  
  This tool has state, which is defined in the NavigateToPageToolState.cs file. It also displays a user interface, which is defined in the NavigateToPageArgumentsControl.cs designer.
• Examples\Extensions\SpotfireDeveloper.ExportToolExample\ExportToHtmlTool.cs
  Unlike the other document tools, this tool is displayed in the File > Export sub menu. This alternative menu display position is set using theMenuCategory.Export category in the CustomTool constructor:

  public ExportToHtmlTool() : base(Properties.Resources.ExportToHtmlDisplayName, null, MenuCategory.Export)

  
• By using MenuCategory.FileOpen it is possible to hook into the File | Open From menu.
• By using MenuCategory.FileSave it is possible to hook into the File | Save As menu.

Page

CustomTool<Page>

• Examples\Extensions\SpotfireDeveloper.CustomToolsExample\PageTool.cs
  Right-click a page tab and select TIBCO Spotfire Custom Tools > Move Page Last.
  

Visual

CustomTool<VisualContent>

• Visualization: All visualizations, but not the plot area. Available from Spotfire 2.0.
• BarChart: Only bar charts. Available from Spotfire 2.0.
• BoxPlot: Only box plots. Available from Spotfire 2.0.
• CrossTablePlot: Only cross table plots. Available from Spotfire 2.0.
• LineChart: Only line charts. Available from Spotfire 2.0.
• MapChart: Only map charts. Available from Spotfire 2.0.
• ParallelCoordinatePlot: Only parallel coordinate plots
• PieChart: Only pie charts. Available from Spotfire 2.0.
• ScatterPlot: Only scatter plots. Available from Spotfire 2.0.
• ScatterPlot3D: Only 3D scatter plots. Available from Spotfire 2.2.
• SummaryTable: Only summary tables. Available from Spotfire 2.0.
• TablePlot: Only table plots. Available from Spotfire 2.0.
• TextArea: Only text areas. Available from Spotfire 2.0.

• Examples\Extensions\SpotfireDeveloper.CustomToolsExample\PlotTool.cs
  This tool is available as TIBCO Spotfire Custom Tools > Export Marked Rows To Console in the plot context menu. It is only available for scatter plots and bar charts, and is enabled when there is a marking.
  
  The tool exports marking data to the console of Visual Studio® when debugging:
  

Additional Table Visualization Contexts

Filter

CustomTool<FilterBase>

• CheckboxFilter: Check box filters. Available from Spotfire 2.0.
• ItemFilter: Item filters. Available from Spotfire 2.0.
• ListBoxFilter: List box filters. Available from Spotfire 2.1.
• RadioButtonFilter: Radio button filters. Available from Spotfire 2.0.
• RangeFilter: Range filters. Available from Spotfire 2.0.
• TextFilter: Text box filters. Available from Spotfire 2.0.
• HierarchyFilter: Hierarchy filters. Available from Spotfire 2.0.
• ColumnFilter: All filter types, but the hierarchy filters. Available from Spotfire 2.0.
• SingleValueColumnFilter: Filter types selecting one value at a time, that is item filters and radio button filters

Grouping Tools

Tools can be grouped in the location where they appear:

• The Transformation Tool Example is registered without specifying a menu group. Since it is a Document tool, it will appear in the Tools menu.
• The Navigate to Page tool is registered with a specified menu sub group. Since it also is a Document tool, it will appear in the menu group of the Tools menu, in this case the TIBCO Spotfire Custom Tools group.

To prevent accidental or unmanaged adding of tools from other projects, only tools that are implemented in the same Spotfire extension project can be grouped together in a menu sub group. Collecting the tools in one AddIn, the group is created and then passed to the tools to be included in the group when registering them. Tools are registered using the AddIn.ToolRegistrar.Register methods:

public sealed class CustomToolsAddIn : AddIn
{
    protected override void RegisterTools(ToolRegistrar registrar)
    {
        base.RegisterTools(registrar);

        CustomMenuGroup menuGroup = new CustomMenuGroup("My menu sub group");

        registrar.Register(new MyTool(), menuGroup);
    }
    
    ...
}