本記事はSpotfire 11.0 （What's New in Spotfire® 11.0）にて新規追加された機能 Visualization Mods 「ビジュアライゼーション Mods」の開発方法について紹介します。
概要
- Visualization Modsは拡張子「*.mod」のファイルとしてローカルまたはSpotfireのライブラリに保存し、分析ファイルから使用できます。
- 他のユーザーと共有することも可能です。
- Visualization ModsはSpotfire 11.0 以降のAnalyst、Web Player、Automation Servicesのいずれでも動作します。
- 一つのVisualization Mods内で、１つのビジュアライゼーションタイプを作成することも可能です。
- Spotfire 14.4 からVisualization Modsの開発方法が改善されています。
- Analyst上で動かす場合、Visualization ModsはAnalystに同梱されているChromiumブラウザエンジンによって描画されます。
Visualization Modsの開発は以下の２つの方法で行えます。
- 14.4 より前の開発方法（参考資料）
- 雛形のプロジェクト（js-dev-starter）やサンプルプロジェクト（例：js-dev-barchart）を複製して、コードを実装します。
- Mods development server by TIBCO Spotfire®（@tibco/spotfire-mods-dev-server）を利用します。
- JavaScriptやTypeScriptを利用しています。
- この方法は今後廃止される可能性があると思われます。
- 14.4 以降の開発方法（参考資料）
- Spotfire Mods SDK（@spotfire/mods-sdk）を利用してプロジェクトを生成して、コードを実装します。
- 主にTypeScriptを利用しています。
- Spotfire 14.4 より前のバージョン（11.4 / 12.0 / 14.0 など）でもこの方法で開発したModsを利用できます。
本記事は「14.4以降の開発方法」を利用して Spotfire 14.0 LTS にて利用するVisualization Modsの開発方法を説明します。
動作環境
- Spotfire Server 14.0 LTS
- Spotfire Analyst 14.0 LTS ※no-server版でもVisualization Modsの開発や利用は可能です。
- Spotfire Web Player 14.0 LTS
- Spotfire Automation Services 14.0 LTS
利用方法
Visualization Mods（*.mod）がローカルに保存されている場合、直接Spotfire Analystへドラッグアンドドロップして、ビジュアライゼーションを作成できます。
通常、管理者がVisualization Mods（*.mod）をライブラリに保存し、「ビジュアライゼーション・タイプ」フライアウトに追加しておきます。そして、一般ユーザーは標準のビジュアライゼーションと同様に「ビジュアライゼーション・タイプ」フライアウトからビジュアライゼーションを作成できます。
分析が参照しているVisualization Mods（*.mod）は分析内に埋め込まれますので、他のSpotfire環境でも正しく動作します。
Visualization Modsを他人から利用する場合、または他の環境へ移行する場合は署名の検証や信頼の実施などが必要となりますが、本記事の対象外となります。
利用条件
Visualization Modsを利用するには、対象ユーザーによって適切なライセンスを付与する必要があります。
Modsを利用するにあたり、ユーザーを以下の３種類に分けてライセンス管理を行うことを推奨します。
-
Mods開発者・管理者：Modsの開発および管理を行うAnalystユーザー
- Modsを開発を行い、Modsをライブラリに保存・公開するユーザー。
-
Mods使用者：通常のAnalystユーザー
- ライブラリに保存されているModsを利用して分析を作成するユーザー。
- Modsを集中管理するため、ローカルModsの使用を禁止することを推奨。
-
Mods閲覧者：通常のConsumerユーザー
- Modsが利用されている分析を閲覧するユーザー。
- Mods関連ライセンスの付与は不要です。
| No. |
ライセンス |
説明 | Mods開発者・管理者に付与 | Mods使用者に付与 | Mods閲覧者に付与 |
|---|---|---|---|---|---|
| 1 | mod を開発する | Spotfire でビジュアライゼーション modまたはアクション modを作成および開発できるようになります。 | 〇 | × | × |
| 2 | mod を信頼 | 他の開発者が開発した mod を信頼することができるようになります。 | 〇 | × / 〇 | × |
| 3 | ビジュアライゼーション mod をライブラリーに保存 | ビジュアライゼーション mod (.mod ファイル) をライブラリーに保存できるようになります。 | 〇 | × | × |
| 4 | ライブラリーからビジュアライゼーション mod を開く | ライブラリーからビジュアライゼーション mod (.mod ファイル) を開くことができるようになります。 | 〇 | 〇 | × |
| 5 | ローカル ビジュアライゼーション mod を開く/保存 | ローカルのビジュアライゼーション mod (.mod ファイル) を開くまたは保存できるようになります。 | 〇 | × | × |
ライセンスの付与はSpotfire管理者がAnalystのツール⇒管理マネージャー画面にて行えます。
開発概要
Visualization ModsはJavaScript / TypeScript言語でコードを記述し開発します。
利用できるAPIは以下になります。
- Visualization Mods API （参考資料）
- JavaScript / TypeScript API
- サードパーティーJavaScriptライブラリ（例：Plotly、D3.js、Chart.js、Google Charts など）
- Google Chartsを利用する場合は外部リソースとして参照しますが、外部リソースを参照する場合は仕様制限としてブラウザからModsビジュアライゼーションをエクスポートできません。（参考資料：A visualization mod with external resources cannot be exported using the web client.）
開発環境
Visualization Modsを開発するには以下の開発環境を準備する必要があります。
- Spotfire Analyst 14.0
- テストやModsファイルの作成のために使用します。
- Visualization Modsの保存（ローカルまたはライブラリへ）も実施できます。
- Visual Studio Code （ダウンロードリンク）
-
- コードの開発のために使用します。
- IntelliSense（型のチェック、関数名の提示など）が利用可能です。
-
- Node.js 20.0 LTS 以降 （ダウンロードリンク）
- Visualization Modsプロジェクトの新規作成、構成管理、開発サーバーの起動などのために使用します。
- コマンドプロンプトから実行できるように「node.exe」の格納先フォルダのパスをユーザー環境変数「PATH」に追加してください。
注意事項： サードパーティのソフトウェアまたはサービスを入手する場合、そのようなサードパーティのソフトウェアまたはサービスに関連するライセンス条項を理解し、かかる条項に従うのはお客様の責任です。
開発手順
Visualization Modsの開発は以下の手順で行います。
１．作業フォルダの作成
作業フォルダ（中身が空のフォルダを推奨）を新規作成します。
例：
C:\vismod
２．プロジェクトの新規作成
コマンドプロンプトを起動し、作業フォルダへ移動して以下のコマンドを実行してVisualization Modsプロジェクトを新規作成します。
npx @spotfire/mods-sdk new visualization
コマンドを初回実行する際にはNPMパッケージ（@spotfire/mods-sdk）のインストールが必要です。「y」を入力して進みます。
NPMパッケージのインストールが完了した後に、Visualization Modsプロジェクトが新規作成されます。
３．依存パッケージのインストール
続いて以下の２つのコマンドを実行します。
npm install
npm run build
Visualization Modsプロジェクトに必要なNPMパッケージのインストールやビルドが行われます。
作業フォルダには以下のフォルダやファイル等が生成されます。
- Visualization Modsソースコード
- mod-manifest.json
- env.d.ts
- 「src」フォルダ
- icon.svg
- index.html
- main.css
- npmプロジェクトファイル
- package.json
- package-lock.json
- Visual Studio Code設定ファイル
- 「.vscode」フォルダ
- TypeScript設定ファイル
- tsconfig.json
- esbuild設定ファイル
- esbuild.config.js
作成されたVisualization Modsプロジェクトの概要は以下のファイル（参考資料：Mod Schema）から確認できます。必要に応じてバージョンやID、名前などを変更してください。
.\mod-manifest.json
例：
{
"apiVersion": "1.3", ※参照しているVisualization Mods APIのバージョン
"version": "1.0", ※本Modsのバージョン
"name": "Vismod", ※本Modsの名前（自動的に格納先フォルダから設定）
"id": "vismod", ※本ModsのID
"icon": "icon.svg", ※本Modsのアイコン
"properties": [ ※本Modsのプロパティ（例として追加済み）
{
"name": "myProperty",
"type": "string",
"defaultValue": "myValue"
}
],
"dataViewDefinition": { ※軸の定義
"colorAxis": { ※「色の基準」軸（例として追加済み）
"mode": "dual",
"dropTarget": {
"icon": "Color",
"description": "Color by {0}"
}
},
"axes": [
{
"name": "X", ※X軸（例として追加済み）
"mode": "categorical", ※カテゴリ軸（文字列などのカテゴリのみを設定可能）
"placement": "bottom", ※軸セレクターの位置
"dropTarget": {
"icon": "XAxis3D",
"description": "Use {0} on the mod's X-axis"
}
},
{
"name": "Y", ※Y軸（例として追加済み）
"mode": "continuous", ※連続軸（数値などの連続値のみを設定可能）
"placement": "left" ※軸セレクターの位置
}
]
},
"files": ["index.html", "main.css", "build/main.js"] #Modsを構成したファイルの一覧
}
４．コードの開発
Visual Studio Codeを使って作業フォルダを開いてコードを書きます。
デフォルトでは以下のスクリプトが生成されます。
.\src\main.ts
ビジュアライゼーションの描画処理は「Spotfire.initialize(...)」関数内で書きます。
デフォルトで生成されたコードでは、以下の部分がビジュアライゼーションの描画部分を実装しています。
/**
* Print out to document
*/
const container = document.querySelector("#mod-container");
if (!container) {
mod.controls.errorOverlay.show(
"Failed to find the DOM node with id #mod-container which should contain the visualization."
);
return;
}
container.textContent = `windowSize: ${windowSize.width}x${windowSize.height}\r\n`;
container.textContent += `should render: ${xRoot.rows().length} rows\r\n`;
container.textContent += `${prop.name}: ${prop.value()}`;
「#mod-container」はIDが「mod-container」の<div>として「index.html」内で定義されておりますが、Modsビジュアライゼーションがこの中で描画されます。
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta http-equiv="X-UA-Compatible" content="IE=edge" />
<title>Spotfire Mod Example</title>
<meta name="viewport" content="width=device-width, initial-scale=1" />
<link rel="stylesheet" type="text/css" media="all" href="main.css" />
</head>
<body>
<div id="mod-container"></div>
<script id="spotfire-loader">
...省略
</script>
<script src="build/main.js"></script>
</body>
</html>
５．開発サーバーの起動
Visual Studio Codeのメニュー：Terminal⇒Run Task...を実行して、「Start watchers」を選択し、開発サーバーを起動します。開発サーバーはデフォルトではポート「8090」を使って動作します。
起動後にブラウザ画面（http://127.0.0.1:8090/mod-manifest.json）が開かれますが、閉じても構いません。
Visual Studio Codeのメニュー：Terminal⇒Run Build Task...（Ctrl＋Shift＋B）を実行して開発サーバーを起動することも可能です。
いずれかの方法で起動した後には以下の３つのタスクが起動され、対応のターミナルが表示されます。
- Mods dev server：Spotfire から接続できる開発サーバー（ポート番号8090で動作）を起動。
- TypeScript watcher：型安全を確保するためにソースコードの変更を監視。
- Mods build watcher：ソースコードに変更があった場合に自動的にビルドを実施。
開発サーバーを停止するには、Terminal⇒Terminate Task...を実行し「All Running Tasks」を選択してすべてのタスクを停止してください。
６．開発サーバーへの接続
Analystでデータを取り込んで分析を新規作成し、または既存分析を開いて、ツール⇒開発⇒ビジュアライゼーションModsの作成を開きます。
「プロジェクトに接続」⇒「開発サーバー」を押して、URL（デフォルトで「http://127.0.0.1:8090」が指定済み）を入力して「接続」ボタンを押すと、前述で起動した開発サーバーへ接続します。
接続が成功した後に、該当Modsを参照するビジュアライゼーションが自動的に作成されます。
X軸、Y軸、色の基準などは自動的に設定されます。
７．ビジュアライゼーションの追加
開発サーバーに接続した後に該当Modsが「ビジュアライゼーション・タイプ」フライアウトからも利用できるようになります。標準機能のビジュアライゼーションと同様にクリックして新たにビジュアライゼーションを作成することができます。
Spotfire Analyst 14.0.5 HF-018までのバージョンでは既知問題として、開発サーバーに接続した状態で「ビジュアライゼーション・タイプ」フライアウトからModsをクリックしてビジュアライゼーションを追加すると該当Modsが「ビジュアライゼーション・タイプ」フライアウトから消えます。
問題が発生した後に、上記の「６．開発サーバーへの接続」再度実行してModsを「ビジュアライゼーション・タイプ」フライアウトへ追加することで暫定対応できます。また、本件問題はSpotfire Analyst 14.0.5 HF-019（2024/12/05にリリース済）にて修正されました。
８．デバッグ
Analyst機能「開発者ツール」を利用してVisualization Modsをデバッグすることができます。
Action ModsのようにVisual Studio Code内でのデバッグは対応されていません。
「開発者ツール」はデフォルトでは利用できない状態になっていますが、ツール⇒オプションを開いて、「アプリケーション」タブにて「開発メニューの表示」をチェック入れて、Analystを一旦再起動すると、開発者ツールが利用可能になります。
ツール⇒開発⇒開発者ツールを押して起動します。
こちらのツールはGoogle ChromeやMicrosoft Edgeの開発者ツールとは機能や使い方は同じです。
任意タブ上で「Ctrl＋P」を押して、「src」を入力してソースファイルを検索し、結果内にある「main.ts」をクリックして開きます。
「main.ts」のソースコード内でブレークポイントを追加し、Modsビジュアライゼーションのサイズを変更するなどで再描画させて、ブレークポイントに処理を止めて変数の値の確認などを行えます。
ツールバーにあるアイコンを押してデバッグ実行も可能です。
・F8：Resume
・F10：Step over
・F11：Step in
・Shift＋F11：Step out
・F9：Step
・Ctrl＋F8：Deactivate breakpoints
ここでソースコードを編集してもModsの画面表示や元のプロジェクトには反映されません。
９．Visualization Modsの配布
開発完了後に、「Modの開発」画面で「切断」を押して開発サーバーから切断してから、「ローカルファイルとして保存」または「ライブラリーに保存」を押して、対象Visualization Modsをローカルファイル、またはライブラリへ保存します。
保存したVisualization Modsファイルは他人に共有して利用することは可能です。
切断する前に、もう一度以下のコマンドを実行して、Visualization Modsのソースコードをビルドすることを推奨します。
ビルドを実行すると、ソースコードが最小化（minimized）、かつ難読化（obfuscated）されます。
npm run build
１０．Visualization Modsの利用
Visualization Modsの開発が完了した後に、管理者（Spotfire管理者権限が必要）が以下の手順で一般ユーザーに公開することを推奨します。
また、Visualization ModsからModsビジュアライゼーションを作成した場合には該当Visualization Modsが分析内に埋め込まれますので、下記の手順でVisualization Modsを公開していない環境内でも利用可能です。
１．Visualization Modsをライブラリに保存します。
ライブラリに保存された場合はライブラリIDによって参照されますので、格納先が変更されても参照できます。
２．Visualization Modsを「ビジュアライゼーション・タイプ」フライアウトに追加します。
「ビジュアライゼーション・タイプ」にて「ライブラリー内のビジュアライゼーションを検索」を実施して上記で保存したVisualization Modsを検索します。
検索結果から、公開したいVisualization Modsに対して「ビジュアライゼーションに固定」を実施し、「ビジュアライゼーション・タイプ」フライアウトに追加します。
※複数のVisualization Modsを追加することも可能です。
「ビジュアライゼーション・タイプ」フライアウトに追加されたVisualization Modsを確認したうえで、「固定されたビジュアライゼーションに関する情報をクリップボードにコピーします」を実施し、情報をクリップボードにコピーします。
ツール⇒管理マネージャーを開いて、「設定」タブにて公開対象グループ（本例は「Everyone」）を選択し、編集ボタンを押して以下の設定項目に貼り付けてください。
・Application ⇒ Mods：Pinned visualization mods
３．Analystを一旦閉じて再度起動し、上記の設定内容が反映されていることを確認してください。
設定されたVisualization Modsは常に「ビジュアライゼーション・タイプ」フライアウトの上部に表示されます。
コードの開発
Visual Studio Code内で「main.ts」などのファイルを編集した場合には、変更内容が自動的にAnalystに反映されますので、リロードや更新などの操作は不要です。
マニフェストの再ロード
「mod-manifest.json」が変更された場合、Modsビジュアライゼーションのタイトルバーに表示されているアイコン「Modの開発」を押して表示されたポップアップ画面にて「マニフェストを再ロード」を押して再ロードする必要があります。
「mod-manifest.json」が変更された後に「マニフェストを再ロード」を実施していない場合にはコードへの変更がAnalystへ反映されない可能性があります。
Visualization Mods APIのバージョン変更
2024/12現在（@spotfire/mods-sdk 1.0.1を使用）、Visualization Modsプロジェクトを新規作成した場合はデフォルトでVisualization Mods API 1.3を利用しています。ほかのバージョンのAPIを利用したい場合は以下の手順でAPIのバージョンを変更してください。
利用可能なAPIバージョンの一覧はこちらを参照ください。
１．「mod-manifest.json」内にAPIのバージョン（本例は1.2）を指定してください。
"apiVersion": "1.2",
例：
２．「package.json」内にAPIのバージョン（本例は1.2）を指定してください。
「~1.2.0」を指定した場合、すべての1.2.Xバージョン（Xはパッチリリース）が利用できます。
"@spotfire/mods-api": "~1.2.0",
例：
３．以下のコマンドを実行して対象バージョンのAPIをインストールしてください。
npm install
インストール後に以下のコマンドを実行して対象バージョンのAPIがインストールされていることを確認してください。
npm list
開発者ツールのコンソール内でのデバッグ
下記の手順で「main.ts」内の変数をグローバル変数に渡すことで、開発者ツールの「Console」タブ内でグローバル変数を参照して値を確認することができます。開発が完了した後にはグローバル変数の削除を推奨します。
１．「env.d.ts」内で、グローバル変数を宣言します。
グローバル変数のデータ型は参照しようとするローカル変数のデータ型に一致する必要があります。
declare global {
var mod: Spotfire.Mod,
var dataView: Spotfire.DataView,
var allRows: DataViewRow[] | null,
}
export {}
例：
２．「main.ts」内で、ローカル変数を上記で宣言したグローバル変数に渡します。
Spotfire.initialize(async (mod: Spotfire.Mod) => {
globalThis.mod = mod;
...省略
例：
３．開発者ツールのコンソールタブ（「Console」タブ）にて、上記のグローバル変数を参照します。
まずは左上のドロップダウンリストから「127.0.0.1:8090」を選択してください。「top」が選択されている状態では上記のグローバル変数を参照できません。
コードを入力して上記のグローバル変数を参照します。
ソースファイルの追加
共通メソッドをモジュールとして開発するなどの場合、以下の手順で新たにソースファイル（「*.ts」ファイル）をVisualization Modsプロジェクトに追加して利用できます。
１．「src」のフォルダの下にソースファイル（本例：Utils.ts）を新規作成し、モジュール（関数、定数など）を定義します。
export const resources = {
PADDING: 120,
LINEWEIGHT: 3
};
export function log(message: string) {
// 処理を実装
console.log(message);
};
例：
２．「main.ts」内で、上記のファイルからモジュールをインポートします。
import { resources, log } from './Utils'
Spotfire.initialize(async (mod: Spotfire.Mod) => {
例：
３．「main.ts」内で、インポートしたモジュールを利用します。
async function render(dataView: Spotfire.DataView, windowSize: Spotfire.Size, prop: Spotfire.ModProperty<string>) {
log('render');
log('PADDING=' + resources.PADDING);
context.signalRenderComplete();
}
例：
サードパーティーJavaScriptライブラリの利用
Visualization ModsからサードパーティーJavaScriptライブラリを利用することが可能です。
詳細はコード例の部分を参照ください。
Visualization Modsをビルドした後に、利用しているサードパーティーJavaScriptライブラリのコードが対象Visualization Modsのファイル内に埋め込まれます。
コード例
Plotly.jsの利用
下記の手順でPlotly.js（ホームページ、npmパッケージ）を利用することができます。
１．依存npmパッケージをインストールします。
npm add --save-dev plotly.js-dist-min @types/plotly.js-dist-min
２．「main.ts」の先頭にて、Plotly.jsをインポートします。
import Plotly from 'plotly.js-dist-min'
Spotfire.initialize(async (mod: Spotfire.Mod) => {
例：
３．グラフ描画部分のコード（参考資料）を書きます。（本例はSpotfire内のデータを使っていません）
※データ型「any」を指定することでコンパイルエラーを回避できます。
var data: any = [
{
x: ['giraffes', 'orangutans', 'monkeys'],
y: [20, 14, 23],
type: 'bar'
}
];
Plotly.newPlot('mod-container', data);
例：
上記で実装したModsビジュアライゼーションは以下のように描画されます。
Chart.jsの利用
下記の手順でChart.js（ホームページ、参考資料）を利用することができます。
１．依存npmパッケージをインストールします。
npm install --save-dev @types/chart.js chart.js
２．「main.ts」の先頭にて、Chart.jsをインポートします。
import Chart from 'chart.js/auto';
Spotfire.initialize(async (mod: Spotfire.Mod) => {
３．「index.html」を編集して、<div>を<canvas>に変更します。
変更前：
<div id="mod-container"></div>
変更後：
<canvas id="mod-container"></canvas>
４．グラフ描画部分のコード（参考資料）を書きます。（本例はSpotfire内のデータを使っていません）
const xValues = [50, 60, 70, 80, 90, 100, 110, 120, 130, 140, 150];
const yValues = [7, 8, 8, 9, 9, 9, 10, 11, 14, 14, 15];
new Chart("mod-container", {
type: "line",
data: {
labels: xValues,
datasets: [{
backgroundColor: "rgba(0,0,255,1.0)",
borderColor: "rgba(0,0,255,0.1)",
data: yValues
}]
},
options: {}
});
上記で実装したModsビジュアライゼーションは以下のように描画されます。
D3の利用
下記の手順でD3（ホームページ）を利用することができます。
１．依存npmパッケージをインストールします。
npm install --save-dev @types/d3 d3
２．「main.ts」の先頭にて、D3をインポートします。
import * as d3 from "d3";
Spotfire.initialize(async (mod: Spotfire.Mod) => {
３．グラフ描画部分のコード（参考資料）を書きます。（本例はSpotfire内のデータを使っていません）
// Set Dimensions
const xSize = windowSize.width;
const ySize = windowSize.height;
const margin = 40;
const xMax = xSize - margin * 2;
const yMax = ySize - margin * 2;
// Create Random Points
const numPoints = 100;
const data = [];
for (let i = 0; i < numPoints; i++) {
data.push([Math.random() * xMax, Math.random() * yMax]);
}
// Append SVG Object to the Page
const svg = d3.select("#mod-container")
.style('width', windowSize.width)
.style('height',windowSize.height)
.text('')
.append("svg")
.append("g")
.attr("transform", "translate(" + margin + "," + margin + ")");
// X Axis
const x = d3.scaleLinear()
.domain([0, 500])
.range([0, xMax]);
svg.append("g")
.attr("transform", "translate(0," + yMax + ")")
.call(d3.axisBottom(x));
// Y Axis
const y = d3.scaleLinear()
.domain([0, 500])
.range([yMax, 0]);
svg.append("g")
.call(d3.axisLeft(y));
// Dots
svg.append('g')
.selectAll("dot")
.data(data).enter()
.append("circle")
.attr("cx", function (d) { return d[0] })
.attr("cy", function (d) { return d[1] })
.attr("r", 3)
.style("fill", "Red");
上記で実装したModsビジュアライゼーションは以下のように描画されます。
参考資料
- Spotfire® Mods Overview
- Working with mods - Getting started
- Developing visualization mods
- Visualization mod manifest schema
- Visualization mods API documentation
- Visualization Mods (exchange)
- Visualization Mods (exchange) ソースコード（一部Modsのみ）
- インターネット接続できない環境でのVisualization Modsの利用
- Spotfireアカウントによって署名されたVisualization Mods利用時の注意事項
- 独自CAで発行した証明書によるModの署名や信頼