Spotfire® Mods FAQ

#Please note, some of the URLs in this article may be out of date due to the Spotfire Community migration [Dec 23]

General

What is Spotfire Mods

Spotfire Mods is a lightweight extension framework for adding custom re-usable components to Spotfire. For general information, please visit the Spotfire Mods Overview wiki page.

Where can I find mods to install and use?

Community Mods is a library of publicly available visualization mods that are free to use. Try them out directly on TIBCO Cloud Spotfire or download from Spotfire Community Exchange.

Use the Visualizations flyout to search and browse for mods that are installed and shared in your Spotfire environment.

How can I share a mod with others?

To share a mod with others in your organization, save the mod to the Spotfire library, where others who have the right permissions can find it by browsing or searching for it from the Visualizations flyout. You can also embed the mod in a Spotfire analysis and share the analysis.

To share a mod between different Spotfire environments, it is recommended to sign the mod using a certificate from a trusted certificate authority (CA). See Signing a visualization mod using Package Builder for more information.

To learn more about how the trust framework for mods work, see Trusting custom content in the Spotfire environment.

What Spotfire® versions support mods?

Spotfire Mods is available on Spotfire® Cloud and on all other Spotfire environments with version Spotfire® 11.0 or later.

Where can I post my enhancement ideas?

The Spotfire Community Ideas Portal is a forum where any Spotfire user can post or vote on suggestions for how Spotfire can be better. By using the search term "mods" (or select Category=API/Mods) you can quickly see all submitted ideas related to Spotfire Mods. If you find an idea that you think is important, you can vote to increase its visibility. If you think of a particular problem or enhancement, for which you don't find a related idea, you can choose to add a new idea.

Mod development

How to set up the development environment and create your first mod

To set up the development environment and run your first mod in development mode inside the Spotfire client, follow this step-by-step guide: https://spotfiresoftware.github.io/spotfire-mods/docs/getting-started/.

How to get started with Visual Studio Code

Visual Studio code is available as a free download from Microsoft. 

Getting started with Visual Studio Code.

When developing mods you are going to use VS Code's JavaScript and Node.js capabilities, although, for getting started with mods you don't need detailed knowledge about Node.js, it is sufficient to

• Download and install Visual Studio Code
• Install Node.js
• Open a sample mods project or create your own in Visual Studio Code. It is recommended to follow the mods tutorial the first time around.

Where can I find the API documentation?

The full API documentation can be found here: https://spotfiresoftware.github.io/spotfire-mods/api-docs/index.html. The available options in the mod-manifest.json file are described here: https://spotfiresoftware.github.io/spotfire-mods/docs/using-the-api/mod-schema/. In Visual Studio Code, you have also access to Intellisense.

Where can I find source code examples and templates?

Source code examples can be found on the Spotfire Mods GitHub repository. You also find the link in the Spotfire Labs Analyst or web client, if you go to Tools>Create visualization mod (the menu item is enabled when an analysis is opened or some data is loaded). Read more about the examples: https://spotfiresoftware.github.io/spotfire-mods/docs/getting-started/. Each example comes with a readme file that tells you how to build the example.

Where to find documentation on the mod-manifest.json file that shows all the options?

Yes, a schema of the mod-manifest.json file can be found here: https://spotfiresoftware.github.io/spotfire-mods/docs/using-the-api/mod-schema/. In Visual Studio Code, you have also access to Intellisense.

How can I share my developed mod for others to use?

When your Spotfire instance is connected to your local development server, you can disconnect (using the button) your development server, and the mod becomes embedded in the analysis. The analysis can now be saved to a local disk or the library for anyone to consume. You can also save the mod as a separate entry in the library. Users can then add the mod to any analysis. A third option is to save the mod to a local file by right clicking on the mod's entry in the visualization flyout. See also https://spotfiresoftware.github.io/spotfire-mods/docs/getting-started/#embedding-the-mod-and-saving-to-the-library.

What is Reader and Readables in the Mods API and what is it used for?

A central part of the mods API is the reader object. It is used to simplify the synchronization when reading related values and it allows you to subscribe to changes of the objects or properties, so-called readables, that is needed by your mod. Learn more about the reader and readables here: https://spotfiresoftware.github.io/spotfire-mods/docs/using-the-api/working-with-readables/.

How to work with Spotfire data views

The following guide gives an introduction on how your mod can be configured to access data views, and how those are consumed from the API: https://spotfiresoftware.github.io/spotfire-mods/docs/using-the-api/mod-data-views/.

Can I have more than one data view?

No, a mod is currently limited to one data view.

How to work with multiple measures on a continuous axis

Spotfire natively supports multiple measures by requiring "(Column Names)" on a categorical axis. This makes it transparent for the mod developer if multiple measures are used or not. An alternative way to support multiple measures is to add multiple continuous axes to the Mod. Read more here: https://spotfiresoftware.github.io/spotfire-mods/docs/using-the-api/mod-data-views/.

How to add more dimensions to my mod

You can add any number of axes in the manifest, and call them whatever you want. Dimensions are represented by categorical axes. Read more here: https://spotfiresoftware.github.io/spotfire-mods/docs/using-the-api/mod-data-views/.

How to use Date and Time data in the API

A DateTime value computed by Spotfire can be accessed in the API as a JavaScript Date object, so no parsing should be necessary. This is true for Spotfire data types Date and DateTime. Spotfire data types Time and TimeSpan however cannot be expressed as a JavaScript Date, and these are returned as custom interfaces Time and TimeSpan.

Continuous axes do not support DateTime expressions by default. You have to declare this in the mod-manifest.json with the dataTypes.allowDateTime  property.

Categorical axes support all data types. To read the Date value of level 0 in a categorical axis "X" starting from a DataViewRow, you do: row.categorical("X").value()[0].value(). Now, this will only work if the axis expression is non-empty. You can read the current type of each level on the axis hierarchy from the hierarchy metadata which can be accessed from the DataView object.

Can I have an unaggregated (table) view in a mod?

No, Mod data views are always aggregated and sorted in order of the axes that group the aggregation.

What determines the order of the rows being passed in the DataView?

The order of data rows is determined by which order the categorical axes is defined in the manifest file.

How to work with Spotfire coloring

Mods can use the same Spotfire colors as native Spotfire visualizations. Read more at https://spotfiresoftware.github.io/spotfire-mods/docs/using-the-api/mod-data-views/.

Can I have more than one color axis?

No, a mod supports only one color axis, as do all native Spotfire visualizations.

Make your mod support marking and brush-linking

The spotfire marking concept is especially useful to single out items in the mod as marked, while performing the marking action by interacting with another plot on the same analysis page so you can get a second view or limit data displayed.

The default behavior of a Spotfire plot to display an item as marked is to increase the color transparency of the color of non-marked items, to contrast marked items displayed in a plot with non-marked items.



So also with the mods. Also, a mod's row reflects its marking status by what is returned by
 

A simple example of how to implement marking can be found in js_dev_barchart (https://github.com/spotfiresoftware/spotfire-mods/blob/master/examples/js-dev-barchart/src/main.js). 

How to support area marking

Whether you are creating a whole new visualization type from scratch, or you are working with third-party charting/visualization libraries, implementing Spotfire style marking behavior is one of the larger challenges. Most libraries support mouse-over tooltips and click handlers at best, although some support a "select" concept.

Spotfire conveys which rows have been "marked" in other plots that use the same marking as the one selected in the mod, but when the mods developer indicates to Spotfire which row(s) have been marked by the user of the mod, the mods developer must develop the logic that translates from a marking rectangle -> intersected drawn objects -> dataview rows, where the marking operation is done on the row level by calling the mark method on each row to be selected as row.mark().

You can find an example of how to implement rectangle-style marking in the example js-area-chart-d3 (https://github.com/spotfiresoftware/spotfire-mods/blob/master/examples/js-areachart-d3/src/render.js).

What are Mod Properties?

Mod properties are properties that are local to an instance of your mod. They are defined in the manifest. For example, in a stock chart, you can choose between candlesticks or ohlc bars, to show or not show trading volume.
 

 "properties": 
 [
   {
      "name": "chartType",
      "type": "string",
      "defaultValue": "candle"
   },
   {
      "name": "showVolume",
      "type": "string",
      "defaultValue": "yes"
   }
],

How to work with Mod Properties

• Subscribe to changes of mod properties in your reader method.
• Access the property values by accepting them as arguments into the render method.
• Let the user modify properties using pop-outs that can modify the value of a property. 

How to get and set a document property

To access or modify document properties, use the mod.document API.

Example to modify:

 mod.document.property("MyDocumentProperty").set("Hello property");

 To read a document property (and subscribe to changes) you need to add the property to a reader, for example:  

 const reader = mod.createReader(mod.visualization.data(), mod.document.property("MyDocumentProperty");  
 reader.subscribe(async function render(dataView, prop) 
   {
       console.log(prop.value()); 
   }

What is the difference between Document properties and Mod properties?

Document properties are multi-purpose settings, global to the document, that can be used to tie together different components of an analysis, such as text area controls, custom expressions, data functions and much more (see user guide).

Mod properties are properties that are local to an instance of your mod and can be used to store the state of the Mod. A common use of Mod properties is to provide configuration settings for the Mod, typically in combination with a UI. See sample code in the js-areachart-d3 and js-dev-barchart examples.

Although it is technically possible to use document properties to store settings for a Mod, it is not recommended since that will not work well when there is more than one instance of the Mod in the analysis. The API does not support creating new document properties, only read/write existing ones. In contrast, Mod properties are automatically created when a Mod is instantiated, according to how they are declared in the mod-manifest.

How to work with different chart libraries

• D3
  • There are several source code projects, for example, js-areachart-d3, ts-spiderchart-d3, and js-dev-circular-treemap, in Spotfire Mods GitHub repository that use D3.
• Plotly
• Highcharts
• FusionCharts
• three.js
• Google Charts
  • A mod source code project using Google Charts is the ts-dev-gauge-googlecharts. 

Embedded vs external resources

To allow your mod to work when the Spotfire user is disconnected from the Spotfire Server (and maybe from the internet), the JS files that make up the mod are embedded when you publish the mod to the Spotfire library.

The actual files to be embedded are listed in the mod-manifest.json file in the "files" section:
 

 "files": 
    [
       "index.html",
       "main.css",
       "lightweight-charts.standalone.production.js",
       "main.js"
    ]

However, it is common for CSS files to reference images, gifs, and other resources that Spotfire must be able to read to be embedded correctly. When, for some reason, a resource cannot be embedded into the mod, this external resource must be declared in the manifest. Note that a mod relying on external resources cannot be exported in the web client. 

Publication on the Spotfire Community Exchange

The Spotfire Community Exchange is a safe and trusted place for customers and partners to discover mods for Spotfire, It provides an opportunity for developers to show off their work and deliver industry-specific and useful mods vetted by Spotfire. Build your mod, review the guidelines, prepare publication assets, and submit your mod for review to publish on the Spotfire Community Exchange.

• Submitting Mods to the Spotfire Community Exchange