カスタムウィジェットの作り方 1

投稿日 / 投稿者名

2018.8.1 / 正木 菜津美

はじめに

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

  • ver.8.15.8(backend/UI)

難易度 ★★★


概要

本レポートでは、デフォルトで提供しているウィジェット以外に、自分でウィジェットのプラグインを開発する方法について、サンプルで開発した「Hello Widget」を用いてご紹介します。
ウィジェットプラグインは、Things Cloud内のデータとのリアルタイムなやり取りを可能にします。

ウィジェット開発に関する紹介は、1〜3のページで構成され、各ページの手順を実行することで次の内容が実現できます。

  1. カスタムウィジェットの作り方 1:ウィジェット編集画面で設定したメッセージ文が表示される「Hello Widget」の開発(★このページ)
  2. カスタムウィジェットの作り方 2:1で作成したウィジェットに「デバイスから取得したデータを表示」する機能を追加
  3. カスタムウィジェットの作り方 3:2で作成したウィジェットに「画像データを表示」する機能を追加(近日公開)

また、全て通して読むことで、設定UIのデータの流れについても理解することができます。

前提条件

所要時間(目安)

この手順に沿って、「Hello Widget」を開発する場合の所要時間。

  • 約40分 (本レポートに記載されたコードをそのまま利用する場合)

つくるもの

今回は、設定したメッセージ文が表示される「Hello Widget」というシンプルなウィジェットの作成を通して、カスタムウィジェット開発におけるデータの流れの基礎を学びます。

【完成イメージ】

image


ウィジェット作成画面のプルダウンに「Hello Widget」が表示されるようになります。

image


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

image


設定したメッセージ文は、このようにウィジェットに表示されます。

なお、本ドキュメント( カスタムウィジェットの作り方 1 )で使用している、hellowidgetプロジェクト以下のファイル一式は こちら からダウンロードできます。



1. ファイル配置

/plugins 配下に以下のフォルダ構成でhellowidgetプロジェクトを作成します。

<<root folder>>
 |
 └── plugins
        └── hellowidget
             ├── cumulocity.json
             ├── hellowidget.config.js
             ├── hellowidget.controller.js
             ├── hellowidget.module.js
             ├── hellowidget.setting.controller.js
             └── views
                   ├── hellowidget.main.html
                   └── hellowidget.setting.html
  • cumulocity.json
    • 構成設定するプラグインマニフェスト
  • hellowidget.config.js
    • プラグイン構成起点となる設定ファイル
  • hellowidget.controller.js
    • ウィジェット表示画面コントローラファイル
  • hellowidget.module.js
    • モジュールファイル
  • hellowidget.setting.controller.js
    • ウィジェット設定画面のコントローラファイル
  • views/hellowidget.main.html
    • ウィジェット表示画面HTMLファイル
  • views/hellowidget.setting.html
    • ウィジェット設定画面のHTMLファイル



【参考】本レポートの「Hello Widget」を開発する場合に必要となるファイル一覧

<<root folder>>
├── cumulocity.json
├── plugins
|      └── hellowidget
|           ├── cumulocity.json
|           ├── hellowidget.config.js
|           ├── hellowidget.controller.js
|           ├── hellowidget.module.js
|           ├── hellowidget.setting.controller.js
|           └── views
|                 ├── hellowidget.main.html
|                 └── hellowidget.setting.html
├── targets
|      └── myapplication.json
└── node_modules
       └── cumulocity-ui-build
              ├── ・・・
              :



2. プラグインマニフェストの設定

プラグインマニフェストは以下のように作成します。

cumulocity.json

{
  "name": "HelloWidget",
  "description": "Hellowidget plugin",
  "category": "Widgets",
  "ngModules": [
    "myapp.hellowidget"
  ],
  "js": [
    "hellowidget.module.js",
    "hellowidget.config.js",
    "hellowidget.controller.js",
    "hellowidget.setting.controller.js"
  ],
  "imports": [],
  "css": [],
  "copy": [
    "views/hellowidget.main.html",
    "views/hellowidget.setting.html"
  ]
}


3. 設定ファイル&モジュールファイルの設定

設定ファイル・モジュールファイルを以下のように作成します。

hellowidget.config.js

(function () {
  'use strict';

  angular
    .module('myapp.hellowidget')
    .config(configure);

  /* @ngInject */
  function configure(
    c8yComponentsProvider,
    gettext
  ) {
    c8yComponentsProvider.add({
      name: 'hellowidget',
      nameDisplay: gettext('HelloWidget'),
      description: gettext('HelloWidget'),
      templateUrl: ':::PLUGIN_PATH:::/views/hellowidget.main.html',
      configTemplateUrl: ':::PLUGIN_PATH:::/views/hellowidget.setting.html',
      options: { noDeviceTarget: true }
    });
  }
}());

ウィジェット表示に使用するHTMLファイルは templateUrl で指定し、ウィジェット設定画面で使用するHTMLファイルはconfigTemplateUrl で指定します。また、今回はデバイスデータの紐付けを行わないので options には、 noDeviceTarget:true を設定します。


hellowidget.module.js

(function () {
    'use strict';
    angular.module('myapp.hellowidget', []);
}());



4. ウィジェット設定画面のコントローラ&表示するHTMLの設定

ウィジェット設定画面のコントローラと、表示するHTMLファイルはそれぞれ以下のように作成します。

hellowidget.setting.controller.js

(function () {
  'use strict';

  angular
    .module('myapp.hellowidget')
    .controller('hellowidgetSettingController', hellowidgetSettingController);

  /* @ngInject */
  function hellowidgetSettingController(
    $scope,
    $q,
    c8yInventory,
    c8yBinary
  ) {

  }
}());

設定画面のコントローラでは基本的な設定しかしていません。


views/hellowidget.setting.html

<div ng-controller="hellowidgetSettingController">
    <form name="hello">
        <label>Setting Message</label>
        <input id="helloMessage" name="helloMessage" type="text" ng-model="config.helloMessage" />
    </form>
</div>

データの反映はHTML上で記述するAngularフレームワークによりデータバインディングに任されています。 設定画面で設定される値はconfig配下にデータバインディングされており、 config.helloMessage で指定します。
データ変更時にThings Cloudに自動的に保存され設定保持が実現します。

5. ウィジェット表示画面のコントローラ&表示するHTMLの設定

ウィジェット表示画面のコントローラは以下のように作成します。

hellowidget.controller.js

(function () {
  'use strict';

  angular
    .module('myapp.hellowidget')
    .controller('hellowidgetController', hellowidgetController);

  /* @ngInject */
  function hellowidgetController(
    $scope,
    $q,
    c8yInventory,
    c8yBinary
  ) {

      var self = this;

      function init() {
          console.log("init");
      }

      // 値変更の監視
      $scope.$watch('child.config.helloMessage', function (newVal, oldVal) {
          if(newVal && !_.isEqual(newVal, oldVal)) {
              console.log("DataChange");
              init();
          }
      }, true);

  }
}());

ウィジェット表示HTMLについては、以下のように記述します。

views/hellowidget.main.html

<div ng-controller="hellowidgetController">
    <h2>{{child.config.helloMessage}}</h2>
</div>

設定画面で設定される値をウィジェット表示から設定する場合、child.config 配下にデータバインディングされているので child.config.helloMessage と指定します。

TIPS:値変更時にキャッチする場合

値変更時にキャッチできるよう、hellowidget.controller.jsで以下のように監視設定をしています。

       :
       :
      // 値変更の監視
      $scope.$watch('child.config.helloMessage', function (newVal, oldVal) {
          if(newVal && !_.isEqual(newVal, oldVal)) {
              console.log("DataChange");
              init();
          }
      }, true);
       :
       :

値設定を変更した際に、ブラウザのコンソール画面で以下のように通知されます。

image



6. ターゲットファイルにウィジェットプラグインの情報を追加する

targets/myapplication.json

{
    "applications": [{
        "contextPath": "cockpit",
        "addImports": [  "[contextPath]/hellowidget" ]
    }]
}

ターゲットファイル(targets/myapplication.json)の applications(cockpit)addImports[contextPath]/hellowidget 追加します。
ターゲットファイルはpluginsディレクトリと同列の階層にある、targetsディレクトリの配下にあります。

7. アプリケーションマニフェストにウィジェットプラグインの情報を追加する

アプリケーションマニフェストのインポート内にもウィジェットプラグインの情報を追加します。

{
    "imports": [ "[contextPath]/hellowidget" ]
}


8. ビルドする

本レポートでは、作成したウィジェットが含まれたcockpitアプリを作成し、アップロードする方法を紹介します。
c8yコマンド(c8y build:target myapplication)を実行し、cockpit.zipを作成します。
作成したzipファイルは、ファイル名を任意の値に編集後(デフォルトのコックピットアプリと重複しないよう、必ずファイル名を変えてください)、対象テナントの Administrationアプリ > 所有アプリケーション > アプリケーションを追加 からアップロードします。
この時、

カスタムウィジェットの作り方 1 についての紹介は以上です。