@c8y/tutorial 1023.47.3 → 1023.48.2

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@c8y/tutorial",
-  "version": "1023.47.3",
+  "version": "1023.48.2",
   "description": "This package is used to scaffold a tutorial for Cumulocity IoT Web SDK which explains a lot of concepts.",
   "dependencies": {
-    "@c8y/style": "1023.47.3",
-    "@c8y/ngx-components": "1023.47.3",
-    "@c8y/client": "1023.47.3",
-    "@c8y/bootstrap": "1023.47.3",
+    "@c8y/style": "1023.48.2",
+    "@c8y/ngx-components": "1023.48.2",
+    "@c8y/client": "1023.48.2",
+    "@c8y/bootstrap": "1023.48.2",
     "@angular/cdk": "^20.2.14",
     "monaco-editor": "~0.53.0",
     "ngx-bootstrap": "20.0.2",
@@ -14,8 +14,8 @@
     "rxjs": "7.8.2"
   },
   "devDependencies": {
-    "@c8y/options": "1023.47.3",
-    "@c8y/devkit": "1023.47.3"
+    "@c8y/options": "1023.48.2",
+    "@c8y/devkit": "1023.48.2"
   },
   "peerDependencies": {
     "@angular/common": ">=20 <21"

package/src/__mocks/scoped-mocks/context-dashboard.ts

@@ -5,7 +5,9 @@ import { generateResponse, handleRequest } from '../utils/common';
 import { generateDashboard } from '../../__mocks/utils/generators/managedObjects';
 
 export class ContextDashboardInterceptor implements HttpInterceptor {
-  dashboard = generateDashboard();
+  dashboard = generateDashboard({
+    device: { id: '12345', name: 'Demo Sensor Device' }
+  });
 
   intercept(req: ApiCall, next: HttpHandler): Observable<IFetchResponse> {
     return handleRequest(req, next, 'inventory/managedObjects', {

package/src/__mocks/utils/generators/managedObjects.ts

@@ -172,10 +172,10 @@ export function generateDashboard({
           _x: 3,
           _y: 0,
           id: id,
-          title: 'Hello',
+          title: 'Demo Widget Example',
           _width: 6,
           config: {
-            text: 'Welcome to a context dashboard'
+            text: 'This text is configured via the widget settings. Click the edit button to change it!'
           },
           _height: 6
         }

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

@@ -17,6 +17,14 @@ import { ContextDashboardModule } from '@c8y/ngx-components/context-dashboard';
   imports: [ContextDashboardModule, CoreModule, CommonModule]
 })
 export class WidgetGuideContextDashboardComponent {
+  /**
+   * Default widgets shown when no dashboard exists in the backend.
+   *
+   * Note: In the codex environment, the mock interceptor at
+   * `packages/tutorial/src/__mocks/utils/generators/managedObjects.ts`
+   * returns a fake dashboard, so these defaults are not used.
+   * If you change these values, also update `generateDashboard()` in the mock.
+   */
   defaultWidgets: Widget[] = [
     {
       _x: 3,
@@ -25,10 +33,10 @@ export class WidgetGuideContextDashboardComponent {
       _height: 6,
       componentId: 'angular.widget.demo',
       config: {
-        text: 'Welcome to a context dashboard'
+        text: 'This text is configured via the widget settings. Click the edit button to change it!'
       },
-      title: 'Hello',
-      id: 'some_unique_id'
+      title: 'Demo Widget Example1',
+      id: 'demo_widget_example'
     }
   ];
 }

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

@@ -1,13 +1,27 @@
-import { Component, Input } from '@angular/core';
-import { ControlContainer, NgForm, FormsModule } from '@angular/forms';
+import { AsyncPipe } from '@angular/common';
 import {
-  DynamicComponent,
-  OnBeforeSave,
-  AlertService,
-  FormGroupComponent
-} from '@c8y/ngx-components';
-import { omit } from 'lodash';
-import { JsonPipe } from '@angular/common';
+  Component,
+  DestroyRef,
+  inject,
+  Input,
+  OnInit,
+  TemplateRef,
+  ViewChild
+} from '@angular/core';
+import { takeUntilDestroyed } from '@angular/core/rxjs-interop';
+import {
+  ControlContainer,
+  FormBuilder,
+  FormControl,
+  FormGroup,
+  NgForm,
+  ReactiveFormsModule,
+  Validators
+} from '@angular/forms';
+import { AlertService, DynamicComponent, FormGroupComponent } from '@c8y/ngx-components';
+import { WidgetConfigService } from '@c8y/ngx-components/context-dashboard';
+import { BehaviorSubject } from 'rxjs';
+import { WidgetDemo } from './demo-widget.component';
 import { WidgetConfig } from './widget-config.model';
 
 @Component({
@@ -16,75 +30,64 @@ import { WidgetConfig } from './widget-config.model';
     <div class="form-group">
       <c8y-form-group>
         <label>Text</label>
-        <textarea
-          style="width: 100%"
-          name="text"
-          [(ngModel)]="config.text"
-          [required]="true"
-        ></textarea>
+        <textarea style="width: 100%" [formControl]="formGroup.controls.text"></textarea>
       </c8y-form-group>
-
-      <label
-        >Configuration
-        <button class="btn btn-primary btn-xs" type="button" (click)="more = !more">
-          {{ more ? 'Hide' : 'Show' }} settings
-        </button></label
-      >
-      <pre><code>{{ clean(config, more) | json }}</code></pre>
     </div>
+
+    <ng-template #widgetPreview>
+      <c8y-widget-demo [config]="config$ | async"></c8y-widget-demo>
+    </ng-template>
   `,
-  // We connect our parent Form to this form (for disabling the save button)
-  // you can also enable the button by using ContextServiceDashboard.formDisabled
-  // property instead (by default it is enabled).
   viewProviders: [{ provide: ControlContainer, useExisting: NgForm }],
   standalone: true,
-  imports: [FormGroupComponent, FormsModule, JsonPipe]
+  imports: [FormGroupComponent, ReactiveFormsModule, WidgetDemo, AsyncPipe]
 })
-export class WidgetConfigDemo implements DynamicComponent, OnBeforeSave {
-  /**
-   * The configuration which is shared between configuration component and display component.
-   * Should be searilzabled to allow to save it to the API. The config is saved automatically
-   * to the API on "save"-button hit. The onBeforeSave handler can be used to change this behavior,
-   * or to manipulate the object.
-   *
-   * Note: The dashboard itself adds certain properties. As such, some properties are not allowed (e.g. device or settings)
-   */
+export class WidgetConfigDemo implements DynamicComponent, OnInit {
+  /** Configuration passed by the dashboard framework. */
   @Input() config: WidgetConfig = {};
 
-  /**
-   * An internal component property used to hide/show settings.
-   */
-  more = false;
+  /** Reactive form group for the widget configuration. */
+  formGroup: FormGroup<{ text: FormControl<string | null> }>;
 
-  /**
-   * Default Angular DI can be used, to use additional services.
-   */
-  constructor(private alert: AlertService) {}
+  /** Emits config changes for the preview template. */
+  config$ = new BehaviorSubject<WidgetConfig>({});
 
-  /**
-   * This example onBeforeSave handler cancels the saving, if the text is only a white-space.
-   */
-  onBeforeSave(config: any): boolean {
-    if (config.text.trim() === '') {
-      this.alert.warning('Please enter a valid text.');
-      return false;
-    }
-    this.config.widgetInstanceGlobalTimeContext = true;
-    this.config.canDecoupleGlobalTimeContext = true;
-    return true;
-  }
+  private readonly alert = inject(AlertService);
+  private readonly widgetConfigService = inject(WidgetConfigService);
+  private readonly formBuilder = inject(FormBuilder);
+  private readonly form = inject(NgForm);
+  private readonly destroyRef = inject(DestroyRef);
 
-  /**
-   * Used to hide/show config settings on toggle.
-   */
-  clean(config, more) {
-    if (more) {
-      return config;
-    }
-    return omit(config, 'settings');
+  @ViewChild('widgetPreview')
+  set preview(template: TemplateRef<any>) {
+    this.widgetConfigService.setPreview(template ?? null);
   }
 
-  selectionChanged(e) {
-    console.log(e);
+  ngOnInit(): void {
+    // Create form with initial values from config
+    this.formGroup = this.formBuilder.group({
+      text: [this.config?.text || '', Validators.required]
+    });
+
+    // Register form with parent NgForm for validation
+    this.form.form.addControl('widgetConfig', this.formGroup);
+
+    // Initialize preview
+    this.config$.next(this.config);
+
+    // Update preview when form values change
+    this.formGroup.valueChanges.pipe(takeUntilDestroyed(this.destroyRef)).subscribe(value => {
+      this.config$.next({ ...this.config, ...value });
+    });
+
+    // Register save callback - validates and merges form values into config
+    this.widgetConfigService.addOnBeforeSave(config => {
+      if (this.formGroup.invalid) {
+        this.alert.warning('Please enter a valid text.');
+        return false;
+      }
+      Object.assign(config, this.formGroup.value);
+      return true;
+    });
   }
 }

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

@@ -1,65 +1,55 @@
-import { Component, Input, OnChanges, SimpleChanges } from '@angular/core';
-import { gettext } from '@c8y/ngx-components/gettext';
+import { Component, computed, input, OnInit } from '@angular/core';
 import {
   DismissAlertStrategy,
   DynamicComponentAlert,
-  DynamicComponentAlertAggregator,
-  DatePipe
+  DynamicComponentAlertAggregator
 } from '@c8y/ngx-components';
-import { NgIf } from '@angular/common';
 import { WidgetConfig } from './widget-config.model';
 
 @Component({
   selector: 'c8y-widget-demo',
   template: `
     <div class="p-16">
-      <h1>Hi I'm a widget from angular</h1>
-      <p class="text">Text from config object: {{ config?.text || 'No text' }}</p>
-      <small>My context is: {{ config?.device?.name || 'No context' }}</small
-      ><br />
-      <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>
+      <h1>Demo Widget</h1>
+      <p class="text">{{ displayText() }}</p>
+      @if (deviceName()) {
+        <small>Device: {{ deviceName() }}</small>
+      }
+      <div class="m-t-16">
+        <button class="btn btn-default btn-sm" (click)="showAlert()">Show alert</button>
+      </div>
     </div>
   `,
   styles: [
     `
       .text {
-        font-size: 2em;
+        font-size: 1.5em;
+        color: var(--c8y-brand-primary);
       }
     `
   ],
-  standalone: true,
-  imports: [NgIf, DatePipe]
+  standalone: true
 })
-export class WidgetDemo implements OnChanges {
-  @Input() config: WidgetConfig;
-  alerts: DynamicComponentAlertAggregator;
+export class WidgetDemo implements OnInit {
+  readonly config = input<WidgetConfig>();
 
-  ngOnInit() {
-    this.alerts.setAlertGroupDismissStrategy(
-      'warning',
-      DismissAlertStrategy.TEMPORARY_OR_PERMANENT
-    );
-  }
+  /** Computed signal for display text with fallback */
+  readonly displayText = computed(() => this.config()?.text || 'No text configured');
+
+  /** Computed signal for device name */
+  readonly deviceName = computed(() => this.config()?.device?.name);
+
+  /** Set by the dashboard framework - used to display alerts on the widget */
+  alerts: DynamicComponentAlertAggregator;
 
-  ngOnChanges(changes: SimpleChanges): void {
-    if (!changes['config']?.firstChange && changes['config']?.currentValue.date) {
-      console.log('Global time context changed:', this.config.date);
-    }
+  ngOnInit(): void {
+    // Enable dismissible alerts for warning type
+    this.alerts?.setAlertGroupDismissStrategy('warning', DismissAlertStrategy.TEMPORARY);
   }
 
-  addAlert() {
-    this.alerts.addAlerts(
-      new DynamicComponentAlert({
-        type: 'warning',
-        text: gettext('Operation not supported by this device.')
-      })
+  showAlert(): void {
+    this.alerts?.addAlerts(
+      new DynamicComponentAlert({ type: 'warning', text: 'This is a dismissible demo alert!' })
     );
   }
 }

package/src/widget/index.ts

@@ -4,36 +4,17 @@ import { WidgetConfigDemo } from './demo-widget-config.component';
 
 export function provideDemoWidget() {
   return [
-    /**
-     * This demo widget provides an example on how
-     * to use the hookWidget. The component itself
-     * is implemented in the dashboard on the
-     * ../hello/hello.component.html by using the
-     * dynamic-component tag.
-     */
     hookWidget({
       id: 'angular.widget.demo',
-      label: 'My angular widget',
-      description: 'This is a description from  angular',
+      label: 'Demo Widget',
+      description: 'A simple demo widget showing text and device context',
       component: WidgetDemo,
       configComponent: WidgetConfigDemo,
       errorStrategy: DynamicComponentErrorStrategy.OVERLAY_ERROR,
-      /** new Angular-Dashboard definition */
       data: {
         schema: () => import('c8y-schema-loader?interfaceName=WidgetConfig!./widget-config.model'),
-        // The settings object can be used to configure the configComponent
         settings: {
-          noNewWidgets: false, // Set this to true, to don't allow adding new widgets.
-          ng1: {
-            options: {
-              noDeviceTarget: false, // Set this to true to hide the AngularJS device selector.
-              groupsSelectable: false // Set this, if not only devices should be selectable.
-            }
-          }
-        },
-        // Settings that are attached to the display component (in this case: WidgetDemo)
-        displaySettings: {
-          globalTimeContext: true // Set this to true, to add a global time context binding
+          noNewWidgets: false
         }
       }
     })

package/src/widget/widget-config.model.ts

@@ -1,3 +1,6 @@
-import { GlobalTimeContextWidgetConfig } from '@c8y/ngx-components';
+import { IIdentified, IManagedObject } from '@c8y/client';
 
-export type WidgetConfig = GlobalTimeContextWidgetConfig & { [key: string]: any };
+export interface WidgetConfig {
+  text?: string;
+  device?: IIdentified & Partial<IManagedObject>;
+}