@c8y/tutorial 1019.8.1 → 1019.12.0

package/cumulocity.config.ts

@@ -100,6 +100,18 @@ export default {
         path: './src/dashboard/custom-dashboard/custom-dashboard.module.ts',
         description: 'An introduction to custom dashboards.'
       },
+      {
+        name: 'Dashboard module with example of dynamic component usage',
+        module: 'WidgetGuideDashboardModule',
+        path: './src/dashboard/widget-guide-dashboard/widget-guide-dashboard.module.ts',
+        description: 'An example showing usage of custom widget in dashboard.'
+      },
+      {
+        name: 'Context dashboard module with example of dynamic component usage',
+        module: 'WidgetGuideContextDashboardModule',
+        path: './src/dashboard/widget-guide-context-dashboard/widget-guide-context-dashboard.module.ts',
+        description: 'An example showing usage of custom widget in context dashboard.'
+      },
       {
         name: 'Introduction datapoint selection module',
         module: 'DatapointSelectionExampleModule',
@@ -640,6 +652,8 @@ export default {
         'NewTranslationModule',
         'NewLanguageModule',
         'CustomDashboardModule',
+        'WidgetGuideDashboardModule',
+        'WidgetGuideContextDashboardModule',
         'WidgetDashboardModule',
         'ContextDashboardModule',
         'ServiceDashboardModule',

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@c8y/tutorial",
-  "version": "1019.8.1",
+  "version": "1019.12.0",
   "description": "This package is used to scaffold a tutorial for Cumulocity IoT Web SDK which explains a lot of concepts.",
   "dependencies": {
-    "@c8y/devkit": "1019.8.1",
-    "@c8y/style": "1019.8.1",
-    "@c8y/ngx-components": "1019.8.1",
-    "@c8y/client": "1019.8.1",
-    "@c8y/bootstrap": "1019.8.1",
+    "@c8y/devkit": "1019.12.0",
+    "@c8y/style": "1019.12.0",
+    "@c8y/ngx-components": "1019.12.0",
+    "@c8y/client": "1019.12.0",
+    "@c8y/bootstrap": "1019.12.0",
     "@angular/cdk": "^16.2.11",
     "ngx-bootstrap": "11.0.2",
     "leaflet": "1.7.1",

package/src/dashboard/context-dashboard/context-dashboard.component.ts

@@ -4,7 +4,7 @@ import { ContextDashboardModule } from '@c8y/ngx-components/context-dashboard';
 import { CommonModule } from '@angular/common';
 
 @Component({
-  selector: 'app-context-dashboard',
+  selector: 'tut-context-dashboard',
   template: `<c8y-title>Context dashboard</c8y-title>
     <c8y-context-dashboard
       name="example-widget"

package/src/dashboard/custom-dashboard/custom-dashboard.component.html

@@ -1,31 +1,31 @@
 <c8y-title>Custom dashboard</c8y-title>
 
-<!--TODO: align action bar-->
 <c8y-action-bar-item [placement]="'right'">
   <button
     class="btn btn-link"
-    title="{{ 'Add random' | translate }}"
+    title="{{ 'Add random' }}"
     type="button"
     (click)="addRandom()"
   >
     <i c8yIcon="plus-circle"></i>
-    {{ 'Add random' | translate }}
+    {{ 'Add random' }}
   </button>
 </c8y-action-bar-item>
 <c8y-action-bar-item [placement]="'right'">
   <button
     class="btn btn-link"
-    title="{{ 'Toggle freeze' | translate }}"
+    title="{{ 'Toggle freeze' }}"
     (click)="isFrozen = !isFrozen"
   >
     <i [c8yIcon]="isFrozen ? 'lock' : 'unlock'"></i>
-    {{ 'Toggle freeze' | translate }}
+    {{ 'Toggle freeze' }}
   </button>
 </c8y-action-bar-item>
 
 <c8y-help src="/docs/cockpit/working-with-dashboards/#working-with-dashboards"></c8y-help>
 
 <c8y-dashboard (dashboardChange)="dashboardChange($event)">
+  <!--  Simple widgets represented by widgets array property from CustomDashboardComponent class-->
   <c8y-dashboard-child
     [class]="{
       'panel-title-hidden': true
@@ -39,6 +39,8 @@
     #current
   >
     <div class="card-block">
+      Simple widget with content only
+      <br />
       x: {{ current.x }}
       <br />
       y: {{ current.y }}
@@ -49,10 +51,12 @@
       <br />
     </div>
   </c8y-dashboard-child>
+
+  <!--  Dashboard child with title and widget classes applied-->
   <c8y-dashboard-child
     [class]="{
       'panel-content-branded': true,
-      'panel-title-overlay': true
+      'panel-title-border': true
     }"
     #cpWidget
     [isFrozen]="isFrozen"
@@ -62,9 +66,11 @@
     [height]="2"
   >
     <c8y-dashboard-child-title>
-      <span>World!</span>
+      <span>Widget title</span>
     </c8y-dashboard-child-title>
     <div class="card-block">
+      This widget has CSS classes 'panel-content-branded' and 'panel-title-border' applied.
+      <br />
       x: {{ cpWidget.x }}
       <br />
       y: {{ cpWidget.y }}
@@ -75,6 +81,8 @@
       <br />
     </div>
   </c8y-dashboard-child>
+
+  <!--  Dashboard child with title, widget class applied and children actions-->
   <c8y-dashboard-child
     [class]="{ 'panel-content-dark': true }"
     #cpWidget2
@@ -85,7 +93,7 @@
     [height]="4"
   >
     <c8y-dashboard-child-title>
-      <span>Hello!</span>
+      <span>Widget title</span>
     </c8y-dashboard-child-title>
     <c8y-dashboard-child-action>
       <a
@@ -97,6 +105,9 @@
       </a>
     </c8y-dashboard-child-action>
     <div class="card-block">
+      This widget has CSS classes 'panel-content-dark' applied. It also has toggle freeze action
+      button.
+      <br />
       x: {{ cpWidget2.x }}
       <br />
       y: {{ cpWidget2.y }}
@@ -108,6 +119,7 @@
     </div>
   </c8y-dashboard-child>
 
+  <!--  Dashboard child with title, widget class applied and children actions-->
   <c8y-dashboard-child
     [class]="{ 'panel-content-transparent': true }"
     #cpWidget3
@@ -118,7 +130,7 @@
     [height]="2"
   >
     <c8y-dashboard-child-title *ngIf="showTitle">
-      <span>Another!</span>
+      <span>Widget title</span>
     </c8y-dashboard-child-title>
     <c8y-dashboard-child-action>
       <a
@@ -139,6 +151,9 @@
       </a>
     </c8y-dashboard-child-action>
     <div class="card-block">
+      This widget has CSS classes 'panel-content-transparent' applied. It also has toggle freeze and
+      toggle title action buttons.
+      <br />
       x: {{ cpWidget3.x }}
       <br />
       y: {{ cpWidget3.y }}
@@ -150,31 +165,36 @@
     </div>
   </c8y-dashboard-child>
 
-  <!-- A dashboard child with a dynamic component -->
+  <!-- Dashboard child with a dynamic component -->
   <c8y-dashboard-child
     [isFrozen]="isFrozen"
     [width]="10"
     [height]="4"
   >
     <c8y-dashboard-child-title>
-      <span>Dynamic component demo</span>
+      <span>Dynamic component child title</span>
     </c8y-dashboard-child-title>
     <c8y-dashboard-child-action>
       <button
-        title="{{ 'Configure this widget' | translate }}"
+        title="{{ 'Configure this widget' }}"
         type="button"
         (click)="editComponent = !editComponent; (false)"
       >
         <i [c8yIcon]="'cog'"></i>
-        {{ 'Configure this widget' | translate }}
+        {{ !editComponent ? 'Configure this widget' : 'Close configuration' }}
       </button>
     </c8y-dashboard-child-action>
     <div class="card-block">
-      <c8y-dynamic-component
-        componentId="angular.widget.demo"
-        [config]="{ text: 'Hello world' }"
-        [mode]="editComponent ? 'config' : 'component'"
-      ></c8y-dynamic-component>
+      <form
+        name="form"
+        #configForm="ngForm"
+      >
+        <c8y-dynamic-component
+          componentId="angular.widget.demo"
+          [config]="{ text: 'Hello world' }"
+          [mode]="editComponent ? 'config' : 'component'"
+        ></c8y-dynamic-component>
+      </form>
     </div>
   </c8y-dashboard-child>
 </c8y-dashboard>

package/src/dashboard/custom-dashboard/custom-dashboard.component.ts

@@ -1,24 +1,18 @@
-import { Component } from '@angular/core';
-import { DashboardChildDimension, CoreModule } from '@c8y/ngx-components';
+import { AfterViewInit, Component, OnDestroy, ViewChild } from '@angular/core';
+import { CoreModule, DashboardChildDimension } from '@c8y/ngx-components';
 import { CommonModule } from '@angular/common';
 import { AssetSelectorModule } from '@c8y/ngx-components/assets-navigator';
 import { DatapointSelectorModule } from '@c8y/ngx-components/datapoint-selector';
-import { DashboardWidgetDemoModule } from '../../widget';
+import { NgForm } from '@angular/forms';
+import { Subscription } from 'rxjs';
 
 @Component({
-  selector: 'custom-dashboard',
+  selector: 'tut-custom-dashboard',
   templateUrl: './custom-dashboard.component.html',
   standalone: true,
-  imports: [
-    CommonModule,
-    CoreModule,
-    AssetSelectorModule,
-    DatapointSelectorModule,
-    // TODO: REMOVE ME
-    DashboardWidgetDemoModule
-  ]
+  imports: [CommonModule, CoreModule, AssetSelectorModule, DatapointSelectorModule]
 })
-export class CustomDashboardComponent {
+export class CustomDashboardComponent implements AfterViewInit, OnDestroy {
   widgets = [
     { x: 0, y: 0, width: 12, height: 1 },
     { x: 3, y: 1, width: 5, height: 2 }
@@ -27,6 +21,21 @@ export class CustomDashboardComponent {
   showTitle = true;
   editComponent = false;
 
+  @ViewChild('configForm', { static: false })
+  configForm: NgForm;
+
+  subscription: Subscription;
+
+  ngAfterViewInit() {
+    this.subscription = this.configForm.valueChanges.subscribe(value =>
+      console.log('Widget config:', value)
+    );
+  }
+
+  ngOnDestroy() {
+    this.subscription.unsubscribe();
+  }
+
   /**
    * Add a random child to the dashboard.
    */

package/src/dashboard/named-context-dashboard/named-context-dashboard.component.ts

@@ -6,9 +6,8 @@ import { CommonModule } from '@angular/common';
 import { ContextDashboardModule } from '@c8y/ngx-components/context-dashboard';
 
 @Component({
-  selector: 'app-named-context-dashboard',
+  selector: 'tut-named-context-dashboard',
   template: `<c8y-title>Named context dashboard</c8y-title>
-    <!--    TODO: verify if device is found and everything is displaying properly -->
     <c8y-context-dashboard
       [name]="name"
       [defaultWidgets]="defaultWidgets"

package/src/dashboard/service-dashboard/service-dashboard.component.ts

@@ -6,7 +6,7 @@ import { CommonModule } from '@angular/common';
 import { ContextDashboardModule } from '@c8y/ngx-components/context-dashboard';
 
 @Component({
-  selector: 'app-service-dashboard',
+  selector: 'tut-service-dashboard',
   template: `<c8y-title>Service dashboard</c8y-title>
     <!--    TODO: check what to do with this example -->
     <c8y-context-dashboard

package/src/dashboard/widget-dashboard/widget-dashboard.component.ts

@@ -15,7 +15,7 @@ import { CommonModule } from '@angular/common';
         canDelete: false,
         translateWidgetTitle: false,
         allowFullscreen: true,
-        title: false
+        title: ''
       }"
       (onFreeze)="toggleFreeze($event)"
       (onChangeDashboard)="change($event)"
@@ -23,11 +23,6 @@ import { CommonModule } from '@angular/common';
       (onEditWidget)="editWidget($event)"
       (onEditDashboard)="editDashboard()"
     >
-      <!-- TODO: check me
-    Not added to demo that the functionality is gone then:
-    (onDeleteWidget)="deleteWidget($event)"
-    (onDeleteDashboard)="deleteDashboard($event)"
-  -->
     </c8y-widgets-dashboard> `,
   standalone: true,
   imports: [CommonModule, CoreModule]

package/src/dashboard/widget-guide-context-dashboard/widget-guide-context-dashboard.component.ts

@@ -0,0 +1,42 @@
+import { Component } from '@angular/core';
+import { CoreModule, Widget } from '@c8y/ngx-components';
+import { CommonModule } from '@angular/common';
+import { AssetSelectorModule } from '@c8y/ngx-components/assets-navigator';
+import { DatapointSelectorModule } from '@c8y/ngx-components/datapoint-selector';
+import { ContextDashboardModule } from '@c8y/ngx-components/context-dashboard';
+
+@Component({
+  selector: 'tut-widget-guide-dashboard',
+  template: `
+    <c8y-title>Context dashboard</c8y-title>
+    <c8y-context-dashboard
+      name="example-widget"
+      [defaultWidgets]="defaultWidgets"
+      [canDelete]="false"
+    ></c8y-context-dashboard>
+  `,
+  standalone: true,
+  imports: [
+    CommonModule,
+    CoreModule,
+    AssetSelectorModule,
+    DatapointSelectorModule,
+    ContextDashboardModule
+  ]
+})
+export class WidgetGuideContextDashboardComponent {
+  defaultWidgets: Widget[] = [
+    {
+      _x: 3,
+      _y: 0,
+      _width: 6,
+      _height: 6,
+      componentId: 'angular.widget.demo',
+      config: {
+        text: 'Welcome to a context dashboard'
+      },
+      title: 'Hello',
+      id: 'some_unique_id'
+    }
+  ];
+}

package/src/dashboard/widget-guide-context-dashboard/widget-guide-context-dashboard.module.ts

@@ -0,0 +1,24 @@
+import { NgModule } from '@angular/core';
+import { NavigatorNode, hookNavigator, hookRoute } from '@c8y/ngx-components';
+
+@NgModule({
+  providers: [
+    hookRoute({
+      path: 'dashboards/widget-guide-context-dashboard',
+      loadComponent: () =>
+        import('./widget-guide-context-dashboard.component').then(
+          m => m.WidgetGuideContextDashboardComponent
+        )
+    }),
+    hookNavigator(
+      new NavigatorNode({
+        label: 'Widget guide context dashboard example',
+        path: '/dashboards/widget-guide-context-dashboard',
+        icon: 'th-large',
+        priority: -6,
+        parent: 'Dashboards'
+      })
+    )
+  ]
+})
+export class WidgetGuideContextDashboardModule {}

package/src/dashboard/widget-guide-dashboard/widget-guide-dashboard.component.ts

@@ -0,0 +1,70 @@
+import { Component, OnDestroy, ViewChild } from '@angular/core';
+import { CoreModule } from '@c8y/ngx-components';
+import { CommonModule } from '@angular/common';
+import { AssetSelectorModule } from '@c8y/ngx-components/assets-navigator';
+import { DatapointSelectorModule } from '@c8y/ngx-components/datapoint-selector';
+import { NgForm } from '@angular/forms';
+import { Subscription } from 'rxjs';
+
+@Component({
+  selector: 'tut-widget-guide-dashboard',
+  template: `
+    <c8y-title>Custom dashboard</c8y-title>
+    <c8y-action-bar-item [placement]="'right'">
+      <button class="btn btn-link" title="{{ 'Toggle freeze' }}" (click)="isFrozen = !isFrozen">
+        <i [c8yIcon]="isFrozen ? 'lock' : 'unlock'"></i>
+        {{ 'Toggle freeze' }}
+      </button>
+    </c8y-action-bar-item>
+    <c8y-dashboard>
+      <!-- Dashboard child with a dynamic component -->
+      <c8y-dashboard-child [width]="10" [height]="4">
+        <c8y-dashboard-child-title>
+          <span>Dynamic component child title</span>
+        </c8y-dashboard-child-title>
+        <c8y-dashboard-child-action>
+          <button
+            title="{{ 'Configure this widget' }}"
+            type="button"
+            (click)="editComponent = !editComponent; (false)"
+          >
+            <i [c8yIcon]="'cog'"></i>
+            {{ !editComponent ? 'Configure this widget' : 'Close configuration' }}
+          </button>
+        </c8y-dashboard-child-action>
+        <div class="card-block">
+          <form name="form" #configForm="ngForm">
+            <!--            important -->
+            <c8y-dynamic-component
+              componentId="angular.widget.demo"
+              [config]="{ text: 'Hello world' }"
+              [mode]="editComponent ? 'config' : 'component'"
+            ></c8y-dynamic-component>
+            <!--            /important-->
+          </form>
+        </div>
+      </c8y-dashboard-child>
+    </c8y-dashboard>
+  `,
+  standalone: true,
+  imports: [CommonModule, CoreModule, AssetSelectorModule, DatapointSelectorModule]
+})
+export class WidgetGuideDashboardComponent implements OnDestroy {
+  isFrozen = false;
+  editComponent = false;
+
+  @ViewChild('configForm', { static: false })
+  configForm: NgForm;
+
+  subscription: Subscription;
+
+  ngAfterViewInit() {
+    this.subscription = this.configForm.valueChanges.subscribe(value =>
+      console.log('Widget config:', value)
+    );
+  }
+
+  ngOnDestroy() {
+    this.subscription.unsubscribe();
+  }
+}

package/src/dashboard/widget-guide-dashboard/widget-guide-dashboard.module.ts

@@ -0,0 +1,22 @@
+import { NgModule } from '@angular/core';
+import { NavigatorNode, hookNavigator, hookRoute } from '@c8y/ngx-components';
+
+@NgModule({
+  providers: [
+    hookRoute({
+      path: 'dashboards/widget-guide-dashboard',
+      loadComponent: () =>
+        import('./widget-guide-dashboard.component').then(m => m.WidgetGuideDashboardComponent)
+    }),
+    hookNavigator(
+      new NavigatorNode({
+        label: 'Widget guide dashboard example',
+        path: '/dashboards/widget-guide-dashboard',
+        icon: 'th-large',
+        priority: -6,
+        parent: 'Dashboards'
+      })
+    )
+  ]
+})
+export class WidgetGuideDashboardModule {}

package/src/widget/demo-widget.component.ts

@@ -1,35 +1,60 @@
-import { Component, Input, SimpleChanges } from '@angular/core';
+import { Component, Input, OnChanges, SimpleChanges } from '@angular/core';
+import {
+  DismissAlertStrategy,
+  DynamicComponentAlert,
+  DynamicComponentAlertAggregator,
+  gettext
+} from '@c8y/ngx-components';
 
 @Component({
   selector: 'c8y-widget-demo',
   template: `
     <div class="p-16">
       <h1>Hi I'm a widget from angular</h1>
-      <p class="text">{{ config?.text || 'No text' }}</p>
+      <p class="text">Text from config object: {{ config?.text || 'No text' }}</p>
       <small>My context is: {{ config?.device?.name || 'No context' }}</small
       ><br />
-      My time context is:
-      <ul *ngIf="config?.date?.length === 2">
-        <li>from: {{ (config?.date[0] | c8yDate) || 'No time context' }}</li>
-        <li>To: {{ (config?.date[1] | c8yDate) || 'No time context' }}</li>
-      </ul>
+      <ng-container *ngIf="config?.date?.length === 2">
+        My time context is:
+        <ul>
+          <li>from: {{ (config?.date[0] | c8yDate) || 'No time context' }}</li>
+          <li>To: {{ (config?.date[1] | c8yDate) || 'No time context' }}</li>
+        </ul>
+      </ng-container>
+      <button class="btn btn-default" (click)="addAlert()">Add warning alert</button>
     </div>
   `,
   styles: [
     `
       .text {
-        transform: scaleX(-1);
-        font-size: 3em;
+        font-size: 2em;
       }
     `
   ]
 })
-export class WidgetDemo {
+export class WidgetDemo implements OnChanges {
   @Input() config;
+  alerts: DynamicComponentAlertAggregator;
+
+  ngOnInit() {
+    this.alerts.setAlertGroupDismissStrategy(
+      'warning',
+      DismissAlertStrategy.TEMPORARY_OR_PERMANENT
+    );
+  }
 
   ngOnChanges(changes: SimpleChanges): void {
-    if (!changes.config.firstChange && changes.config.currentValue.date) {
+    if (!changes['config']?.firstChange && changes['config']?.currentValue.date) {
       console.log('Global time context changed:', this.config.date);
     }
   }
+
+  addAlert() {
+    this.alerts.addAlerts(
+      new DynamicComponentAlert({
+        type: 'warning',
+        text: gettext('Operation not supported by this device.')
+      })
+    );
+  }
 }

package/src/widget/demo-widget.module.ts

@@ -1,5 +1,11 @@
 import { NgModule } from '@angular/core';
-import { CommonModule as C8yCommonModule, FormsModule, hookComponent } from '@c8y/ngx-components';
+import {
+  CommonModule as C8yCommonModule,
+  DynamicComponentDefinition,
+  DynamicComponentErrorStrategy,
+  FormsModule,
+  hookComponent
+} from '@c8y/ngx-components';
 import { AssetSelectorModule } from '@c8y/ngx-components/assets-navigator';
 import { ContextWidgetConfig } from '@c8y/ngx-components/context-dashboard';
 import { WidgetConfigDemo } from './demo-widget-config.component';
@@ -23,6 +29,7 @@ import { WidgetDemo } from './demo-widget.component';
       description: 'This is a description from  angular',
       component: WidgetDemo,
       configComponent: WidgetConfigDemo,
+      errorStrategy: DynamicComponentErrorStrategy.OVERLAY_ERROR,
 
       /** new Angular-Dashboard definition */
       data: {
@@ -41,7 +48,7 @@ import { WidgetDemo } from './demo-widget.component';
           globalTimeContext: true // Set this to true, to add a global time context binding
         }
       } as ContextWidgetConfig
-    })
+    } as DynamicComponentDefinition)
   ]
 })
 export class DashboardWidgetDemoModule {}

package/src/widget-resolvers/widget-resolvers.module.ts

@@ -2,6 +2,7 @@ import { NgModule } from '@angular/core';
 import { WidgetResolversComponent } from './widget-resolvers.component';
 import {
   CommonModule,
+  DynamicComponentDefinition,
   DynamicComponentErrorStrategy,
   DynamicManagedObjectResolver,
   FormsModule,
@@ -44,7 +45,7 @@ import { ContextWidgetConfig } from '@c8y/ngx-components/context-dashboard';
           }
         }
       } as ContextWidgetConfig
-    })
+    } satisfies DynamicComponentDefinition)
   ]
 })
 export class WidgetResolversModule {}

package/tsconfig.app.json

@@ -14,5 +14,8 @@
   "include": [
     "src/**/*.ts",
     "../ngx-components/**/*.ts"
+  ],
+  "exclude": [
+    "../ngx-components/dist",
   ]
-}
+}