Updated to Mods API v1.3

Updated relevant examples to use the new Tooltip.show method.
spotfiresoftware · Oct 8, 2021 · a1dae85 · a1dae85
1 parent a500f35
commit a1dae85
Show file tree

Hide file tree

Showing 43 changed files with 3,577 additions and 12,408 deletions.
diff --git a/README.md b/README.md
@@ -29,6 +29,7 @@ The Mods API is backwards compatible but not forwards compatible. Pick a Mod API
 | Spotfire 11.0    | 1.0             |
 | Spotfire 11.3    | 1.1             |
 | Spotfire 11.4    | 1.2             |
+| Spotfire 11.5    | 1.3             |
 
 When a mod is trying to use newer API features without updating the [`apiVersion`](https://github.com/TIBCOSoftware/spotfire-mods/blob/7be343f007d2ec9f3d36e5078419b57674db8467/examples/js-dev-barchart/src/mod-manifest.json#L2) in the `mod-manifest.json` the following happens.
 

diff --git a/examples/js-areachart-d3/spotfire/mod-schema.json b/examples/js-areachart-d3/spotfire/mod-schema.json
@@ -156,8 +156,8 @@
             "type": "string",
             "title": "Mod API version.",
             "description": "Specifies the version of the Mod JavaScript API used by the code of this Mod. Set the lowest possible version number that the Mod requires to ensure best possible backward compatibility with older Spotfire systems. Using a newer API version than specified will result in runtime errors, even if the current Spotfire system includes that API.",
-            "default": "1.0",
-            "examples": ["1.0"],
+            "default": "1.3",
+            "examples": ["1.0", "1.1", "1.2", "1.3"],
             "pattern": "^(.*)$"
         },
         "name": {
@@ -186,9 +186,7 @@
             "description": "Only declared external resources will work in the mod. A visualization mod with external resources cannot be exported using the web client.",
             "items": {
                 "type": "string",
-                "examples": [
-                    "https://www.example.com"
-                ]
+                "examples": ["https://www.example.com"]
             }
         },
         "properties": {
@@ -343,6 +341,21 @@
                             }
                         ]
                     }
+                },
+                "tooltip": {
+                    "type": "object",
+                    "title": "Use configurable tooltips",
+                    "description": "Specifies how the Mod uses Spotfire native style configurable tooltips. Added in API version 1.3",
+                    "default": {},
+                    "additionalProperties": false,
+                    "properties": {
+                        "enabled": {
+                            "type": "boolean",
+                            "title": "Enabled",
+                            "default": true,
+                            "description": "Specifies whether to enable configurable tooltips, both in the API and in the properties dialog."
+                        }
+                    }
                 }
             }
         },
@@ -375,11 +388,7 @@
                 "type": "string",
                 "title": "The Items Schema",
                 "default": "",
-                "examples": [
-                    "index.html",
-                    "main.css",
-                    "main.js"
-                ],
+                "examples": ["index.html", "main.css", "main.js"],
                 "pattern": "^(.*)$"
             }
         }

diff --git a/...eachart-d3/spotfire/spotfire-api-1-2.d.ts → ...eachart-d3/spotfire/spotfire-api-1-3.d.ts b/...eachart-d3/spotfire/spotfire-api-1-2.d.ts → ...eachart-d3/spotfire/spotfire-api-1-3.d.ts
@@ -1,5 +1,5 @@
 /*
- * Copyright © 2020. TIBCO Software Inc.
+ * Copyright © 2021. TIBCO Software Inc.
  * This file is subject to the license terms contained
  * in the license file that is distributed with this file.
  */
@@ -1373,6 +1373,24 @@ export declare interface Reader<T extends ReadonlyArray<any>> {
      * readables specified when the reader was created.
      */
     hasExpired(): Promise<boolean>;
+    /**
+     * Check whether one or more passed arguments are new since the last time the subscribe loop was called.
+     *
+     * @example Check if the data view has changed in the subscribe loop.
+     *
+     * ```
+     * let reader = mod.createReader(mod.visualization.data(), mod.windowSize());
+     * reader.subscribe((dataView, size) => {
+     *    console.log(reader.hasValueChanged(dataView));
+     * });
+     * ```
+     *
+     * @param value - Value from `subscribe` or `once` arguments.
+     * @param values - Additional values from `subscribe` or `once` arguments.
+     * @returns true if any of the values are new, otherwise false.
+     * @version 1.3
+     */
+    hasValueChanged(value: UnionFromTupleTypes<T>, ...values: UnionFromTupleTypes<T>[]): boolean;
 }
 
 /**
@@ -1594,14 +1612,34 @@ export declare interface Tooltip {
      * The tooltip is shown using the same style and initial delay as native Spotfire visualizations.
      * Once shown, the tooltip will follow the mouse around until {@link Tooltip.hide} is called.
      *
-     * Subsequent calls to `show`can be made to update the tooltip text.
+     * Subsequent calls to `show` can be made to update the tooltip text.
      * @param content - The text to show in the tooltip.
      */
     show(content: string): void;
+    /**
+     * Shows a tooltip for the specified `row` as it has been configured in the properties panel.
+     *
+     * The tooltip is shown using the same style and initial delay as native Spotfire visualizations.
+     * Once shown, the tooltip will follow the mouse around until {@link Tooltip.hide} is called.
+     *
+     * Subsequent calls to `show` can be made to update the tooltip text.
+     *
+     * @note For this feature to work, the dataViewDefinition.tooltip.enabled in the mod-manifest.json needs to be set to true.
+     *
+     * @param row - The row to show text for in the tooltip.
+     * @version 1.3
+     */
+    show(row: DataViewRow): void;
     /**
      * Hides the tooltip that is currently being showed, if any.
      */
     hide(): void;
 }
 
-export {};
+/**
+ * Extract all possible types in a Tuple type.
+ * @public
+ */
+export declare type UnionFromTupleTypes<T extends readonly any[], U = never> = T[number] | U;
+
+export { }
diff --git a/examples/js-areachart-d3/src/buildSeries.js b/examples/js-areachart-d3/src/buildSeries.js
@@ -25,6 +25,7 @@
  *          y1: number;
  *          marked: boolean;
  *          gapFilled: boolean;
+ *          tooltip: Spotfire.DataViewRow;
  *          }} Point
  */
 
@@ -58,7 +59,8 @@ export function buildColorSeries(colorLeaves, xLeaves, hasX, hasY, stackMode, ga
             marked: row.isMarked(),
             color: row.color().hexCode,
             colorIndex: colorLeaf.leafIndex,
-            gapFilled: false
+            gapFilled: false,
+            tooltip: row
         }))
     }));
 
@@ -85,7 +87,8 @@ export function buildColorSeries(colorLeaves, xLeaves, hasX, hasY, stackMode, ga
                         colorIndex: serie.colorIndex,
                         marked: allMarked,
                         color: !leftPoint.marked ? leftPoint.color : rightPoint.color,
-                        gapFilled: true
+                        gapFilled: true,
+                        tooltip: undefined
                     });
                 }
             }

diff --git a/examples/js-areachart-d3/src/render.js b/examples/js-areachart-d3/src/render.js
@@ -499,7 +499,7 @@ export async function render(state, mod, dataView, windowSize, chartType, rounde
 
         function handleMouseOverPoint(data) {
             g.attr("visibility", "visible");
-            tooltip.show(createPointTooltip(data));
+            tooltip.show(data.tooltip);
         }
 
         function handleMouseOut() {
@@ -652,56 +652,6 @@ export async function render(state, mod, dataView, windowSize, chartType, rounde
             .join("\n");
     }
 
-    /**
-     * Mimic the built in Spotfire tooltip
-     * @param {Point} point
-     * @returns {string}
-     */
-    function createPointTooltip(point) {
-        const separator = "\n";
-        let colorValues = getFormattedValues(colorLeaves[point.colorIndex]);
-        let xValues = getFormattedValues(xLeaves[point.xIndex]);
-        let yDisplayName = yAxisMeta.parts[0].displayName;
-
-        if (yAxisMeta.parts.length > 1) {
-            // Find the corresponding display name for the y axis value for multiple measures.
-            let colorLevelForColumnNames = colorAxisMeta.parts.map((p) => p.expression).indexOf("[Axis.Default.Names]");
-            let xLevelForColumnNames = xAxisMeta.parts.map((p) => p.expression).indexOf("[Axis.Default.Names]");
-            if (colorLevelForColumnNames >= 0) {
-                yDisplayName = colorValues[colorLevelForColumnNames];
-            }
-
-            if (xLevelForColumnNames >= 0) {
-                yDisplayName = xValues[xLevelForColumnNames];
-            }
-        }
-
-        let xLabel =
-            createAxisTooltip(
-                xAxisMeta.parts.map((p) => p.displayName),
-                xValues,
-                separator
-            ) ||
-            (xAxisMeta.parts.length
-                ? createAxisTooltip([xAxisMeta.name + " axis"], [xLeaves[point.xIndex].formattedPath()], separator)
-                : "");
-        let colorLabel =
-            createAxisTooltip(
-                colorAxisMeta.parts.map((p) => p.displayName),
-                colorValues,
-                separator
-            ) ||
-            (colorAxisMeta.parts.length
-                ? createAxisTooltip(
-                      [colorAxisMeta.name + " axis"],
-                      [colorLeaves[point.colorIndex].formattedPath()],
-                      separator
-                  )
-                : "");
-
-        return [xLabel, yDisplayName + ": " + point.Y_Formatted, colorLabel].join(separator);
-    }
-
     /**
      * Popout content
      */

diff --git a/examples/js-areachart-d3/static/mod-manifest.json b/examples/js-areachart-d3/static/mod-manifest.json
@@ -1,6 +1,6 @@
 {
-    "apiVersion": "1.2",
-    "version": "1.1.0",
+    "apiVersion": "1.3",
+    "version": "1.2.0",
     "name": "Area Chart",
     "id": "spotfire-area-chart-mod",
     "icon": "icon.svg",
@@ -22,6 +22,7 @@
         }
     ],
     "dataViewDefinition": {
+        "tooltip": { "enabled": true },
         "colorAxis": {
             "mode": "categorical",
             "dropTarget": {

diff --git a/examples/js-dev-barchart/spotfire/mod-schema.json b/examples/js-dev-barchart/spotfire/mod-schema.json
@@ -156,8 +156,8 @@
             "type": "string",
             "title": "Mod API version.",
             "description": "Specifies the version of the Mod JavaScript API used by the code of this Mod. Set the lowest possible version number that the Mod requires to ensure best possible backward compatibility with older Spotfire systems. Using a newer API version than specified will result in runtime errors, even if the current Spotfire system includes that API.",
-            "default": "1.0",
-            "examples": ["1.0"],
+            "default": "1.3",
+            "examples": ["1.0", "1.1", "1.2", "1.3"],
             "pattern": "^(.*)$"
         },
         "name": {
@@ -186,9 +186,7 @@
             "description": "Only declared external resources will work in the mod. A visualization mod with external resources cannot be exported using the web client.",
             "items": {
                 "type": "string",
-                "examples": [
-                    "https://www.example.com"
-                ]
+                "examples": ["https://www.example.com"]
             }
         },
         "properties": {
@@ -343,6 +341,21 @@
                             }
                         ]
                     }
+                },
+                "tooltip": {
+                    "type": "object",
+                    "title": "Use configurable tooltips",
+                    "description": "Specifies how the Mod uses Spotfire native style configurable tooltips. Added in API version 1.3",
+                    "default": {},
+                    "additionalProperties": false,
+                    "properties": {
+                        "enabled": {
+                            "type": "boolean",
+                            "title": "Enabled",
+                            "default": true,
+                            "description": "Specifies whether to enable configurable tooltips, both in the API and in the properties dialog."
+                        }
+                    }
                 }
             }
         },
@@ -375,11 +388,7 @@
                 "type": "string",
                 "title": "The Items Schema",
                 "default": "",
-                "examples": [
-                    "index.html",
-                    "main.css",
-                    "main.js"
-                ],
+                "examples": ["index.html", "main.css", "main.js"],
                 "pattern": "^(.*)$"
             }
         }

diff --git a/...v-barchart/spotfire/spotfire-api-1-2.d.ts → ...v-barchart/spotfire/spotfire-api-1-3.d.ts b/...v-barchart/spotfire/spotfire-api-1-2.d.ts → ...v-barchart/spotfire/spotfire-api-1-3.d.ts
@@ -1,5 +1,5 @@
 /*
- * Copyright © 2020. TIBCO Software Inc.
+ * Copyright © 2021. TIBCO Software Inc.
  * This file is subject to the license terms contained
  * in the license file that is distributed with this file.
  */
@@ -1373,6 +1373,24 @@ export declare interface Reader<T extends ReadonlyArray<any>> {
      * readables specified when the reader was created.
      */
     hasExpired(): Promise<boolean>;
+    /**
+     * Check whether one or more passed arguments are new since the last time the subscribe loop was called.
+     *
+     * @example Check if the data view has changed in the subscribe loop.
+     *
+     * ```
+     * let reader = mod.createReader(mod.visualization.data(), mod.windowSize());
+     * reader.subscribe((dataView, size) => {
+     *    console.log(reader.hasValueChanged(dataView));
+     * });
+     * ```
+     *
+     * @param value - Value from `subscribe` or `once` arguments.
+     * @param values - Additional values from `subscribe` or `once` arguments.
+     * @returns true if any of the values are new, otherwise false.
+     * @version 1.3
+     */
+    hasValueChanged(value: UnionFromTupleTypes<T>, ...values: UnionFromTupleTypes<T>[]): boolean;
 }
 
 /**
@@ -1594,14 +1612,34 @@ export declare interface Tooltip {
      * The tooltip is shown using the same style and initial delay as native Spotfire visualizations.
      * Once shown, the tooltip will follow the mouse around until {@link Tooltip.hide} is called.
      *
-     * Subsequent calls to `show`can be made to update the tooltip text.
+     * Subsequent calls to `show` can be made to update the tooltip text.
      * @param content - The text to show in the tooltip.
      */
     show(content: string): void;
+    /**
+     * Shows a tooltip for the specified `row` as it has been configured in the properties panel.
+     *
+     * The tooltip is shown using the same style and initial delay as native Spotfire visualizations.
+     * Once shown, the tooltip will follow the mouse around until {@link Tooltip.hide} is called.
+     *
+     * Subsequent calls to `show` can be made to update the tooltip text.
+     *
+     * @note For this feature to work, the dataViewDefinition.tooltip.enabled in the mod-manifest.json needs to be set to true.
+     *
+     * @param row - The row to show text for in the tooltip.
+     * @version 1.3
+     */
+    show(row: DataViewRow): void;
     /**
      * Hides the tooltip that is currently being showed, if any.
      */
     hide(): void;
 }
 
-export {};
+/**
+ * Extract all possible types in a Tuple type.
+ * @public
+ */
+export declare type UnionFromTupleTypes<T extends readonly any[], U = never> = T[number] | U;
+
+export { }
diff --git a/examples/js-dev-barchart/src/main.js b/examples/js-dev-barchart/src/main.js
@@ -363,7 +363,7 @@ Spotfire.initialize(async (mod) => {
                 segment.style.backgroundColor = row.color().hexCode;
 
                 segment.onmouseover = (e) => {
-                    mod.controls.tooltip.show(xLeafNode.formattedPath() + ": " + y.formattedValue());
+                    mod.controls.tooltip.show(row);
                 };
                 segment.onmouseout = (e) => {
                     mod.controls.tooltip.hide();

diff --git a/examples/js-dev-barchart/src/mod-manifest.json b/examples/js-dev-barchart/src/mod-manifest.json
@@ -1,6 +1,6 @@
 {
-    "apiVersion": "1.2",
-    "version": "1.0",
+    "apiVersion": "1.3",
+    "version": "1.1",
     "name": "Bar Chart",
     "id": "js-dev-barchart",
     "icon": "icon.svg",
@@ -17,6 +17,7 @@
         }
     ],
     "dataViewDefinition": {
+        "tooltip": { "enabled": true },
         "colorAxis": {
             "mode": "dual",
             "dropTarget": {