Colour gradient for number card (#209)

* Color gradient for number card

* Move dashboard migrations into separate module

* Apply suggestions from code review

Co-Authored-By: Philipp Rudloff <[email protected]>

* Fix asymmetrical GET/POST dashboard API and move the dashboard migration to the server

* Fix simulation and example dashboard file

Co-authored-by: Philipp Rudloff <[email protected]>

Author: tkoster

.data/dashboard.blank.json

@@ -3,8 +3,9 @@
     "blockSize": [250, 200],
     "bgColor": "papayawhip",
     "tiles": [],
-    "title": "\u26a1electric io",
+    "title": "⚡electric io",
     "bgImageUrl": "",
     "bgImageRepeat": "true"
-  }
+  },
+  "version": 1
 }

.data/dashboard.example.json

@@ -24,7 +24,7 @@
       },
       {
         "title": "Study Temperature",
-        "type": "lineChart",
+        "type": "line-chart",
         "lineColor": "#FF6384",
         "deviceId": "AZ3166",
         "property": "temperature",
@@ -34,7 +34,7 @@
       },
       {
         "title": "Jenn's Coolness Factor 😎",
-        "type": "lineChart",
+        "type": "line-chart",
         "lineColor": "#6b66ff",
         "deviceId": "Jenn",
         "property": "coolness",
@@ -50,11 +50,16 @@
         "property": "humidity",
         "position": [296, 465],
         "size": [1, 1],
-        "id": "101ca6cb-ba75-4e5c-9db6-d29ba7ab9f51"
+        "id": "101ca6cb-ba75-4e5c-9db6-d29ba7ab9f51",
+        "textColorMode": "single",
+        "lowValue": 20,
+        "lowTextColor": "#1282baff",
+        "highValue": 40,
+        "highTextColor": "#cb1475ff"
       },
       {
         "title": "Noise 🙉",
-        "type": "lineChart",
+        "type": "line-chart",
         "lineColor": "#60dd4d",
         "deviceId": "Tessel2",
         "property": "sound",
@@ -70,6 +75,8 @@
         "size": [1, 1],
         "id": "88e12934-c628-48cb-8b84-b16c2e311105"
       }
-    ]
-  }
+    ],
+    "title": "⚡electric io"
+  },
+  "version": 1
 }

CONTRIBUTING.md

@@ -12,6 +12,7 @@ This page should get you up and running with how to run locally and how to adher
    - [Mobile support](#mobile-support)
 3. [Pull requests](#pull-requests)
    - [Avoiding merge conflicts](#merge-conflicts)
+4. [Dashboard settings migrations](#dashboard-settings-migrations)
 
 ## Installation
 
@@ -191,3 +192,19 @@ This will:
 You can then `git push` to update the PR if you’ve already submitted one.
 
 ✨✨✨ Happy Contributing!! ✨✨✨
+
+## Dashboard settings migrations
+
+If you change the structure of the dashboard settings in a way that would prevent an existing dashboard from loading correctly, you should add a migration.
+
+Dashboard migrations are functions in the `dashboardMigrations` array in `lib/services/dashboard-migrations.service.js`. Each function in this array corresponds to a new dashboard version.
+
+The value of the dashboard `version` property is an integer corresponding to the number of migrations in the array of all dashboard migrations. An upgrade is required if the dashboard version is lower than the number of migrations in this array. When the server starts, it checks the `version` property and upgrades the dashboard if necessary. (A dashboard with no version property is at version `0`.)
+
+For example, say the dashboard is at version `2` and there are four functions in the migrations array. This means the dashboard is two versions behind. The upgrade runs the two last functions in the migrations array and sets the dashboard version to `4`.
+
+### Adding a dashboard migration
+
+To add a dashboard migration, write a function that performs the migration and **append** it to the array of migrations in `dashboard-migrations.service.js`. This function should have one parameter, the dashboard settings object, and modify it so that the dashboard will load correctly in the current version. Always use sensible defaults to avoid showing users broken or surprising behaviour.
+
+Do not forget to update the blank and default dashboard settings files in the `.data` directory if necessary.

lib/routes.js

@@ -11,7 +11,7 @@ function injectRoutes({ iotHubService }) {
     try {
       const dashboardSettings = await DashboardService.getDashboardSettings();
 
-      response.status(200).json(dashboardSettings);
+      response.status(200).json(dashboardSettings.dashboard);
     } catch (error) {
       response.status(500).send({
         data: {
@@ -25,7 +25,9 @@ function injectRoutes({ iotHubService }) {
     debug("LOG: Saving dashboard settings.");
 
     try {
-      await DashboardService.saveDashboardSettings(request.body);
+      const dashboardSettings = await DashboardService.getDashboardSettings();
+      dashboardSettings.dashboard = request.body;
+      await DashboardService.saveDashboardSettings(dashboardSettings);
 
       response.status(200).send();
     } catch (error) {

lib/routes.test.js

@@ -33,7 +33,7 @@ const mockDashboardSettings = {
     ],
     editMode: "unlocked"
   },
-  deviceList: ["AZ3166", "Tessel2", "Jenn"]
+  version: 1
 };
 
 const mockDeviceIds = ["AZ3166", "Tessel2", "Jenn"];
@@ -52,7 +52,7 @@ describe("API endpoints", () => {
       const response = await request(app).get("/api/dashboard");
 
       expect(response.status).toBe(200);
-      expect(response.body).toEqual(mockDashboardSettings);
+      expect(response.body).toEqual(mockDashboardSettings.dashboard);
     });
 
     test("can’t get dashboard settings if the service produces an error", async () => {
@@ -78,7 +78,7 @@ describe("API endpoints", () => {
 
       const response = await request(app)
         .post("/api/dashboard")
-        .send(mockDashboardSettings);
+        .send(mockDashboardSettings.dashboard);
 
       expect(response.status).toBe(200);
     });
@@ -92,7 +92,7 @@ describe("API endpoints", () => {
 
       const response = await request(app)
         .post("/api/dashboard")
-        .send(mockDashboardSettings);
+        .send(mockDashboardSettings.dashboard);
 
       expect(response.status).toBe(500);
       expect(response.body.data.message).toContain("Could not write to");

lib/services/dashboard-migrations.service.js

@@ -0,0 +1,33 @@
+module.exports = {
+  upgradeDashboard
+};
+
+function upgradeDashboard(settings, migrations = dashboardMigrations) {
+  const storedVersion = settings.version || 0;
+  const currentVersion = migrations.length;
+
+  for (let i = storedVersion; i < currentVersion; ++i) {
+    migrations[i](settings.dashboard);
+  }
+
+  settings.version = currentVersion;
+  return storedVersion < currentVersion;
+}
+
+const dashboardMigrations = [migrateDashboardVersion0To1];
+
+/**
+ * Migrate from dashboard version 0 to version 1:
+ * - Number tile: added text color gradient properties
+ */
+function migrateDashboardVersion0To1(dashboard) {
+  for (const tile of dashboard.tiles) {
+    if (tile.type === "number") {
+      tile.textColorMode = "single";
+      tile.lowValue = 20.0;
+      tile.lowTextColor = "#1282baff";
+      tile.highValue = 40.0;
+      tile.highTextColor = "#cb1475ff";
+    }
+  }
+}

lib/services/dashboard-migrations.service.test.js

@@ -0,0 +1,41 @@
+const { upgradeDashboard } = require("./dashboard-migrations.service");
+
+describe("upgradeDashboard", () => {
+  it("does not invoke migrations on an up-to-date dashboard", () => {
+    const migration = jest.fn();
+    const migrations = [migration, migration, migration];
+    const dashboard = { version: 3 };
+
+    upgradeDashboard(dashboard, migrations);
+
+    expect(migration).not.toHaveBeenCalled();
+  });
+
+  it("invokes migrations in order", () => {
+    const migrationsPerformed = [];
+    const migration1 = jest.fn(() => migrationsPerformed.push(1));
+    const migration2 = jest.fn(() => migrationsPerformed.push(2));
+    const migration3 = jest.fn(() => migrationsPerformed.push(3));
+    const migrations = [migration1, migration2, migration3];
+    const dashboard = {};
+
+    upgradeDashboard(dashboard, migrations);
+
+    expect(migrationsPerformed).toEqual([1, 2, 3]);
+    expect(dashboard.version).toEqual(3);
+  });
+
+  it("skips migrations already performed", () => {
+    const migrationsPerformed = [];
+    const migration1 = jest.fn(() => migrationsPerformed.push(1));
+    const migration2 = jest.fn(() => migrationsPerformed.push(2));
+    const migration3 = jest.fn(() => migrationsPerformed.push(3));
+    const migrations = [migration1, migration2, migration3];
+    const dashboard = { version: 2 };
+
+    upgradeDashboard(dashboard, migrations);
+
+    expect(migrationsPerformed).toEqual([3]);
+    expect(dashboard.version).toEqual(3);
+  });
+});

lib/services/dashboard.service.js

@@ -43,9 +43,7 @@ module.exports = {
         debug(message);
         reject(message);
       } else {
-        const fileContents = `{ "dashboard": ${JSON.stringify(
-          dashboardSettings
-        )} }`;
+        const fileContents = JSON.stringify(dashboardSettings);
 
         fs.writeFile(DASHBOARD_FILE_PATH, fileContents, "utf8", error => {
           if (error) {

lib/services/dashboard.service.test.js

@@ -31,7 +31,7 @@ const mockDashboardSettings = {
     ],
     editMode: "unlocked"
   },
-  deviceList: ["AZ3166", "Tessel2", "Jenn"]
+  version: 1
 };
 
 describe("DashboardService", () => {

lib/simulator/simulatedDevice.js

@@ -11,11 +11,11 @@ simulatedDevice.prototype.start = function() {
       const [min, max] = prop.minmax;
       body[prop.name] = Math.random() * (max - min) + min;
     });
-    const annotations = {
+    const systemProperties = {
       "iothub-connection-device-id": this.id,
       "iothub-enqueuedtime": new Date()
     };
-    const message = { annotations, body };
+    const message = { systemProperties, body };
 
     this.receiver.emitMessage(message);
   }, this.telemetry.interval);