c8y-widget

name	c8y-widget
description	Comprehensive guide for developing custom widgets in Cumulocity, covering prerequisites, dynamic components, and step-by-step examples. Use when building UI widgets.

This section covers the prerequisites for widget development, explains dynamic components, and provides a step-by-step example of building a simple widget and using it in a dashboard.

Prerequisites

Key concepts essential for widget and dashboard development.

Widgets

Widgets are modular components that display data and interact with other parts of the Cumulocity platform. They can present maps, images, graphs, tables, and other graphical representations of data. Widgets are useful for tracking information (such as alarms, assets, or applications), or for providing maps, quick links, and more in dashboards or reports. Multiple widgets are available in c8y/ngx-components, but you can also create your own custom widgets.

Dashboards

Dashboards are the surfaces where widgets are displayed. There are two types of dashboards:

• Context dashboard: Resolves its data from the current context (device or group) it is displayed on. This type is usually created by the user.
• Named-context dashboard: A context dashboard with a name, created programmatically for the device as a child addition.

hookComponent and dynamic components

The hookComponent function allows you to add dynamic components to the UI (such as widgets). To use this function, call hookComponent and provide a component object compatible with DynamicComponentDefinition type.

Dynamic components allow you to display already registered components. This mechanism is used internally in ContextDashboardComponent, but you can also use it directly in the DashboardComponent.

Creating an application and adding a custom widget

The following steps describe how to create a new application with a custom widget.

Initialize an example application

Install the Angular 19 @angular/cli package:

npm install @angular/cli@19 -g

Generate a new Angular 19 application:

ng new <appName> --interactive=false --style=less --ssr=false

Navigate to the application directory:

cd <appName>

Use the ng add command to include @c8y/websdk, and follow the prompts. For this example, select the Cockpit application when prompted to choose which application to add.

ng add @c8y/websdk

Create a custom widget

In this example, the custom widget implementation consists of three elements:

WidgetDemo component class

Responsible for displaying a widget on the dashboard. It has one input for the config object, which can be stored in the database and configured by the widget config.

WidgetConfigDemo component class

Handles changing the configuration of an existing or new widget. You must add a config object, which you can fill with any serializable configuration you want to pass to the widget. To enable widget configuration validation, add the appropriate option to the @Component decorator.

DashboardWidgetDemoModule

Encapsulates the entire widget functionality and registers the widget for use in the application. The most important element of the module is the hookComponent. The hook method is called with an object that implements DynamicComponentDefinition and contains all necessary data, such as the dynamic component ID, view and config classes, and settings.

File: demo-widget.component.ts

import { Component, computed, input, OnInit } from "@angular/core";
import {
  DismissAlertStrategy,
  DynamicComponentAlert,
  DynamicComponentAlertAggregator,
} from "@c8y/ngx-components";
import { WidgetConfig } from "./widget-config.model";

@Component({
  selector: "c8y-widget-demo",
  template: `
    <div class="p-16">
      <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: 1.5em;
        color: var(--c8y-brand-primary);
      }
    `,
  ],
  standalone: true,
})
export class WidgetDemo implements OnInit {
  readonly config = input<WidgetConfig>();

  /** 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;

  ngOnInit(): void {
    // Enable dismissible alerts for warning type
    this.alerts?.setAlertGroupDismissStrategy(
      "warning",
      DismissAlertStrategy.TEMPORARY,
    );
  }

  showAlert(): void {
    this.alerts?.addAlerts(
      new DynamicComponentAlert({
        type: "warning",
        text: "This is a dismissible demo alert!",
      }),
    );
  }
}

File: demo-widget-config.component.ts

import { AsyncPipe } from "@angular/common";
import {
  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({
  selector: "c8y-widget-config-demo",
  template: `
    <div class="form-group">
      <c8y-form-group>
        <label>Text</label>
        <textarea style="width: 100%" [formControl]="formGroup.controls.text"></textarea>
      </c8y-form-group>
    </div>

    <ng-template #widgetPreview>
      <c8y-widget-demo [config]="config$ | async"></c8y-widget-demo>
    </ng-template>
  `,
  viewProviders: [{ provide: ControlContainer, useExisting: NgForm }],
  standalone: true,
  imports: [FormGroupComponent, ReactiveFormsModule, WidgetDemo, AsyncPipe],
})
export class WidgetConfigDemo implements DynamicComponent, OnInit {
  /** Configuration passed by the dashboard framework. */
  @Input() config: WidgetConfig = {};

  /** Reactive form group for the widget configuration. */
  formGroup: FormGroup<{ text: FormControl<string | null> }>;

  /** Emits config changes for the preview template. */
  config$ = new BehaviorSubject<WidgetConfig>({});

  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);

  @ViewChild("widgetPreview")
  set preview(template: TemplateRef<any>) {
    this.widgetConfigService.setPreview(template ?? null);
  }

  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;
    });
  }
}

File: index.ts (Module definition)

import { DynamicComponentErrorStrategy, hookWidget } from "@c8y/ngx-components";
import { WidgetDemo } from "./demo-widget.component";
import { WidgetConfigDemo } from "./demo-widget-config.component";

export function provideDemoWidget() {
  return [
    hookWidget({
      id: "angular.widget.demo",
      label: "Demo Widget",
      description: "A simple demo widget showing text and device context",
      component: WidgetDemo,
      configComponent: WidgetConfigDemo,
      errorStrategy: DynamicComponentErrorStrategy.OVERLAY_ERROR,
      data: {
        schema: () =>
          import(
            "c8y-schema-loader?interfaceName=WidgetConfig!./widget-config.model"
          ),
        settings: {
          noNewWidgets: false,
        },
      },
    }),
  ];
}

Add these three elements to your application source folder and import the provideDemoWidget() function into your application module providers.

Using your custom widget in the application

A widget can be used in two ways: implicitly within a context dashboard or directly as a dynamic component.

Using a widget in a context dashboard

In this scenario, the dynamic component is already integrated into the context dashboard. You can add your custom widget (named My angular widget or similar based on id/label) from the list of available widgets on the home or context dashboard.

Example Context Dashboard Component:

import { Component } from "@angular/core";
import { CoreModule, Widget } from "@c8y/ngx-components";
import { CommonModule } from "@angular/common";
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: [ContextDashboardModule, CoreModule, CommonModule],
})
export class WidgetGuideContextDashboardComponent {
  defaultWidgets: Widget[] = [
    {
      _x: 3,
      _y: 0,
      _width: 6,
      _height: 6,
      componentId: "angular.widget.demo",
      config: {
        text: "This text is configured via the widget settings. Click the edit button to change it!",
      },
      title: "Demo Widget Example1",
      id: "demo_widget_example",
    },
  ];
}

Direct usage of a dynamic component

Dynamic components can be used anywhere in the application, but are most commonly utilized as widgets within a dashboard component.

Example Direct Usage (Standalone Component Dashboard):

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();
  }
}