Spotfire Mods

https://spotfiresoftware.github.io/spotfire-mods/docs/
Admin
The Spotfire Mods framework provides tools and APIs for extending Spotfire with custom...
Tokens:41,952
Snippets:380
Trust Score:9.7
Update:2 months ago
Show doc for...
Tokens:
Raw
### Install and build dependencies

Source: https://spotfiresoftware.github.io/spotfire-mods/docs/action-mods/insight-agent-tutorial

Navigates to the project directory, installs required packages, and triggers the build process.

```bash
cd calculated-column
npm install
npm run build
```

--------------------------------

### Start Development Server

Source: https://spotfiresoftware.github.io/spotfire-mods/docs/getting-started

Start the development server to enable automatic updates and testing of your mod.

```bash
npm run server
```

--------------------------------

### Separating Initial Setup from Updates with Readers

Source: https://spotfiresoftware.github.io/spotfire-mods/docs/visualization-mods/using-the-api/working-with-readables

Illustrates how to use `reader.once()` for initial setup with multiple `Readables`, followed by creating separate `readers` with `subscribe()` for property changes and rendering updates. This prevents unnecessary callbacks during setup.

```javascript
const setupReader = mod.createReader(
    mod.visualization.data(),
    mod.windowSize(),
    mod.property("myProperty")
);

setupReader.once((dv, size, prop) => {
    log("All values are read", prop.value());

    const propertyReader = mod.createReader(mod.property("myProperty"));
    propertyReader.subscribe((myProperty) => {
        log("Property has changed to", myProperty.value());
    });

    const renderReader = mod.createReader(
        mod.visualization.data(),
        mod.windowSize()
    );
    renderReader.subscribe(async function render(dataView, windowSize) {
        log(
            "Render",
            (await dataView.allRows()).length,
            windowSize.height
        );
    });

    setInterval(() => prop.set("New value" + Math.random()), 2000);
});

```

--------------------------------

### Create a New Mod Project

Source: https://spotfiresoftware.github.io/spotfire-mods/docs/getting-started

Use these commands to create a new mod project from the default template and install dependencies. Ensure you have Node.js (version 22 or later) installed.

```bash
npx @spotfire/mods-sdk@latest new [action|visualization]
npm install
npm run build

```

--------------------------------

### Initialize and build action mod

Source: https://spotfiresoftware.github.io/spotfire-mods/docs/action-mods/tutorial

Commands to scaffold a new action mod project and install dependencies.

```bash
npx @spotfire/mods-sdk@latest new action
npm install
npm run build
```

--------------------------------

### Setup Analysis with Visualization

Source: https://spotfiresoftware.github.io/spotfire-mods/docs/action-mods/tutorial

Configures document properties, loads data from the library, and initializes a horizontal bar chart visualization.

```typescript
// Create shorthands for the relevant APIs.
const { DataType, DataProperty, DataPropertyClass } = Spotfire.Dxp.Data;
const { SbdfLibraryDataSource } = Spotfire.Dxp.Data.Import;
const { LibraryManager, LibraryItemRetrievalOption, LibraryItemType } = Spotfire.Dxp.Framework.Library;
const { VisualTypeIdentifiers, BarChart, BarChartOrientation } = Spotfire.Dxp.Application.Visuals;

export function setupAnalysis({ document, application }: SetupAnalysisParameters) {
    addProperty("companyName", DataType.String, "Tutorial Company");
    addProperty("creationDate", DataType.DateTime, System.DateTime.Now);
    const myDataTable = loadLibraryData("my-data");

    let page = document.ActivePageReference;
    if (!page) {
        // No pages exist, add one.
        page = document.Pages.AddNew();
    }

    const barChart = page.Visuals.AddNew(VisualTypeIdentifiers.BarChart).As(BarChart)!;
    barChart.Title = "Tutorial Visualization";
    barChart.Data.DataTableReference = myDataTable;

    // Use AutoConfigure to setup axis.
    barChart.AutoConfigure();

    barChart.Orientation = BarChartOrientation.Horizontal;
    barChart.ColorAxis.Expression = barChart.XAxis.Expression;

    function loadLibraryData(tableName: string) {
        if (document.Data.Tables.Contains(tableName)) {
            return document.Data.Tables.Item.get(tableName)!;
        }

        // Retrieve the library manager service and assume it is defined since we are connected to a TSS.
        const libraryManager = application.GetService(LibraryManager)!;
        const results = libraryManager.Search(`type::sbdf ${tableName}`, LibraryItemRetrievalOption.IncludePath);
        const myDataItem = Array.from(results).find(
            (i) => i.Title === "my-data" && i.ItemType === LibraryItemType.SbdfDataFile,
        );

        if (!myDataItem) {
            throw new Error(`Found no SBDF in the library with the name '${tableName}'.`);
        }

        // Load the data.
        const sbdfDataSource = new SbdfLibraryDataSource(myDataItem);
        return document.Data.Tables.Add(tableName, sbdfDataSource);
    }

    function addProperty(name: string, type: Spotfire.Dxp.Data.DataType, value: unknown) {
        if (document.Data.Properties.ContainsProperty(DataPropertyClass.Document, name)) {
            return;
        }

        // Create a the property object
        const property = DataProperty.CreateCustomPrototype(name, type, DataProperty.DefaultAttributes);

        // Set the property value.
        property.Value = value;

        // Add it to the document
        document.Data.Properties.AddProperty(DataPropertyClass.Document, property);
    }
}

RegisterEntryPoint(setupAnalysis);
```

--------------------------------

### Switch cross table axis script setup

Source: https://spotfiresoftware.github.io/spotfire-mods/docs/action-mods/snippets

Command to initialize the switch cross table axis script and the corresponding manifest configuration.

```bash
npx @spotfire/mods-sdk add-script switch-cross-table-axis --name "Switch cross table axis"
```

```json
{
    "id": "switch-cross-table-axis",
    "name": "Switch cross table axis",
    "entryPoint": "switchCrossTableAxis",
    "file": "build/switch-cross-table-axis.js",
    "description": "Switches the axis expressions of a cross table visualization.",
    "parameters": [{ "name": "visual", "type": "Visualization", "description": "The cross table visualization." }]
}
```

--------------------------------

### Search for Library Items

Source: https://spotfiresoftware.github.io/spotfire-mods/docs/action-mods/tutorial

Initial setup for searching the library for an SBDF file and adding document properties.

```typescript
// Create shorthands for the relevant APIs.
const { DataType, DataProperty, DataPropertyClass } = Spotfire.Dxp.Data;
const { LibraryManager, LibraryItemRetrievalOption } = Spotfire.Dxp.Framework.Library;

export function setupAnalysis({ document, application }: SetupAnalysisParameters) {
    addProperty("companyName", DataType.String, "Tutorial Company");
    addProperty("creationDate", DataType.DateTime, System.DateTime.Now);

    // Retrieve the library manager service and assume it is defined since we are connected to a TSS.
    const libraryManager = application.GetService(LibraryManager)!;
    const results = libraryManager.Search("type::sbdf my-data", LibraryItemRetrievalOption.IncludePath);

    for (const result of results) {
        console.log(`Found item: Title=${result.Title}, Path=${result.Path}, GUID=${result.Id.ToString()}`);
    }

    function addProperty(name: string, type: Spotfire.Dxp.Data.DataType, value: unknown) {
        if (document.Data.Properties.ContainsProperty(DataPropertyClass.Document, name)) {
            return;
        }

        // Create a the property object
        const property = DataProperty.CreateCustomPrototype(name, type, DataProperty.DefaultAttributes);

        // Set the property value.
        property.Value = value;

        // Add it to the document
        document.Data.Properties.AddProperty(DataPropertyClass.Document, property);
    }
}

RegisterEntryPoint(setupAnalysis);
```

--------------------------------

### Library Search Output

Source: https://spotfiresoftware.github.io/spotfire-mods/docs/action-mods/tutorial

Example of the debug output after successfully granting LibraryRead permissions.

```text
Found item: Title=my-data, Path=/my-data, GUID=a82c6a33-2743-492d-870b-8c188f8cc66b
```

--------------------------------

### Modular Data Loading and Property Registration

Source: https://spotfiresoftware.github.io/spotfire-mods/docs/action-mods/tutorial

This script defines helper functions for adding document properties and loading SBDF data from the library, then registers the setup function as an entry point.

```typescript
// Create shorthands for the relevant APIs.
const { DataType, DataProperty, DataPropertyClass } = Spotfire.Dxp.Data;
const { SbdfLibraryDataSource } = Spotfire.Dxp.Data.Import;
const { LibraryManager, LibraryItemRetrievalOption, LibraryItemType } = Spotfire.Dxp.Framework.Library;

export function setupAnalysis({ document, application }: SetupAnalysisParameters) {
    addProperty("companyName", DataType.String, "Tutorial Company");
    addProperty("creationDate", DataType.DateTime, System.DateTime.Now);
    loadLibraryData("my-data");

    function loadLibraryData(tableName: string) {
        if (document.Data.Tables.Contains(tableName)) {
            return document.Data.Tables.Item.get(tableName)!;
        }

        // Retrieve the library manager service and assume it is defined since we are connected to a TSS.
        const libraryManager = application.GetService(LibraryManager)!;
        const results = libraryManager.Search(`type::sbdf ${tableName}`, LibraryItemRetrievalOption.IncludePath);
        const myDataItem = Array.from(results).find(
            (i) => i.Title === "my-data" && i.ItemType === LibraryItemType.SbdfDataFile,
        );

        if (!myDataItem) {
            throw new Error(`Found no SBDF in the library with the name '${tableName}'.`);
        }

        // Load the data.
        const sbdfDataSource = new SbdfLibraryDataSource(myDataItem);
        return document.Data.Tables.Add(tableName, sbdfDataSource);
    }

    function addProperty(name: string, type: Spotfire.Dxp.Data.DataType, value: unknown) {
        if (document.Data.Properties.ContainsProperty(DataPropertyClass.Document, name)) {
            return;
        }

        // Create a the property object
        const property = DataProperty.CreateCustomPrototype(name, type, DataProperty.DefaultAttributes);

        // Set the property value.
        property.Value = value;

        // Add it to the document
        document.Data.Properties.AddProperty(DataPropertyClass.Document, property);
    }
}

RegisterEntryPoint(setupAnalysis);
```

--------------------------------

### Replace data table with SBDF CLI and configuration

Source: https://spotfiresoftware.github.io/spotfire-mods/docs/action-mods/snippets

Requires the LibraryRead capability. The manifest defines parameters for the library GUID and target data table.

```bash
npx @spotfire/mods-sdk add-script replace-table-with-library-data --name "Replace a data table with an SBDF file from the library"
```

```json
{
    "id": "replace-table-with-library-data",
    "name": "Replace a data table with an SBDF file from the library",
    "entryPoint": "replaceTableWithLibraryData",
    "file": "build/replace-table-with-library-data.js",
    "description": "Replaces a table in the analysis with data from an SBDF file saved in the library.",
    "parameters": [
        { "name": "libraryGuid", "type": "String", "description": "The library ID of the SBDF." },
        { "name": "table", "type": "DataTable", "description": "The data table which should be replaced." }
    ]
}
```

--------------------------------

### Configure Data Types for Continuous Axes

Source: https://spotfiresoftware.github.io/spotfire-mods/docs/visualization-mods/using-the-api/mod-data-views

Shows how to specify allowed data types for continuous axes in the manifest file. This example enables support for both date/time and numeric data types.

```json
"dataTypes": {
    "allowDateTime": true,
    "allowNumeric": true
}

```

--------------------------------

### Creating and Awaiting a Property Readable

Source: https://spotfiresoftware.github.io/spotfire-mods/docs/visualization-mods/using-the-api/working-with-readables

Demonstrates how to create a Readable for a mod property. The first example shows creating a lazy Readable without fetching data, while the second awaits the value, triggering a fetch from the server.

```typescript
// This does not fetch any value from the server
const myPropertyReadable = mod.property("myProperty");
console.log(myPropertyReadable);

// This fetches the latest value from the server.
const myProperty = await mod.property("myProperty");
console.log(myProperty);
```

--------------------------------

### Define Popout Content Structure

Source: https://spotfiresoftware.github.io/spotfire-mods/docs/visualization-mods/tutorials/barchart-googlechart

Define the structure of the popout content using available components like sections and buttons. This example shows a simple section with a button.

```javascript
         const { section } = popout;
         const { button } = popout.components;
         const popoutContent = () => [

```

--------------------------------

### Initialize Agent and Script via CLI

Source: https://spotfiresoftware.github.io/spotfire-mods/docs/action-mods/insight-agent-tutorial

Use the Spotfire Mods SDK to scaffold the agent and script files.

```bash
npx @spotfire/mods-sdk add-agent calculated-column-agent --name "Calculated column agent" --type visual
npx @spotfire/mods-sdk add-script add-calculated-column --name "Add a calculated column"
```

--------------------------------

### Initialize agent project

Source: https://spotfiresoftware.github.io/spotfire-mods/docs/action-mods/insight-agent-tutorial

Creates a new agent project using the Spotfire mods SDK template.

```bash
npx @spotfire/mods-sdk@latest new agent -o calculated-column
```

--------------------------------

### Retrieve Library Item

Source: https://spotfiresoftware.github.io/spotfire-mods/docs/action-mods/tutorial

Methods to retrieve a specific library item using search results or a known GUID.

```typescript
const myDataItem = Array.from(results).find(i => i.Title === "my-data" && i.ItemType === LibraryItemType.SbdfDataFile);
```

```typescript
const myDataItem = OutParam.create(Spotfire.Dxp.Framework.Library.LibraryItem);
libraryManager.TryGetItem(System.Guid.Parse("a82c6a33-2743-492d-870b-8c188f8cc66b"), myDataItem.out);
```

--------------------------------

### Library Access Error Trace

Source: https://spotfiresoftware.github.io/spotfire-mods/docs/action-mods/tutorial

Example of the error message generated when the mod manifest lacks the required LibraryRead capability.

```text
Could not run action

The API function 'LibraryItemRetrievalOption.get_IncludePath' requires 'LibraryRead' to be specified in the "capabilities" property of the manifest file.

Error: The property get method is unavailable or inaccessible
    at setupAnalysis (C:\setup-analysis\build\setup-analysis.js:10:92) ->     const results = libraryManager.Search("type::sbdf my-data", LibraryItemRetrievalOption.IncludePath);
```

--------------------------------

### Replace data table with SBDF implementation

Source: https://spotfiresoftware.github.io/spotfire-mods/docs/action-mods/snippets

Retrieves an SBDF file from the library using a GUID and replaces the specified data table.

```typescript
const { Guid } = System;

const { SbdfLibraryDataSource } = Spotfire.Dxp.Data.Import;
const { LibraryManager, LibraryItem, LibraryItemType } = Spotfire.Dxp.Framework.Library;

export function replaceTableWithLibraryData({
    application,
    libraryGuid,
    table
}: ReplaceTableWithLibraryDataParameters) {
    const manager = application.GetService(LibraryManager);
    if (manager == null) {
        throw new Error("LibraryManager is unavailable.");
    }

    const guid = OutParam.create(Guid);
    if (!Guid.TryParse(libraryGuid, guid.out)) {
        throw new Error(`The provided library ID '${libraryGuid}' is not a valid GUID.`);
    }

    const item = OutParam.create(LibraryItem);
    if (!manager.TryGetItem(guid, item.out)) {
        throw new Error(`A library item with the id '${libraryGuid}' could not be found.`);
    }

    if (item.ItemType !== LibraryItemType.SbdfDataFile) {
        throw new Error("The library item is not an SBDF file.");
    }
    const ds = new SbdfLibraryDataSource(item);

    try {
        table.ReplaceData(ds);
    } catch (e) {
        throw new Error(`Failed to replace table with library data, exception: ${e}`);
    }
}

RegisterEntryPoint(replaceTableWithLibraryData);
```

--------------------------------

### Mod manifest configuration

Source: https://spotfiresoftware.github.io/spotfire-mods/docs/action-mods/snippets

Define the script entry point in the mod-manifest.json file.

```json
{
    "id": "add-trend-lines-reference-layer",
    "name": "Add a reference layer showing trend lines",
    "description": "Adds a reference layer to the visualization that displays trend lines.",
    "file": "build/add-trend-lines-reference-layer.js",
    "entryPoint": "addTrendLinesReferenceLayer"
}
```

--------------------------------

### Index a managed object

Source: https://spotfiresoftware.github.io/spotfire-mods/docs/action-mods/faq

Use the Item property with get and set methods to access indexers on managed objects like dictionaries.

```typescript
const value = dict.Item.get("key");
dict.Item.set("key", "newValue");
```

--------------------------------

### Initialize Replace Empty Values Mod

Source: https://spotfiresoftware.github.io/spotfire-mods/docs/action-mods/snippets

Use the Spotfire Mods SDK CLI to scaffold the action mod script.

```bash
npx @spotfire/mods-sdk add-script replace-empty-values --name "Replace empty values of a column"
```

--------------------------------

### Add Script via CLI

Source: https://spotfiresoftware.github.io/spotfire-mods/docs/action-mods/snippets

Use the Spotfire Mods SDK CLI to initialize the script in your project.

```bash
npx @spotfire/mods-sdk add-script insert-columns-with-column-match --name "Insert columns to an existing data table with custom column match"
```

--------------------------------

### Mod Manifest Configuration

Source: https://spotfiresoftware.github.io/spotfire-mods/docs/action-mods/snippets

The manifest file defines the entry point and parameters for the script.

```json
{
    "id": "add-latest-mod-visualization",
    "description": "Searches the library for mod visualizations with the ID specified by the user. Selects the latest version of all such available in the library and adds a new page with one such visualization.",
    "name": "Add latest mod visualization",
    "file": "build/add-latest-mod-visualization.js",
    "entryPoint": "addLatestModVisualization",
    "parameters": [{ "name": "modId", "description": "The id of the visualization mod to add.", "type": "String" }]
}
```

--------------------------------

### Build Mod Once (Minified and Obfuscated)

Source: https://spotfiresoftware.github.io/spotfire-mods/docs/getting-started

Run this command to build the mod once in a minimized and obfuscated form, suitable for sharing.

```bash
npm run build
```

--------------------------------

### Read column values using DataColumn parameter

Source: https://spotfiresoftware.github.io/spotfire-mods/docs/whats-new

Demonstrates the legacy approach of manually resolving a column from a table using a string or GUID parameter.

```typescript
export function readColumnValues({ document, table, column }: ReadColumnValuesParameters) {
    const dataColumn = OutParam.create(DataColumn);
    if (!table.Columns.TryGetValue(column, dataColumn.out)) {
        throw new Error(`Data table '${table.Name}' contains no column with name '${column}'.`);
    }

    // ...
}
```

--------------------------------

### Remove unreferenced markings CLI and configuration

Source: https://spotfiresoftware.github.io/spotfire-mods/docs/action-mods/snippets

Use the CLI to scaffold the script and update the manifest to register the entry point.

```bash
npx @spotfire/mods-sdk add-script remove-unreferenced-markings --name "Remove unreferenced markings"
```

```json
{
    "id": "remove-unreferenced-markings",
    "name": "Remove unreferenced markings",
    "entryPoint": "removeUnreferencedMarkings",
    "file": "build/remove-unreferenced-markings.js",
    "description": "Removes all markings which are not referenced by a visualization."
}
```

--------------------------------

### Add layout script via CLI

Source: https://spotfiresoftware.github.io/spotfire-mods/docs/action-mods/snippets

Use this command to initialize the layout-and-rotate script within your Spotfire mod project.

```bash
npx @spotfire/mods-sdk add-script layout-and-rotate --name "Set up a page layout and rotate the visualizations on consecutive runs"
```

--------------------------------

### Add script via CLI

Source: https://spotfiresoftware.github.io/spotfire-mods/docs/action-mods/snippets

Use the Spotfire Mods SDK to scaffold the script into the project.

```bash
npx @spotfire/mods-sdk add-script add-trend-lines-reference-layer --name "Add a reference layer showing trend lines"
```

--------------------------------

### Load Google Charts Asynchronously

Source: https://spotfiresoftware.github.io/spotfire-mods/docs/visualization-mods/tutorials/barchart-googlechart

Use `async`/`await` to load the Google Charts library and draw the chart, simplifying the code structure. This example also adjusts chart area margins and removes the title.

```typescript
await google.charts.load("current", { packages: ["corechart"] });
          var data = google.visualization.arrayToDataTable([
              ["Element", "Density", { role: "style" }],
              ["Copper", 8.94, "#b87333"],
              ["Silver", 10.49, "silver"],
              ["Gold", 19.3, "gold"],
              ["Platinum", 21.45, "color: #e5e4e2"]
          ]);

          var view = new google.visualization.DataView(data);
          view.setColumns([0, 1, { calc: "stringify", sourceColumn: 1, type: "string", role: "annotation" }, 2]);

          var options: google.visualization.BarChartOptions = {
              bar: { groupWidth: "95%" },
              legend: { position: "none" },
              chartArea: { left: 85, top: 20, right: 10, bottom: 40 }
          };
          var chart = new google.visualization.BarChart(document.getElementById("mod-container"));
          chart.draw(view, options);
```

--------------------------------

### Early Return from Slow Render Loop using hasExpired()

Source: https://spotfiresoftware.github.io/spotfire-mods/docs/visualization-mods/using-the-api/working-with-readables

Shows how to use `reader.hasExpired()` within a `subscribe` callback to detect if the reader has expired during a slow rendering process. This allows for an early return to start a new rendering loop.

```javascript
const reader = mod.createReader(mod.property("myProperty"));

document.body.onclick = () => {
    log("Set new value for myProperty ");
    mod.property("myProperty").set("next value" + Math.random());
};

reader.subscribe(async function slowRender(prop) {
    log("Slow render started ", prop.value());
    await sleep(3000);

    if (await reader.hasExpired()) {
        log("Reader has expired, return early to enter new loop");
        return;
    }

    await sleep(3000);

    log("End of slow rendering");
});

function sleep(ms) {
    return new Promise((res) => setTimeout(res, ms));
}

function log(...messages) {
    let div = document.createElement("div");
    div.textContent = messages.join(" ");
    document.body.appendChild(div);
    div.scrollIntoView();
}

```

--------------------------------

### Manifest configuration for custom date format

Source: https://spotfiresoftware.github.io/spotfire-mods/docs/action-mods/snippets

Defines the entry point and parameters for the custom date format script.

```json
{
    "id": "set-custom-date-format",
    "name": "Set a custom date format for a column",
    "entryPoint": "setCustomDateFormat",
    "file": "build/set-custom-date-format.js",
    "description": "Sets a custom date format for a specific column.",
    "parameters": [
        { "name": "format", "type": "String", "description": "The date format, e.g. 'dd-MM-yyyy' for day/month-year." },
        {
            "name": "columnName",
            "type": "String",
            "description": "The name of the column whose date format should be set."
        },
        { "name": "table", "type": "DataTable", "description": "The data table in which the column can be found." }
    ]
}
```

--------------------------------

### Add Map Chart Projection Script

Source: https://spotfiresoftware.github.io/spotfire-mods/docs/action-mods/snippets

Command to initialize the map chart projection script in a Spotfire Mod project.

```bash
npx @spotfire/mods-sdk add-script set-projection-for-mapchart-layer --name "Set a projection for all layers in a mapchart"
```

--------------------------------

### CLI Command to Add Shapefile Script

Source: https://spotfiresoftware.github.io/spotfire-mods/docs/action-mods/snippets

Use this command to initialize the script in your project. Requires the LibraryRead capability.

```bash
npx @spotfire/mods-sdk add-script add-shapefile-to-active-map-chart --name "Add a shapefile to the active map chart"
```

--------------------------------

### Configure mod-manifest.json

Source: https://spotfiresoftware.github.io/spotfire-mods/docs/action-mods/snippets

Define the mod metadata and parameters required for the Spotfire environment.

```json
{
    "id": "replace-empty-values",
    "name": "Replace empty values of a column",
    "entryPoint": "replaceEmptyValues",
    "file": "build/replace-empty-values.js",
    "description": "Replaces all the empty values of a column with another value.",
    "parameters": [
        { "name": "table", "type": "DataTable", "description": "The table in which the column can be found." },
        { "name": "columnName", "type": "String", "description": "The name of the column." },
        { "name": "value", "type": "String", "description": "The value which should replace the (Empty) values." }
    ]
}
```

--------------------------------

### Mod Manifest Configuration

Source: https://spotfiresoftware.github.io/spotfire-mods/docs/action-mods/snippets

Define the entry point and parameters for the shapefile addition script in the mod-manifest.json file.

```json
{
    "id": "add-shapefile-to-active-map-chart",
    "name": "Add a shapefile to the active map chart",
    "entryPoint": "addShapefileToActiveMapChart",
    "file": "build/add-shapefile-to-active-map-chart.js",
    "description": "Adds a feature layer to the active map chart visualization using a shapefile from the library. Useful when configured as an action trigger on a map chart visualization.",
    "parameters": [
        { "name": "shapeFileLibraryName", "type": "String", "description": "The name of the shapefile in the library." }
    ]
}
```

--------------------------------

### Mod manifest configuration

Source: https://spotfiresoftware.github.io/spotfire-mods/docs/action-mods/snippets

The mod-manifest.json file defines the entry point and metadata for the layout script.

```json
{
    "id": "layout-and-rotate",
    "name": "Set up a page layout and rotate the visualizations on consecutive runs",
    "entryPoint": "layoutAndRotate",
    "file": "build/layout-and-rotate.js",
    "description": "Creates a layout where one visualization is enlarged and all others are stacked to its the right. On consecutive runs the enlarged visualization is rotated with one of the smaller ones."
}
```

--------------------------------

### Create a Reader for Property and Window Size

Source: https://spotfiresoftware.github.io/spotfire-mods/docs/visualization-mods/using-the-api/working-with-readables

Initializes a reader to monitor changes in a specific property and the window size.

```typescript
mod.createReader(mod.property("myProperty"), mod.windowSize());

```

--------------------------------

### Add Bar Chart Coloring Script

Source: https://spotfiresoftware.github.io/spotfire-mods/docs/action-mods/snippets

Command to initialize the bar chart coloring script in a Spotfire Mod project.

```bash
npx @spotfire/mods-sdk add-script bar-chart-coloring --name "Set the colors of a bar chart"
```

--------------------------------

### Manifest configuration for document property

Source: https://spotfiresoftware.github.io/spotfire-mods/docs/action-mods/snippets

Defines the entry point and parameters for the document property script.

```json
{
    "id": "set-document-property",
    "name": "Set a document property",
    "entryPoint": "setDocumentProperty",
    "file": "build/set-document-property.js",
    "description": "Sets a document property to a specific value, creating the property if it does not already exist.",
    "parameters": [
        { "name": "propertyName", "type": "String", "description": "The name of the property." },
        { "name": "type", "type": "String", "description": "The type of the property." },
        { "name": "value", "type": "String", "description": "The value to set the document property to." }
    ]
}
```

--------------------------------

### Configure Manifest File

Source: https://spotfiresoftware.github.io/spotfire-mods/docs/action-mods/insight-agent-tutorial

The JSON manifest defining the agent, script, and parameter structure.

```json
{
    "apiVersion": "2.5",
    "version": "1.0",
    "type": "action",
    "name": "Calculated Column",
    "id": "calculated-column",
    "description": "Suggests useful calculated columns for a visualization's data table.",
    "capabilities": ["AI"],
    "icon": "icon.svg",
    "scripts": [
        {
            "id": "add-calculated-column",
            "name": "Add a calculated column",
            "entryPoint": "addCalculatedColumn",
            "file": "build/add-calculated-column.js",
            "parameters": [
                { "name": "name", "type": "String" },
                { "name": "expression", "type": "String" },
                { "name": "table", "type": "DataTable" },
                { "name": "explanation", "type": "String" }
            ]
        }
    ],
    "agents": [
        {
            "id": "calculated-column-agent",
            "name": "Calculated column agent",
            "entryPoint": "calculatedColumnAgent",
            "file": "build/calculated-column-agent.js",
            "type": "visual"
        }
    ]
}
```

--------------------------------

### Define Action Parameters via CLI

Source: https://spotfiresoftware.github.io/spotfire-mods/docs/action-mods/insight-agent-tutorial

Register the required parameters for the calculated column action.

```bash
npx @spotfire/mods-sdk add-parameter add-calculated-column name String
npx @spotfire/mods-sdk add-parameter add-calculated-column expression String
npx @spotfire/mods-sdk add-parameter add-calculated-column table DataTable
npx @spotfire/mods-sdk add-parameter add-calculated-column explanation String
```

--------------------------------

### Add document property script

Source: https://spotfiresoftware.github.io/spotfire-mods/docs/action-mods/snippets

Use the CLI to scaffold a new script for setting document properties.

```bash
npx @spotfire/mods-sdk add-script set-document-property --name "Set a document property"
```

--------------------------------

### TypeScript Implementation

Source: https://spotfiresoftware.github.io/spotfire-mods/docs/action-mods/snippets

The core logic for performing the column join using Spotfire DXP APIs.

```typescript
const { Dictionary, List } = System.Collections.Generic;
const { DataColumnSignature, AddColumnsSettings, JoinType, DataColumn } = Spotfire.Dxp.Data;
const { DataTableDataSource } = Spotfire.Dxp.Data.Import;

export function insertColumnsWithColumnMatch({
    srcTable,
    srcColumn,
    destTable,
    destColumn,
    ignoreColumns
}: InsertColumnsWithColumnMatchParameters) {
    const destCol = getColumnOrThrow(destTable, destColumn);
    const srcCol = getColumnOrThrow(srcTable, srcColumn);

    // The matching column.
    const map = new Dictionary(DataColumnSignature, DataColumnSignature);
    map.Add(new DataColumnSignature(destCol), new DataColumnSignature(srcCol));

    // Columns to ignore.
    const ignoredColumns = new List(DataColumnSignature);
    for (const ignoreColumn of ignoreColumns.split(",")) {
        ignoredColumns.Add(new DataColumnSignature(getColumnOrThrow(srcTable, ignoreColumn)));
    }

    const settings = new AddColumnsSettings(map, JoinType.InnerJoin, ignoredColumns);
    const dataSource = new DataTableDataSource(srcTable);
    destTable.AddColumns(dataSource, settings);
}

function getColumnOrThrow(table: Spotfire.Dxp.Data.DataTable, columnName: string) {
    const col = OutParam.create(DataColumn);
    if (!table.Columns.TryGetValue(columnName, col.out)) {
        throw new Error(`Cannot find column '${columnName}' in table '${table.Name}'.`);
    }
    return col.value;
}

RegisterEntryPoint(insertColumnsWithColumnMatch);
```

--------------------------------

### TypeScript Implementation

Source: https://spotfiresoftware.github.io/spotfire-mods/docs/action-mods/snippets

The core logic for searching the library, comparing versions, and loading the mod into the document.

```typescript
const { LibraryManager, LibraryItemRetrievalOption, LibraryItem } = Spotfire.Dxp.Framework.Library;
const { NotificationService } = Spotfire.Dxp.Framework.ApplicationModel;
const { Version } = System;

type LibraryItem =  Spotfire.Dxp.Framework.Library.LibraryItem;
type Version = System.Version;

export function addLatestModVisualization({ document, application, modId }: AddLatestModVisualizationParameters) {

    // Search the library for visualization mods with the specified id.
    const libraryManager = application.GetService(LibraryManager);
    const result = libraryManager?.Search(`type:visualization Spotfire.Mod.Id:${modId}`, LibraryItemRetrievalOption.IncludeProperties);
    if (!result || result.Count === 0) {
        notifyInfo(application, "No matching Mod found", "The library search did not return anything.");
        return;
    }

    // Pick the library item representing the visualization mod with the highest version.
    let latest: LibraryItem = result.Item.get(0)!;
    let latestVersion = getModVersion(latest);
    for (let index = 1; index < result.Count; index++) {
        const item = result.Item.get(index)!;
        const version = getModVersion(item);
        if(version.CompareTo(latestVersion) > 0) {
            latestVersion = version;
            latest = item;
        }
    }

    // Load a visualization mod from the library item into the ModManager.
    // This will cause any existing visualization mods with the same id to be upgraded to the new version.
    const modIdentifier = OutParam.create(Spotfire.Dxp.Application.Mods.ModIdentifier);
    const exception = OutParam.create(System.Exception);
    if (!document.ModManager.TryLoadVisualizationModFromLibrary(latest, modIdentifier.out, exception.out)) {
        notifyInfo(application, "Failed to load Mod", exception.value.ToString());
        return;
    }

    // Add a new page with one mod visualization.
    const page = document.Pages.AddNew();
    page.AutoConfigure();
    const modVis = page.Visuals.AddNew(modIdentifier);
    modVis.Title = `${modIdentifier.Name}, v${modIdentifier.Version.ToString()} (${modIdentifier.Id})`;
}

function getModVersion(item: LibraryItem) : Version {
    const ps = Array.from(item.Properties);
    const versionString =  ps.filter(p => p.Name == "Spotfire.Mod.Version").map(p => p.Item.get(0))[0];
    const version = OutParam.create(System.Version);
    if (!System.Version.TryParse(versionString ?? "", version.out)) {
        return new Version();
    }

    return version;
}

function notifyInfo(application: Spotfire.Dxp.Application.AnalysisApplication, title: string, summary: string) {
    const ns = application.GetService(NotificationService);
    ns?.AddInformationNotification(title, summary, "");
}

RegisterEntryPoint(addLatestModVisualization);
```

--------------------------------

### Use APIs with output parameters

Source: https://spotfiresoftware.github.io/spotfire-mods/docs/action-mods/faq

Initialize an OutParam object and pass its out field to methods that require C# out parameters.

```typescript
const page = OutParam.create(Spotfire.Dxp.Application.Page);
if (document.Pages.TryGetPage(new System.Guid("<page GUID>"), page.out))
{
    page.Title = "New Title";
}
```

--------------------------------

### Add reference layer script via CLI

Source: https://spotfiresoftware.github.io/spotfire-mods/docs/action-mods/snippets

Use the Spotfire Mods SDK CLI to scaffold the reference layer script.

```bash
npx @spotfire/mods-sdk add-script reference-layer-color-scale --name "Give a reference layer an independent color scale"
```

--------------------------------

### Add Script via CLI

Source: https://spotfiresoftware.github.io/spotfire-mods/docs/action-mods/snippets

Use the Spotfire Mods SDK CLI to register the script in your project.

```bash
npx @spotfire/mods-sdk add-script add-latest-mod-visualization --name "Add latest mod visualization"
```

--------------------------------

### Configure Mod Manifest

Source: https://spotfiresoftware.github.io/spotfire-mods/docs/action-mods/snippets

Define the data function parameters in the mod-manifest.json file.

```json
{
    "id": "data-function-with-data-view-definition",
    "name": "Add a data function using a data view definition",
    "description": "Adds a data function to the document and sets its input to the 'integerColumns' parameter.",
    "entryPoint": "dataFunctionWithDataViewDefinition",
    "file": "build/data-function-with-data-view-definition.js",
    "parameters": [
        {
            "name": "integerColumns",
            "description": "Integer columns to be passed to the data function.",
            "type": "DataViewDefinition",
            "allowedDataTypes": ["Integer"]
        }
    ]
}
```

--------------------------------

### Add find columns script via CLI

Source: https://spotfiresoftware.github.io/spotfire-mods/docs/action-mods/snippets

Use the Spotfire Mods SDK CLI to scaffold the find columns script.

```bash
npx @spotfire/mods-sdk add-script find-columns-with-predicate --name "Find all columns that match a predicate"
```

--------------------------------

### Find columns manifest configuration

Source: https://spotfiresoftware.github.io/spotfire-mods/docs/action-mods/snippets

Manifest file definition for the find columns script.

```json
{
    "id": "find-columns-with-predicate",
    "name": "Find all columns that match a predicate",
    "entryPoint": "findColumnsWithPredicate",
    "file": "build/find-columns-with-predicate.js",
    "description": "This snippet shows how to use a predicate callback to find all time columns of a table and prints them to the debug output.",
    "parameters": [
        { "name": "table", "type": "DataTable", "description": "The data table in which to search for columns." }
    ]
}
```

--------------------------------

### Add custom date format script

Source: https://spotfiresoftware.github.io/spotfire-mods/docs/action-mods/snippets

Use the CLI to scaffold a new script for setting custom date formats.

```bash
npx @spotfire/mods-sdk add-script set-custom-date-format --name "Set a custom date format for a column"
```

--------------------------------

### Add a data flow insight agent via CLI

Source: https://spotfiresoftware.github.io/spotfire-mods/docs/action-mods/snippets

Use the Spotfire Mods SDK CLI to scaffold a new visual insight agent.

```bash
npx @spotfire/mods-sdk add-agent dataflow-insight-agent --name "Run a data flow during the insight phase" --type visual
```

--------------------------------

### Mod Manifest Configuration

Source: https://spotfiresoftware.github.io/spotfire-mods/docs/action-mods/snippets

The mod-manifest.json file defines the entry point and parameters for the save analysis action.

```json
{
    "id": "save-analysis-to-library",
    "name": "Save the analysis to the library",
    "entryPoint": "saveAnalysisToLibrary",
    "file": "build/save-analysis-to-library.js",
    "description": "Saves the current analysis to the library.",
    "wrapInTransaction": false,
    "parameters": [
        {
            "name": "libraryFolder",
            "type": "String",
            "description": "The path to the folder in the library where the analysis should be saved."
        },
        { "name": "title", "type": "String", "description": "The title of the analysis." }
    ]
}
```

--------------------------------

### Configure mod-manifest.json for the agent

Source: https://spotfiresoftware.github.io/spotfire-mods/docs/action-mods/snippets

Define the agent metadata in the mod-manifest.json file.

```json
{
    "id": "dataflow-insight-agent",
    "name": "Run a data flow during the insight phase",
    "description": "Computes a derived column with a data flow on the background thread, then reports a summary.",
    "file": "build/dataflow-insight-agent.js",
    "entryPoint": "dataflowInsightAgent",
    "type": "visual"
}
```

--------------------------------

### Initialize mod with multiple data views

Source: https://spotfiresoftware.github.io/spotfire-mods/docs/whats-new

Use the mod.visualization.data API with specific names to subscribe to multiple data views simultaneously.

```typescript
Spotfire.initialize(async (mod: Spotfire.Mod) => {
    const reader = mod.createReader(mod.visualization.data("Nodes"), mod.visualization.data("Edges"));
    const context = mod.getRenderContext();

    reader.subscribe(render);

    async function render(nodesDataView: Spotfire.DataView, edgesDataView: Spotfire.DataView) {
        const errors = (await Promise.all([nodesDataView.getErrors(), edgesDataView.getErrors()])).flatMap(
            errs => errs
        );
        if (errors.length > 0) {
            mod.controls.errorOverlay.show(errors);
            return;
        }

        const [nodeRows, edgeRows] = await Promise.all([nodesDataView.allRows(), edgesDataView.allRows()]);
        if (nodeRows == null || edgeRows == null) {
            mod.controls.errorOverlay.show("No nodes or edges to render.");
            return;
        }

        mod.controls.errorOverlay.hide();

        // Render the network graph.

        context.signalRenderComplete();
    }
});
```

--------------------------------

### Reference layer manifest configuration

Source: https://spotfiresoftware.github.io/spotfire-mods/docs/action-mods/snippets

Manifest file definition for the reference layer script.

```json
{
    "id": "reference-layer-color-scale",
    "name": "Give a reference layer an independent color scale",
    "description": "Adds a reference layer to a bar chart and colors it independently of the parent chart.",
    "file": "build/reference-layer-color-scale.js",
    "entryPoint": "referenceLayerColorScale",
    "parameters": [
        { "name": "visual", "type": "Visualization", "description": "The bar chart to add the reference layer to." }
    ]
}
```
Tokens:
Raw