タブプラグイン

タブプラグイン

以下ではデバイスに新規タブを追加するプラグインの開発概要を記載しています。

タブプラグインの開発を手がける前にアプリケーションとプラグインおよび"Hello world!"スタイルのデモプラグインの基礎コンセプトが解説されている introductionの一読をお勧めします。

これらの他、ドキュメント内で照会されているプラグインは全てcumulocity-ui-plugin-examplesレポジトリで参照できます。

デバイス連絡先プラグイン

このセクションではデバイスに「連絡先」というタブを追加するプラグインを作成する方法を紹介します。「連絡先」をクリックすると連絡先を記入できるフォームが出てきます。ユーザーが入力したフォームを保存するとデバイスのオブジェクトととしてインベントリ内に保存されます。新規のタブは以下の図のようになります。

連絡先タブ

これを作成するには以下の手順を踏む必要があります:

  • プラグインを作成
  • アプリケーションマニフェストのインポートリスト上にこのプラグインを定義。
  • デバイスにタブを追加
  • タブ上にデータを表示
  • データをThings Cloudバックエンドへ永続させる。

ここでは、プラグインを挿入したいアプリケーションをすでに手元に持っていることを想定しておりますが、もし持っていない場合はレポジトリで提供されているものを使用することができます。"plugins/deviceContact"フォルダ内にもここの例題で使用されているアプリが保存されています。

従属物の追加

今回、「デバイスマネジメント」のアプリケーションを拡張したいとしましょう。実際にはデバイスマネジメントにプラグインを追加し、自身のアプリケーションマニフェスト内のインポートに追加することを意味します。開発環境上で既存アプリケーションの使用中プラグインの一覧を表示したい場合は以下のコマンドを走らせてください:c8y util:showimports <appContextPath>

今回の場合:

$ c8y util:showimports devicemanagement

アプリケーションマニフェストのインポート定義へ表示されたプラグイン一覧を追加してください。

注記)もし自身のブランディングプラグインを定義している場合はc8yBranding プラグインを削除する必要があります。

もし、最小主義のアプローチでいく場合はcumulocity-ui-plugin-examples 内の"cumulocity.json"ファイルを読取り、デバイス連絡先プラグインに必要なプラグインのみをインポートしてください。

ヒント c8y util:showimports cockpit または c8y util:showimports administration を走らせ、利用可能なプラグインを表示させてください。"node_modules/cumulocity-ui-build"内にある_apps.jsonに既存アプリケーション用のマニフェストが保存してあります。

プラグインの作成

自身のアプリケーションフォルダ内で以下のコマンドを走らせてください:

$ c8y create:plugin deviceContact

"plugins/deviceControl" 内にあるプラグインマニフェスト を編集し、以下の情報を追加してください:

{
    "name": "Device Details - Contact",
    "description": "Plugin adds a Contact tab to Device Details view"
}

プラグインのルートフォルダ内に"deviceContact.module.js"というファイルを作成し、以下の内容を入力してください:

(function () {
    'use strict';

    angular.module('myapp.deviceContact', []);
}());

インポート一覧に以下の新規プラグインを追加するために、アプリケーションマニフェストを更新してください:

{
    ...
    "imports": [
        ...
        "myapplication/deviceContact"
    ]
}

デバイスにタブを追加

ここではデバイスの詳細一覧上に空の「連絡先」タブを作成します。以下の手順でタブ内の中身を入れていきます。プラグインフォルダ内に"deviceContact.config.js"というファイルを下記のような内容で作成してください。 "Hello world!"の例題のように独自アプリケーションに新規のビューを追加するために Cumulocity JavaScript APIで提供されている"c8yViewsProvider"サービスを使用します。

(function() {
  'use strict';

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

  configure.$inject = [
    'c8yViewsProvider'
  ];

  function configure(
        c8yViewsProvider
    ) {
    c8yViewsProvider.when('/device/:deviceId', { // when the path "/device/:deviceId" is accessed ...
      name: 'Contact', // ... show a tab with the name *"Contact"*
      icon: 'envelope-o', // ... use the envelope-o icon (icons are provided by the great Font Awesome library and you can use any of their [icon names](http://fontawesome.io/icons/) without the *fa-* prefix here
      priority: 1000, // ... set the priority to 1000, which means that all tabs with a priority lower than 1000 appear before this tab and all with a priority higher than 1000 appear after this tab
      templateUrl: ':::PLUGIN_PATH:::/views/deviceContact.html', //  ... display our html file "deviceContact.html" inside the "views" folder of our plugin (the plugin's folder is represented using the magic string ```:::PLUGIN_PATH:::```, which is replaced by the actual path during the build process)
      controller: 'deviceContactCtrl' // ... use "deviceContactCtrl" as controller
    });
  }

}());

注記)ルート (この場合"/device/:deviceId")に複数のビューを添付する場合、タブは自動的に作成されます。デバイス詳細一覧ではすでに/device/:deviceId を使用するので「連絡先」はタブとして追加表示されます。

次に、コントローラーとビューを定義する必要があります。コントローラーについては、"deviceContact.controller.js"という新規ファイルをプラグインフォルダ内に作成し、以下の内容を追記してください:

(function () {
'use strict';

    angular
    .module('myapp.deviceContact')
    .controller('deviceContactCtrl', DeviceContactController);

    function DeviceContactController() {

    }
}());

プラグインフォルダ内に"views"という新規フォルダを作成し、以下を追記した"deviceContact.html"というファイルを追加作成してください:

    <div class="panel panel-clean">
        <div class="panel-body">
            Contact
        </div>
    </div>

モジュール、設定、コントローラをプラグインに追加した今、"myapp.deviceContact"を自身のモジュールとして特定する必要があり、それぞれのjavaスクリプトファイルをプラグインマニフェストへ追加する必要があります:

{
  "name": "Device Details - Contact",
  "description": "Plugin adds a Contact tab to Device Details view",
  "category": "Examples",
  "ngModules": [
    "myapp.deviceContact"
  ],
  "js": [
    "deviceContact.module.js",
    "deviceContact.config.js",
    "deviceContact.controller.js"
  ]
}

この時点で展開をすることにより、アプリケーションの検証 が可能です。デバイスを選択する際、「連絡先」タブが表示されるはずです。

連絡先タブ上にデータを表示

先ほどの段階では、「連絡先」タブにはダミーのビューが設定されています。ここでは実際の連絡先情報をデバイスのビューに表示します。まずは連絡先データーがデバイスのインベントリにある"c8y_Contact"というフラグメントに保存されていることを以下のように定義します:

    {
        "c8y_Contact": {
            "name": "John Smith",
            "email": "john.smith@example.com",
            "phone": "123-456-789",
            "address": "Sample Street 11 A"
        }
    }

"deviceContact.controller.js"にロード機能を追加し、 以下のように必要な従属物を挿入してください。この機能は表示されたデバイス($routeParams.deviceId)の詳細を取得し、ローカルスコープにデバイスIDと"c8y_Contact"フラグメントを追加します。

(function() {
  'use strict';

  angular
    .module('myapp.deviceContact')
    .controller('deviceContactCtrl', DeviceContactController);

  DeviceContactController.$inject = [
    '$scope',
    '$routeParams',
    'c8yDevices'
  ];

  function DeviceContactController($scope, $routeParams, c8yDevices) {

    function load() {
      c8yDevices.detail($routeParams.deviceId).then(function (res) {
        var device = res.data;
        $scope.device.id = device.id;
        $scope.device.c8y_Contact = device.c8y_Contact;
      });
    }

    $scope.device = {};

    load();
  }

}());

deviceContact.htmlにあるデバイス連絡先のビューを下記のように編集してください:

    <div class="panel panel-clean">
        <div class="panel-body">
            <form name="contactForm">
                <div class="form-group">
                    <label for="contact_name">Name</label>
                    <input id="contact_name" type="text" class="form-control" ng-model="device.c8y_Contact.name">
                </div>
                <div class="form-group">
                    <label for="contact_email">E-mail address</label>
                    <input id="contact_email" type="text" class="form-control" ng-model="device.c8y_Contact.email">
                </div>
                <div class="form-group">
                    <label for="contact_phone">Phone</label>
                    <input id="contact_phone" type="text" class="form-control" ng-model="device.c8y_Contact.phone">
                </div>
                <div class="form-group">
                    <label for="contact_address">Address</label>
                    <input id="contact_address" type="text" class="form-control" ng-model="device.c8y_Contact.address">
                </div>
            </form>
        </div>
    </div>

ユーザーにデータ保存の許可を与える

以下の手順を踏めば、新規連絡先フォームに入力されたデータを保存することが可能になります。

データを保存できるよう、"deviceContact.controller.js"内のコントローラーに追加の従属物と以下の内容をロード関数の閉じ括弧の後に追加し、更新してください。 "c8yDevices.save" とは Things Cloud REST APIを使用しデバイスを保存するライブラリ機能 です。"c8yAlert.success" とはユーザーインターフェース上部に緑の確認ボックスを表示するライブラリ機能です。

(function() {
  'use strict';

  angular
    .module('myapp.deviceContact')
    .controller('deviceContactCtrl', DeviceContactController);

  DeviceContactController.$inject = [
    '$scope',
    '$routeParams',
    'c8yDevices',
    'c8yAlert'
  ];

  function DeviceContactController($scope, $routeParams, c8yDevices, c8yAlert) {

    function load() {
      c8yDevices.detail($routeParams.deviceId).then(function (res) {
        var device = res.data;
        $scope.device.id = device.id;
        $scope.device.c8y_Contact = device.c8y_Contact;
      });
    }

    function save(device) {
      c8yDevices.save(device).then(onSave);
    }

    function onSave() {
      c8yAlert.success('Contact information successfully saved!');
    }

    $scope.save = save;
    $scope.device = {};

    load();
  }

}());

「保存の変更」 ボタンをデバイス連絡先のビューに追加しましょう。deviceContact.htmlのformタグを閉じる前に以下のdivを貼り付けてください。このボタンは先ほど定義したsave機能を作動させます。

    <div>
        <a href="" class="btn btn-primary" ng-click="save(device)" ng-disabled="contactForm.$invalid">Save changes</a>
    </div>

これでプラグインの完成です!プラグインを展開し、ウェブブラウザ上で独自アプリケーションを開きデバイスをクリックして「連絡先」タブを確認しましょう。