5.1.4 カスタムUI作成

カスタムコンポーネントの設定画面はデフォルトだと、パラメーターとしてJSON、もしくは文字列を自由に入力できるようになっています。しかし、これだと作成者と使用者が異なる場合、パラメーターに設定する項目について調べるにはカスタムコンポーネントのソースコードを確認する必要があり、手間がかかります。

そのため、カスタムコンポーネントは設定画面のパラメータの入力欄をカスタマイズすることができます。パラメータの入力欄として、どういった項目を配置するかユーザーが定義して、使用者が入力する項目をわかりやすくすることができます。

5.1.4.1 カスタムUIの作成方法#

カスタムUIは以下の方法で作成できます。カスタムUIには以下の２つの形式があり、それぞれ作成方法が異なります。

SynapseカスタムUI用JSON

コンポーネントへの設定項目を、JSONファイルに記載する方法です。作成するのはJSONファイルだけであり、修正が必要な時もJSONファイルを変更するだけで手軽に行えます。その代わり、Synapseが提供する機能の範囲でしか設定項目は定義できず、複雑なUIの作成はできません。
SynapseカスタムUI用HTML

コンポーネントへの設定項目を、HTMLとJavaScriptで作成します。
HTMLファイルの内容はユーザーが好きなように作成でき、JavaScript, CSS, 画像なども活用することで複雑なUIを実装することができ、さらに多言語なUI実装にも対応しています。ただし、作成には基本的なHTML/JavaScriptの知識が必要になります。
また、単純な実装だとSynapse本体の画面とはルック＆フィールが異なってしまいます。

カスタムUIとして作成できる範囲は画像の赤枠内にある「パラメーター」に関連する要素だけであり、外側の要素は編集できません。

「保存」ボタン

入力したコンポーネントの設定を保存します。
「キャンセル」ボタン

設定ダイアログを閉じます。
名称、自動起動無効

コンポーネント稼働に必須な設定項目です。
スクリプトで使用するファイルをアップロードする(証明書など)

コンポーネント実行時に必要なファイル（証明書など）を管理します。

5.1.4.2 SynapseカスタムUI用JSONファイルの作成#

ここでは、カスタムUI用JSONファイルの作成方法について説明します。

5.1.4.2.1 作成方法#

次の手順で、カスタムUI用JSONファイルを作成することができます。

テキストエディタで空のjsonファイルを作成します。
jsonファイル内に、"parameter_defines"という配列を定義します。

"parameter_defines"の中に、カスタムコンポーネントの画面に表示する入力要素を定義します。その他、"window_size"、"layout"など必要に応じて定義してください。

定義ファイル(json)

{
  "window_size": "auto",
  "parameter_defines": [
    {
      // 入力要素1
    },
    {
      // 入力要素2
    },
    {
      // 入力要素3
    }
    ...
  ]
}

画面に表示する入力要素は、以下の項目によって定義します。

項目	値の種類	必須	説明
window_size	string	×	ウィンドウのサイズ { "window_size" : "small" }のように指定 auto/指定なし - min-width: "400px" small - min-width: "33%" middle - min-width: "50%" large - min-width:"80%"
parameter_defines	object	○	項目の親要素（最上位の階層から１つ下の階層まで入れ子指定可能参考）
name	string	○	入力した値を設定ファイルに保持する際のキー
label	string	○	画面に表示される項目名
type	string	○	入力する値の種類を、以下の中から選択 string：文字列 number：整数 real：実数 select：選択肢
max	number	○	入力の上限 ※typeがnumber・realの場合のみ有効
min	number	×	入力の下限 ※typeがnumber・realの場合のみ有効
select	array	×	選択肢 ※1 typeがselectの場合のみ有効 ※2 選択肢は、"label"と"value"のプロパティを持つオブジェクト配列によって定義してください。例：[{ "label":"option1", "value":1}, { "label":"option2", "value":2}]
default	any	×	デフォルト値
require	bool	○	入力必須か否か
array	bool	×	配列化するか否か
layout	object	×	各項目の幅指定参考 { "layout" : { "col" : 2 }}のようにcolへ1～12を指定省略時はデフォルト6 array,object省略時はデフォルト12

5.1.4.2.2 サンプル#

カスタムUI定義ファイルのサンプルは次の通りです。

{
  "parameter_defines": [
    {
      "name": "host",
      "label": "ホスト",
      "type": "string",
      "default": "localhost",
      "require": true,
      "max":256
    },
    {
      "name": "port",
      "label": "ポート",
      "type": "number",
      "max": 65535,
      "min": 1,
      "default": "12",
      "require": true
    },
    {
      "name": "select",
      "label": "選択",
      "type": "select",
      "select": [
        { "label":"aaa", "value":1},
        { "label":"bbb", "value":2}
      ],
      "default": 1,
      "require": false
    }
  ]
}

次のようなレイアウトとなります。

サンプル１

5.1.4.2.3 入れ子を使ったサンプル#

カスタムUI定義ファイルの入れ子を使ったサンプルは次の通りです。

{
  "window_size": "middle",
  "parameter_defines": [
    {
      "name": "nested",
      "label": "入れ子",
      "type": "object",
      "array": true,
      "parameter_defines": [
        {
          "name": "name",
          "label": "波名",
          "type": "string",
          "require": true,
          "max": 32,
          "default": "signal_5"
        },
        {
          "name": "freq",
          "label": "周波数",
          "type": "select",
          "require": true,
          "select": [
            { "label": "1.0", "value": 1.0 },
            { "label": "2.0", "value": 2.0 }
          ],
          "default": 1.0
        },
        {
          "name": "amp",
          "label": "振幅",
          "type": "real",
          "require": true,
          "max": 100.0,
          "min": 0.1,
          "default": 1.0
        }
      ],
      "require": false,
      "default": [
        {
          "name": "signal_1",
          "freq": 1,
          "amp": 1.1
        },
        {
          "name": "signal_2",
          "freq": 2,
          "amp": 1.2
        }
      ]
    }
  ]
}

次のようなレイアウトとなります。

サンプル２

5.1.4.2.4 項目の幅を指定したサンプル#

カスタムUI定義ファイルの項目幅を指定したサンプルは次の通りです。

{
  "parameter_defines": [
    {
      "name": "item1",
      "label": "項目1",
      "type": "string",
      "require": false,
      "max": 32,
      "default": "こうもく１",
      "layout": {
        "col": 2
      }
    },
    {
      "name": "item2",
      "label": "項目2",
      "type": "real",
      "require": false,
      "max": 32,
      "default": "12.3",
      "mask": true,
      "layout": {
        "col": 4
      }
    },
    {
      "name": "item3",
      "label": "項目3",
      "type": "select",
      "require": false,
      "max": 32,
      "default": 2,
      "select": [
        { "label": "A", "value": 1},
        { "label": "B", "value": 2},
        { "label": "C", "value": 3}
      ],
      "layout": {
        "col": 6
      }
    }
  ]
}

次のようなレイアウトとなります。

サンプル３

5.1.4.3 SynapseカスタムUI用HTML作成、適用方法#

ここでは、カスタムUIをHTMLとJavaScriptで作成する方法について説明します。

5.1.4.3.1 作成方法#

HTML形式でのカスタムUIを利用するには、下記の環境が必要です。まずはこの環境を準備してください。

カスタムコンポーネント開発環境(SCCDE)

以下のいずれかのコマンドで、HTML形式のカスタムUIを含むサンプルコンポーネントを追加できます。

$ sccde add -t collector -u html
$ sccde add -t emitter -u html

実際のHTMLファイルは、parameter_ui配下のコンポーネント個別のディレクトリ内に配置されます。作成されたサンプルを元に、html, js, cssファイルをカスタマイズして利用してください。

5.1.4.3.2 HTML形式の詳細#

HTMLファイル(index.html)

通常のHTMLと同様に、HTMLタグ、BODYタグを使って定義できます。このファイルで定義した内容が、カスタムコンポーネントのパラメータ設定ダイアログの文字列入力部の代わりに表示されます。

表示例
JavaScriptファイル(index.js)

ダイアログ表示時、および、パラメータ保存時に、所定の関数呼び出しが必要なため、JavaScriptでその関数を定義する必要があります。このJavaScriptファイルはHTMLファイル内の<script>タグで読み込むようにしてください。

詳細は後述

多言語対応UIの実装形式について

多言語対応のUIを実装する場合、以下の形式に沿った内容で作成する必要があります。

静的な実装方法(HTMLファイル)
管理コストは増えますが、シンプルな運営方法となります。
ファイル名をindex.{言語コード}.htmlにして、言語ごとに別々のHTMLファイルを用意します。{言語コード}は例えば日本語の場合ja、英語の場合enと記載します。ファイルの中身は、ファイル名の言語に合わせた内容で記載する必要があります。
動的な実装方法(JavaScriptファイル)
ファイル管理に手がかかりませんが、関数での処理が必要となります。
カスタムUIを読み込む際の関数に、現在の表示言語の設定を識別するlocaleパラメータを使用することで、動的な多言語切替が可能です。詳細はonLoad()関数の使用方法をご確認ください。

scc-info.jsonファイル

カスタムコンポーネントでカスタムUI(HTML)を使用することをシステムに伝えるため、対象コンポーネントの下記の定義が必要です。

プロパティ	説明
parameter-ui-type	'html'を指定
parameter-ui-size	パラメータダイアログの画面サイズ指定。'small','middle','large','auto'から選択可能。（デフォルトは'middle'）
parameter-ui	HTMLファイルやJavaScriptファイルを含むディレクトリへのパスを指定

5.1.4.3.3 JavaScriptファイルの記述#

以降では、サンプルのindex.jsのソースコードを例に、カスタムUIをHTMLで実装する際のJavaScriptにおいての処理方法を説明します。

JavaScriptでSynapseの情報を取り扱えるようにするため、Synapse専用のAPIオブジェクトを提供しています。このAPIオブジェクトは、'window.customUiLib`として参照できます。

このオブジェクトに特定のプロパティ名で関数を登録することで、Synapse本体の画面とデータの受け渡しが可能になります。

async function onLoad(editable, param, isNewComponent, componentId, locale) {
  :
}
async function onSave() {
  :
}

// コールバック関数の登録
window.customUiLib.onSave = onSave;
window.customUiLib.onLoad = onLoad;
 :

その他にもSynapseの情報を取得できるAPIがあります。

これらAPIの詳細については、カスタムUI JS-APIリファレンスを参照してください。

5.1.4.3.4 パラメータダイアログが表示されたときに実行される関数#

カスタムコンポーネントのパラメータ設定ダイアログが表示される際には、カスタムUIのJavaScriptで登録したonLoad()関数がコールされます。この関数の引数として、以下の情報が渡されますので、必要に応じてhtml内の要素に反映してください。

ダイアログの編集可否

Run Modeにおいてはダイアログの入力項目を編集不可にするため、引数editableにfalseが渡されます。詳細は編集制限の制御を参照してください。
設定済みパラメータ

すでに作成済みのコンポーネントパラメータを編集する際、以前設定されたパラメータが引数paramに渡されます。
新規作成か更新か

コンポーネントの新規作成時にはtrue、更新時はfalseが引数isNewComponentに渡されます。
コンポーネントID

コンポーネントのIDが引数componentIdに渡されます。この情報はコンポーネントの新規作成時にはundefinedとなります。
言語設定

現在使用している言語設定のコードjaやenなどが引数localeに渡されます。

5.1.4.3.5 パラメータダイアログの保存時に実行される関数#

カスタムコンポーネントのパラメータ設定ダイアログで保存ボタンがクリックされた際には、カスタムUIのJavaScriptで登録したonSave()関数がコールされます。この関数から保存すべきパラメータを返すようにしてください。

5.1.4.3.6 編集制限の制御#

SynapseにはRun Mode、Edit Modeの二つの画面があり、Run Modeではデータ収集フローの運用を、Edit Modeではデータ収集フローの設定などが行えます。

通常のコンポーネントやJSONファイルで定義したカスタムUIはRun Modeでは編集できないように制限がかけられていますが、HTMLで実装したカスタムUIではその制限ができません。その代わり、編集可能か否かの情報をonLoad()関数の引数editableから受け取れますので、それをもとにユーザーが編集できないように実装してください。

基本的にはHTML要素のdisableをtrueに設定して非活性とすれば問題ありません。

async function onLoad(editable, param, isNewComponent, componentId, locale) {
  // editableがfalseならフォームの'host'項目を非活性にする
  document.forms['form']['host'].disabled = !editable;
}
window.customUiLib.onLoad = onLoad;

参考：HTML属性: disabled

5.1.4.3.7 npmを利用したサンプル#

Synapseでは、VueやQuaserを利用して画面を作成しています。
素のHTMLやCSSでは違和感のある画面となってしまいますが、npmを利用することで、VueやQuaserといった外部パッケージを利用したUIを作成することができます。ここまでの説明で利用したサンプルでは素のHTML, Javascript, CSSだけを利用していましたが、Vue, Quaserを利用するようにしたサンプルも提供しています。

Vue、Quaserを利用したサンプル

サンプルをダウンロードしましたら、下記のコマンドを実行することでhtmlやjsファイルがdistディレクトリ配下に生成されます。これらのファイルを通常のhtmlと同様にSCCDE環境内に配置して使用可能です。

$ ls
sample_custom_ui_vue.zip
$ unzip sample_custom_ui_vue.zip
$ cd sample_custom_ui_vue
$ npm install
$ npm run build
$ ls dist
assets  index.html

npmの利用

npmを利用するにはNode.jsをインストールする必要があります。インストール方法を含めたNode.jsについての詳細はNode.js公式サイトを参照してください。
Node.js公式サイト：https://nodejs.org/ja

5.1.4.4 PythonカスタムコンポーネントへのカスタムUI(JSON)の適用#

「SynapseカスタムUI用JSONファイルの作成」で作成した定義ファイルを登録することで、PythonカスタムコンポーネントにカスタムUIを設定することができます。

5.1.4.4.1 登録#

次の手順で、カスタムUIを登録することができます。

設定メニューアイコンを押下し、「カスタムコンポーネント」を選択します。
ダイアログ上部のタブの「Python(.py)」を選択します。
任意のカスタムコンポーネントの「UIアイコン（UI設定）」を押下します。
「登録」を押下し、定義ファイルを登録します。
「登録済み」という文言と、定義ファイルの内容が表示されます。
定義ファイルを登録したカスタムコンポーネントの設定画面に、ファイルで定義した項目が表示されます。

パラメーター表示

「パラメーター表示」を押下します。
カスタムUIに入力した内容から生成される、コンポーネントの実行時パラメータを確認することができます。

5.1.4.4.2 削除#

次の手順で、登録した定義ファイルを削除し、画面をデフォルトの状態にもどすことができます。

設定メニューアイコンを押下し、「カスタムコンポーネント」を選択します。
ダイアログ上部のタブの「Python(.py)」を選択します。
定義ファイルを登録したカスタムコンポーネントの「UIアイコン（UI設定）」を押下します。
「削除」を押下します。
登録した定義ファイルが削除され、「未登録」と表示されます。
カスタムコンポーネントの設定画面が、デフォルトの状態に戻ります。

5.1.4.5 C言語カスタムコンポーネントへのカスタムUI(JSON)の適用#

「SynapseカスタムUI用JSONファイルの作成」で作成した定義ファイルを登録することで、 C言語カスタムコンポーネントにカスタムUIを設定することができます。

5.1.4.5.1 登録#

次の手順で、カスタムUIを登録することができます。

設定メニューアイコンを押下し、「カスタムコンポーネント」を選択します。
ダイアログ上部のタブの「C(.so)」を選択します。
任意のカスタムコンポーネントの「UIアイコン（UI設定）」を押下します。
「登録」を押下し、定義ファイルを登録します。
「登録済み」という文言と、定義ファイルの内容が表示されます。
定義ファイルを登録したカスタムコンポーネントの設定画面に、ファイルで定義した項目が表示されます。

パラメーター表示

「パラメーター表示」を押下します。
カスタムUIに入力した内容から生成される、コンポーネントの実行時パラメータを確認することができます。

5.1.4.5.2 削除#

次の手順で、登録した定義ファイルを削除し、画面をデフォルトの状態にもどすことができます。

設定メニューアイコンを押下し、「カスタムコンポーネント」を選択します。
ダイアログ上部のタブの「C(.so)」を選択します。
定義ファイルを登録したカスタムコンポーネントの「UIアイコン（UI設定）」を押下します。
「削除」を押下します。
登録した定義ファイルが削除され、「未登録」と表示されます。
カスタムコンポーネントの設定画面が、デフォルトの状態に戻ります。