How to transition existing visualizations from JSViz to Mods

Introduction

If previous JavaScript based custom visualizations has been based on the JavaScript Visualization Framework, this article attempts to provide a walkthrough of the main differences and the steps that might need to be taken to transition existing plots to the Mods version.

First off, is it worth the effort? There is no one answer to this. The Mods framework provide a certain set off features that JSViz does not and the other way around.

Difference between Mods and JSViz

• Mods is part of the core product, which makes the Mods framework officially supported by Spotfire customer support. (The custom javascript developed externally by the developer excluded).
• Mods can be used to visualize external (In-db) data and real-time streaming data, where as JSViz can only visualize with inmemmory (imported) data.
• Mods can autogenerate UI components such as, property dialogs, axis selectors, legends out of the Mods manifest definition, where as in JSViz these have to be custom coded.
• JSViz has multi-table support where as Mods can only visualize data from a single underlying data table.

Plot definition and UI.

In JSViz, the structure of the plot, bar data selection which is done either programmatically through the .NET API, and also in the property dialog by choosing data tables and defining column expressions for the columns needed, and an optional base HTML resource, is done programmatically in the JavaScript that creates the chart graphics. In contrast, with JSViz, creating all the interactions controls and meta information display such as legends is completely up for the chart developer to create programmatically.

Mods, on the other hand, use a declarative definition of the plot, using a manifest file that specifies axes, properties and other resources upfront. This allows Spotfire to create the UI components such as axis selectors for left, bottom and right locations as well as other dimensions such as colors and size. The use of manifest also allows for the autogenerate the plot legend, as spotfire now "knows" about these selections and can provide controls for them both for changing settings and showing current selections.

Currently, UI:s for setting unique plot specific properties will need to be custom implemented in JavaScript for Mods as well as JSViz.

Example mods-manifest.json

{
    "apiVersion": "1.0",
    "version": "1.0",
    "name": "BarChart example using googlecharts",
    "id": "basic-barchart-googlecharts",
    "icon": "icon.svg",
    "properties": [
        {
            "name": "orientation",
            "type": "string",
            "defaultValue": "vertical"
        },
        {
            "name": "stacking",
            "type": "string",
            "defaultValue": "side-by-side"
        }
    ],
    "dataViewDefinition": {
        "colorAxis": {
            "mode": "dual",
            "dropTarget": {
                "icon": "Color",
                "description": "Color by {0}"
            }
        },
        "axes": [
            {
                "name": "X",
                "mode": "categorical",
                "placement": "bottom",
                "dropTarget": {
                    "icon": "XAxis3D",
                    "description": "Use {0} on the mod's X-axis"
                }
            },
            {
                "name": "Y",
                "mode": "continuous",
                "placement": "left"
            }
        ]
    },
    "files": [
        "index.html",
        "main.css",
        "main.js"
    ]
}

Data access

JSViz, through the use of the utility library JSViz.js, hides most of the data retrieval and requires only that the developer defines and provides a method that takes a sfData object as an argument as such:

// JSViz
// The JSViz.js will automagically pick up on the renderCore functions existence
// and try to execute it with fresh data from Spotfire every time data changes. 

function renderCore (sfData){
    //
    // rendering logic goes here
    //
}

The JSViz.js library file will automatically initiate a query to the Spotfire dataengine and retrieve data from Spotfire and package it into a data object consisitng of meta data and rows and columns from the underlying data tables when the JSViz model triggers the browser side JavaScript render event, and call the renderCore method with this data object as the argument. The sfData object will typically contain all the data and metadata that can be retrieved from the underlying data tables and document properties as configured in the JSViz property dialog UI, in one pass.

Mods, However, provides a more finegrained apporach to where supplying the render logic and data retrieval is decoupled.

A reader, is created by specifying what data should be read. This reader is subsequently used to subscribe a method, typically the equivalent of JSViz renderCore, when this data changes. 

//Mods
//First create a reader that will subscribe to the appropriate data items.

    const reader = mod.createReader(
        mod.visualization.data(),
        mod.property("myproperty1"),
        mod.property("myproperty2"),
        mod.windowSize()
    );

// Second, subscribe a method to be executed on data changes to the reader created above.

    reader.subscribe(render);

However, contrary to JSViz, in the Mods case, after the render method has been invoked, the data in the data view remains to be queried for data content from Spotfire as below.

async function render(dataView, property1, property2) {
        /**
         * Check the data view for errors
         */
        let errors = await dataView.getErrors();
        if (errors.length > 0) {
            // Showing an error overlay will hide the mod iframe.
            // Clear the mod content here to avoid flickering effect of
            // an old configuration when next valid data view is received.
            mod.controls.errorOverlay.show(errors);
            return;
        }
        mod.controls.errorOverlay.hide();

        /**
         * Get rows from dataView
         */
        const rows = await dataView.allRows();
        if (rows == null) {
            // User interaction caused the data view to expire.
            // Don't clear the mod content here to avoid flickering.
            return;
        }
    //
    //Render logic here
    //
}