Web SDK を利用したカスタムウィジェットの作り方1

投稿日/更新日/投稿者名

• 2020.7.31 / 2020.10.27 / 川戸美輝
• 2025.1.30 / 吉冨寿一郎
• 2025.9 / 陳
  
  

はじめに

本レポートは、Things Cloud の利用例をより知っていただくための実利用レポートとして作成したものです。Things Cloud は極力後方互換性を持つよう開発されていますが、今後のリリースにより、一部画面やコマンド、手順などが変更となったり、利用できない可能性があることをあらかじめご了承ください。 なお、作成にあたり、以下バージョンを用いています。ご利用のバージョンは こちら の手順で確認できます。

• ver 1021.22.99 (フロントエンド)

Web SDK を利用する上では、以下のWebサイトが参考になります。

• Web SDK のドキュメント

概要

Web SDK を利用して、デフォルトで提供されているウィジェット以外に、独自のウィジェットを開発する手法について、サンプルとして開発した「View Widget」を用いて説明します。

Web SDK を利用したアプリケーション開発における基本的な部分は、カスタムアプリケーションの作り方と重複した内容もございますので、こちらも合わせてお読みいただくことで、一層理解が深まると考えられます。

本レポートで紹介するカスタムウィジェットの作り方は2つのページから構成されており、それぞれの内容は下記の通りです。

• 本レポートの紹介内容
  • カスタムウィジェットの作り方1 ：静的な情報のみを表示するウィジェット「View Widget」の開発（本ページ）
  • カスタムウィジェットの作り方2 ：1で作成したウィジェットに「デバイスから取得したデータを表示」する機能を追加

• 本ページで学べること
  • Web SDK を使ったカスタムウィジェットの開発方法
  • ローカル開発環境での動作確認の仕方、Things Cloud へのデプロイ方法

所要時間（目安）

本レポートに記載されたコードをそのまま利用し、ウィジェット「View Widget」がテナントで利用可能になるまでの所要時間。

• 約30分
  
  

難易度 ★★

前提条件

• 次の言語/フレームワークを扱えること
  • HTML5
  • CSS
  • TypeScript
  • Angular v18.0.0以上推奨
• 開発環境に以下をインストールしていること
  • Node.js v20推奨
  • npm (Node.js と一緒にインストールされます)
  • @angular/cli パッケージ (ng コマンドの使用に必要です)

作成物

今回は、シンプルなウィジェット「View Widget」の作成を通して、カスタムウィジェット開発の基礎を学びます。

ウィジェット作成画面に「View Widget」が表示されます。

「View Widget」を選択し、メッセージを設定します。

このようにウィジェットとして表示されます。

なお、本レポート完了時にできあがる成果物は こちら からダウンロードできます。
※ node_modules/ は上記のファイル一式に含まれていないため、npm install コマンドでインストールする必要があります。インストール後は、5. ローカル環境での動作確認 以降を参考に、ローカル環境・実環境での動作確認を進めてください。

開発の流れ

1. ウィジェット開発の準備
2. 開発用ディレクトリの作成
3. コンポーネントファイルの作成
4. app.module.ts の編集
補足. ウィジェットに表示するテキストの見た目を変更する
5. ローカル環境での動作確認
6. Things Cloud へのデプロイ
7. 実環境での動作確認

1. ウィジェット開発の準備

ウィジェット開発で必要なツールを利用できるよう、以下のコマンドでAngular CLIをインストールします。

$ npm install -g @angular/cli@18

2.開発用ディレクトリの作成 で必要になるThings Cloudのフロントエンドのバージョンを確認します。

• 手順1. テナントにログインし、画面右上にあるユーザイコンをクリックします。
  
• 手順2. プラットフォームの詳細をダウンロードをクリックし、JSONファイルをダウンロードします。
  
• 手順3. ファイルを開き、CTRL+Fなどで "type": "CURRENT_APPLICATION"の記載された行を探します。
  
• 手順4. その行の上にある "version" に記載された値が、フロントエンドのバージョンです。下記の場合、1021.22.99 がフロントエンドのバージョンです。

{...(略)...
  "CURRENT_APPLICATION": [
    {
      "label": "cockpit",
      "version": "1021.22.99",
      "type": "CURRENT_APPLICATION",
      "custom": {
    ...(略)...}
    }
  ]
}

2. 開発用ディレクトリの作成

開発用のディレクトリを、以下のコマンドで作成します。

# アプリケーションディレクトリの作成
$ npx @angular/cli@18 new --style=less

# 任意のアプリケーション名を設定
? What name would you like to use for the new workspace and initial project? my-cockpit

# [n]と入力
? Do you want to enable Server-Side Rendering (SSR) and Static Site 
Generation (SSG/Prerendering)? no

作成したディレクトリに移動し、@c8y/websdk パッケージを追加します。 この時、バージョンを選択する必要がありますので、1. で確認したThings Cloudのフロントエンドのバージョンを選択または入力してください。

# 作成したディレクトリに移動
$ cd ./my-cockpit

# @c8y/websdkパッケージを追加
$ ng add @c8y/websdk

? The package @c8y/websdk@1022.27.0 will be installed and executed. 
Would you like to proceed? (Y/n) y

# cockpitを選択
? Which base project do you want to scaffold from? cockpit

# 1. の手順4. で確認したThings Cloudのフロントエンドのバージョンを設定
? Which base version do you want to scaffold from? (Use arrow keys) other
? Enter the desired version: 1021.22.99

$ npm install

上記の操作を実行すると、以下のような構成でディレクトリが作成されます。

<<root folder>>
	|
	└── my-cockpit
      ├── README.md
      ├── angular.json
      ├── cumulocity.config.ts
      ├── node_modules/
      |   └── (略)
      ├── package-lock.json
      ├── package.json
      ├── public/
      |   └── (略)
      ├── src/
      |   ├── (略)
      |   └── app/
      |       └── app.module.ts
      ├── tsconfig.app.json
      ├── tsconfig.json
      └── tsconfig.spec.json

3. コンポーネントファイルの作成

ウィジェットは大きく、以下の2つの要素から構成されます。

• ウィジェット (Widget)：ダッシュボードに追加された時に表示されるコンポーネント（view-widget.component.ts）
• 設定 (Configuration)：ダッシュボードにウィジェットを追加する際に表示される、ウィジェットの設定を入力できるコンポーネント（view-widget-config.component.ts）

したがって、2つのコンポーネントファイルを作成する必要があります。 それぞれのファイルは、src/app/ のディレクトリに作成します。

はじめに、view-widget.component.ts を作成し、以下のように編集します。

import { Component, Input } from '@angular/core';

@Component({
	selector: 'c8y-custom-widget',
	template: `<p class="text">{{config?.text || 'No text'}}</p>`
})

export class WidgetDemo {
	@Input() config;
}

このコンポーネントは、「config に設定された文字列を表示する」という機能のみを持っています。

続いて、view-widget-config.component.ts を作成し、以下のように編集します。

import { Component, Input } from '@angular/core';

@Component({
	selector: "custom-widget-config",
	template: `<div class="form-group">
		<c8y-form-group>
			<label translate>Text</label>
			<textarea style="width:100%" [(ngModel)]="config.text"></textarea>
		</c8y-form-group>
	</div>`
})

export class WidgetConfigDemo {
	@Input() config: any = {};
}

このコンポーネントで、実際にテキスト入力を受けつけます。 config オブジェクトを追加することで、ウィジェット作成時に設定したメッセージが、config を介して作成したウィジェットへ反映されるようになります。

4. app.module.ts の編集

カスタムコックピットにウィジェットを追加するために、src/app/app.module.ts に以下の三点の変更を加えます。

1. hookComponent の import
2. Widgetコンポーネント の import
3. declaration と providers でコンポーネントを定義

app.module.tsの内容を、以下に示されているコードに変更してください。

import { NgModule } from '@angular/core';
import { BrowserAnimationsModule } from '@angular/platform-browser/animations';
import { UpgradeModule as NgUpgradeModule } from '@angular/upgrade/static';
import { CoreModule, RouterModule, hookComponent } from '@c8y/ngx-components';
import {
  DashboardUpgradeModule,
  UpgradeModule,
  HybridAppModule,
  UPGRADE_ROUTES
} from '@c8y/ngx-components/upgrade';
import { SubAssetsModule } from '@c8y/ngx-components/sub-assets';
import {
  CockpitDashboardModule,
  DashboardManagerModule
} from '@c8y/ngx-components/context-dashboard';
import { ReportsModule } from '@c8y/ngx-components/reports';
import { BinaryFileDownloadModule } from '@c8y/ngx-components/binary-file-download';
import { CockpitConfigModule } from '@c8y/ngx-components/cockpit-config';
import { PluginSetupStepperModule } from '@c8y/ngx-components/ecosystem/plugin-setup-stepper';
import { PendingMoRequestModule } from '@c8y/ngx-components/pending-mo-request';
import { WidgetDemo } from './view-widget.component';
import { WidgetConfigDemo } from './view-widget-config.component';

@NgModule({
  imports: [
    // Upgrade module must be the first
    UpgradeModule,
    BrowserAnimationsModule,
    RouterModule.forRoot([...UPGRADE_ROUTES]),
    CoreModule.forRoot(),
    ReportsModule,
    NgUpgradeModule,
    DashboardUpgradeModule,
    CockpitDashboardModule,
    DashboardManagerModule,
    BinaryFileDownloadModule,
    SubAssetsModule.config(),
    CockpitConfigModule,
    PluginSetupStepperModule,
    PendingMoRequestModule
  ],
  declarations: [WidgetDemo, WidgetConfigDemo],	
  providers: [
    hookComponent({
      id: 'hoge.view.widget', //一意なIDを設定
      label: 'View Widget',
      description: 'Can display a demo',
      component: WidgetDemo, //コンポーネントを関連付け
      configComponent: WidgetConfigDemo, //コンポーネントを関連付け
      //デバイス選択画面の非表示オプション（デバイスの情報が不要なため、任意で追加）
      data: {
        ng1: {
          options: {
            noDeviceTarget: true
          }
        }
      }
    })
  ]
})
export class AppModule extends HybridAppModule {
  constructor(protected override upgrade: NgUpgradeModule) {
    super();
  }
}

補足: ウィジェットに表示するテキストの見た目を変更する

ここまでの作業で、既にカスタムウィジェットの動作に必要な部分は完成しています。 本項では、補足として、ウィジェットに表示するテキストの見た目を変更する手法を紹介します。

ウィジェットに表示するテキストの見た目は、CSSを介して簡単に変更することができます。 以下のように、view-widget.component.ts内のstylesで設定します。 今回は最もシンプルな例として、文字サイズの変更と文字色の変更を行います。

@Component({
	selector: 'c8y-custom-widget',
	template: `<p class="text" >{{config?.text || 'No text'}}</p>`,
	styles: [ `p{ font-size: 30px; color: red }` ]
})

5. ローカル環境での動作確認

アプリケーションのルートディレクトリ (my-cockpit/ 直下) で以下のコマンドを実行することで、ローカルホストでの動作確認ができます。以下では、ローカルホストへのリクエストを -u オプションで指定した URL へプロキシしています。

$ npm start -- -u https://<テナント名>.je1.thingscloud.ntt.com

もしくは、package.json を修正することで、 npm start コマンドのみで同様の動作確認が可能です。

package.json 内の、"scripts" の "start" 項目の ng server 以降に -u https://<テナント名>.je1.thingscloud.ntt.com を追加することで、リクエストを指定 URL へプロキシできるようになります。

{...(略)...
  "scripts": {
    "ng": "ng",
    // ng server 以降を追加する
    "start": "ng serve -u https://<テナント名>.je1.thingscloud.ntt.com",
    "build": "ng build",
    "watch": "ng build --watch --configuration development",
    "test": "ng test"
  },
...(略)...
}

実行には、以下の npm start コマンドを使用します。

$ npm start

上記のいずれかを実行した後、出力されたURL ( http://localhost:4200/apps/my-cockpit ) をwebブラウザに入力し、アクセスします。アクセス後、以下の画面でテナントID・ユーザ名・パスワードを入力し、テナントへログインします。ログイン後、アプリケーションの動作確認ができるようになります。

ここで、テナントIDとはt<number>の形で定義される固有の識別子を指します。テナントIDの確認方法は、基本的には以下の3種類です。

• テナントへログインし、右上のユーザアイコンをクリックして、プラットフォーム情報から確認する
• APIを使用してテナント情報を取得する（参考ページ）
• 親テナントの管理アプリケーションにログインし、サブテナントメニューから確認する

ログインに成功したら、画面左のメニューから任意のグループを選択し、ダッシュボードを追加します。 追加されたダッシュボードにウィジェットを追加し、View Widgetを選択します。 表示したいメッセージを入力して保存することで、ダッシュボード上に作成したウィジェットが表示されます。（参考：【完成イメージ】）

CSSを記述しない場合、ウィジェットには以下のようにプレーンなテキストが表示されます。

6. Things Cloud へのデプロイ

ローカル開発環境での動作が正常であることを確認したら、Things Cloud へデプロイします。アプリケーションのルートディレクトリ (my-cockpit/ 直下) に移動し、以下のコマンドを実行します。これにより、 Things Cloud 上でカスタムウィジェットが使用できるようになります。

$ ng deploy -u https://<テナント名>.je1.thingscloud.ntt.com -T <テナントID> -U <アカウント名> -P "<パスワード>"

7. 実環境での動作確認

デプロイしたアプリケーションにアクセスし、ブランドロゴ等が正常に表示されていることを確認します。

カスタムウィジェットは、既存のコックピットでは使用できず、自身で作成したアプリケーション名（my-cockpitなど）のアプリケーションでのみ利用できます。

以下の場合、画面右上のユーザアイコンの左に位置するアプリケーション選択画面を開き、My-cockpit アプリケーションを選択すると、カスタムウィジェットが利用できます。

さいごに

本レポートでは、Things Cloud の既存コックピットとは異なるコックピット (my-cockpit) を作成し、my-cockpit上にカスタムウィジェットをデプロイしました。そのため、既存のコックピットからは今回作成したカスタムウィジェットの動作は確認できません。

実際に既存のコックピットで動作するカスタムウィジェットを開発する場合は、既存のコックピットに対してデプロイを行ってください。 ただし、既存のコックピットに対してデプロイを行う場合、別途開発者が設定しない限り、Branding UI のバージョンも同時に変更されますのでご注意ください。

Things Cloud の Web SDK を利用する上では、以下のWebサイトが参考になります。

• Web SDK のドキュメント