Skip to main content
RSS feed 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:

Application context tools
The following application tools are available in the Spotfire SDK:
  • Examples\Extensions\SpotfireDeveloper.InformationLinkToolExample
    The Open Parameterized Analysis... tool passes parameter values from an open analysis into another analysis to be opened.
  • Examples\Extensions\SpotfireDeveloper.ParameterizedAnalysisToolExample
    The Information Link Tool Example tool enables the user to browse for an information link, populating and displaying its parameters.
  • 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:

Document context tools{
The following document tools are available in the Spotfire SDK:
  • Examples\Extensions\SpotfireDeveloper.HtmlPrintToolExample
  • 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:
    Average calculation document tool
  • 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 (Update table control 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.
  • Examples\Extensions\SpotfireDeveloper.TransformationToolExample\TransformationTool.cs
    Select Tools > Transformation Tool Example to run the tool. It performs transformations on data import.
  • 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:
    Navigate to Page document tool
    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)
    Export to HTML document tool
  • 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>
From Spotfire 2.0 page tools are avilable on page level by way of the tab context menu. The following page tool is available in the Spotfire SDK:
  • Examples\Extensions\SpotfireDeveloper.CustomToolsExample\PageTool.cs
    Right-click a page tab and select TIBCO Spotfire Custom Tools > Move Page Last.
    Move Page Last page tool

Visual

CustomTool<VisualContent>
From Spotfire 2.0 this context enables a tool for all visuals in a page. There are also sub contexts for visual tools applying to specific visualization types:
  • 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.
Sub contexts may be combined by overriding the IsVisibleCore(VisualContent context) method, thereby hiding the tool for all sub contexts but the explicitly defined ones.
The following visual tool is available in the Spotfire SDK:
  • 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.
    Export Marked Rows to Console visual tool
    The tool exports marking data to the console of Visual Studio® when debugging:
    Tool result

Additional Table Visualization Contexts

From Spotfire 2.2 the following sub contexts are available for the table visualization:
  • CustomTool<TablePlotColumnContext>
    Available in the context menu shown when right-clicking a column header. The context contains: table column, the table.
  • CustomTool<TablePlotCellContext>
    Available in the context menu shown when right-clicking a cell in the table.
  • CustomTool<TablePlotCopyCellValueContext>
    Available in the Copy Cell sub menu of the context menu shown when right-clicking a cell in the table. Depending on the content of the right-clicked cell, and without any added extensions, the sub menu title contains one or more of the following entries:
    • Value: Available when the clicked cell contains text. The text is placed on the clipboard.
    • Link: Available when a column renderer has supplied a link for the clicked cell.
    • Image: Available when a renderer has supplied an image for the clicked cell. The image placed on the clipboard is identical to the one seen in the table.
Refer to How to Create a Table Context Menu Entry for details.

Filter

CustomTool<FilterBase>
From Spotfire 2.0 this context enables the tool for all filters in the filter panel. There are also sub contexts for filter tools applying to specific filter types:
  • 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
There is no filter tool in the Spotfire SDK.

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);
    }
    
    ...
}