@c8y/tutorial 1021.3.1 → 1021.6.0

package/cumulocity.config.ts

@@ -1,6 +1,6 @@
 import { ConfigurationOptions } from '@c8y/devkit';
 import { DefinePlugin } from 'webpack';
-import { author, description, version, name } from './package.json';
+import { author, description, name, version } from './package.json';
 
 export default {
   runTime: {
@@ -261,6 +261,13 @@ export default {
         description: 'A sample for wizard hook.',
         scope: 'self'
       },
+      {
+        name: 'Service hook Codex sample',
+        module: 'ServiceHookCodexSampleModule',
+        path: './src/hooks/service/service-hook-codex-sample.module.ts',
+        description: 'A sample for hookService.',
+        scope: 'self'
+      },
       {
         name: 'Stepper',
         module: 'StepperHookModule',

package/package.json

@@ -1,20 +1,20 @@
 {
   "name": "@c8y/tutorial",
-  "version": "1021.3.1",
+  "version": "1021.6.0",
   "description": "This package is used to scaffold a tutorial for Cumulocity IoT Web SDK which explains a lot of concepts.",
   "dependencies": {
-    "@c8y/style": "1021.3.1",
-    "@c8y/ngx-components": "1021.3.1",
-    "@c8y/client": "1021.3.1",
-    "@c8y/bootstrap": "1021.3.1",
+    "@c8y/style": "1021.6.0",
+    "@c8y/ngx-components": "1021.6.0",
+    "@c8y/client": "1021.6.0",
+    "@c8y/bootstrap": "1021.6.0",
     "@angular/cdk": "^18.2.10",
     "ngx-bootstrap": "18.0.0",
     "leaflet": "1.9.4",
     "rxjs": "^7.8.1"
   },
   "devDependencies": {
-    "@c8y/options": "1021.3.1",
-    "@c8y/devkit": "1021.3.1"
+    "@c8y/options": "1021.6.0",
+    "@c8y/devkit": "1021.6.0"
   },
   "peerDependencies": {
     "@angular/common": ">=18 <19"

package/src/grids/server-grid-example/last-updated-data-grid-column/last-updated.cell-renderer.component.ts

@@ -0,0 +1,10 @@
+import { Component } from '@angular/core';
+import { CellRendererContext } from '@c8y/ngx-components';
+
+@Component({
+  template: ` {{ context.value | c8yDate }} `,
+  selector: 'c8y-last-updated-cell-renderer'
+})
+export class LastUpdatedCellRendererComponent {
+  constructor(public context: CellRendererContext) {}
+}

package/src/grids/server-grid-example/last-updated-data-grid-column/last-updated.data-grid-column.ts

@@ -0,0 +1,100 @@
+import { FormGroup } from '@angular/forms';
+import { BaseColumn, ColumnConfig, gettext } from '@c8y/ngx-components';
+import { LastUpdatedCellRendererComponent } from './last-updated.cell-renderer.component';
+
+/**
+ * Defines a class for custom Last updated date column.
+ * Implements `Column` interface and sets basic properties, as well as custom components.
+ */
+export class LastUpdatedDataGridColumn extends BaseColumn {
+  constructor(initialColumnConfig?: ColumnConfig) {
+    super(initialColumnConfig);
+    this.name = 'lastUpdated';
+    this.path = 'lastUpdated';
+    this.header = 'Last updated';
+
+    this.cellRendererComponent = LastUpdatedCellRendererComponent;
+
+    this.filterable = true;
+
+    this.filteringConfig = {
+      /**
+       * When using Formly schema, filter chips can be automatically generated by the
+       * data-grid library based on the filtering schema definition. You do not need
+       * to manually implement the chip generation. The Formly field definitions provided
+       * in the `filteringConfig` will automatically be transformed into chips by the
+       * data-grid system.
+       */
+      fields: [
+        {
+          type: 'object',
+          key: 'lastUpdated',
+          templateOptions: {
+            label: gettext('Show items last updated')
+          },
+          fieldGroup: [
+            {
+              type: 'date-time',
+              key: 'after',
+              templateOptions: {
+                label: gettext('from')
+              },
+              expressionProperties: {
+                'templateOptions.maxDate': (model: any) => model?.before
+              }
+            },
+            {
+              type: 'date-time',
+              key: 'before',
+              templateOptions: {
+                label: gettext('to')
+              },
+              expressionProperties: {
+                'templateOptions.minDate': (model: any) => model?.after
+              }
+            }
+          ],
+          validators: {
+            atLeastOneFilled: {
+              expression: (formGroup: any) => {
+                const after = formGroup.get('after').value;
+                const before = formGroup.get('before').value;
+                return after || before;
+              }
+            }
+          }
+        }
+      ],
+      formGroup: new FormGroup({}),
+      getFilter: model => {
+        const filter: any = {};
+        const dates = model?.lastUpdated;
+        if (dates?.after || dates?.before) {
+          filter.__and = [];
+          if (dates?.after) {
+            const after = this.formatDate(dates.after);
+            filter.__and.push({
+              'lastUpdated.date': { __gt: after }
+            });
+          }
+          if (dates?.before) {
+            const before = this.formatDate(dates.before);
+            filter.__and.push({
+              'lastUpdated.date': { __lt: before }
+            });
+          }
+        }
+        return filter;
+      }
+    };
+
+    this.sortable = true;
+    this.sortingConfig = {
+      pathSortingConfigs: [{ path: 'lastUpdated.date' }]
+    };
+  }
+
+  protected formatDate(dateToFormat: string): string {
+    return new Date(dateToFormat).toISOString();
+  }
+}

package/src/grids/server-grid-example/server-grid-example.module.ts

@@ -1,6 +1,5 @@
-import { CommonModule } from '@angular/common';
 import { NgModule } from '@angular/core';
-import { hookNavigator, hookRoute, NavigatorNode } from '@c8y/ngx-components';
+import { CommonModule, hookNavigator, hookRoute, NavigatorNode } from '@c8y/ngx-components';
 import { ServerGridActionControlsModule } from './server-grid-action-controls.module';
 
 @NgModule({

package/src/grids/server-grid-example/server-grid-example.service.ts

@@ -10,6 +10,8 @@ import {
   Pagination
 } from '@c8y/ngx-components';
 
+import { assign, get, identity } from 'lodash-es';
+import { LastUpdatedDataGridColumn } from './last-updated-data-grid-column/last-updated.data-grid-column';
 import { TypeDataGridColumn } from './type-data-grid-column/type.data-grid-column';
 
 /** Model for custom type filtering form. */
@@ -59,7 +61,8 @@ export class ServerGridExampleService {
         filterable: true,
         sortable: true
       },
-      new TypeDataGridColumn()
+      new TypeDataGridColumn(),
+      new LastUpdatedDataGridColumn()
     ];
 
     return columns;
@@ -177,43 +180,6 @@ export class ServerGridExampleService {
     return { icon, label };
   }
 
-  /** Returns a query object for given settings of filtering by type. */
-  getTypeQuery(model: TypeFilteringModel): any {
-    let query: any = {};
-
-    if (model.group) {
-      query = this.queriesUtil.addOrFilter(query, { type: 'c8y_DeviceGroup' });
-    }
-
-    if (model.device) {
-      query = this.queriesUtil.addOrFilter(query, { __has: 'c8y_IsDevice' });
-    }
-
-    if (model.smartRule) {
-      query = this.queriesUtil.addOrFilter(query, {
-        type: { __in: ['c8y_SmartRule', 'c8y_PrivateSmartRule'] }
-      });
-    }
-
-    if (model.dashboard) {
-      query = this.queriesUtil.addOrFilter(query, {
-        type: { __has: 'c8y_Dashboard' }
-      });
-    }
-
-    if (model.file) {
-      query = this.queriesUtil.addOrFilter(query, {
-        type: { __has: 'c8y_IsBinary' }
-      });
-    }
-
-    if (model.application) {
-      query = this.queriesUtil.addOrFilter(query, { type: 'c8y_Application_*' });
-    }
-
-    return query;
-  }
-
   /** Returns filters for given columns and pagination setup. */
   private getFilters(columns: Column[], pagination: Pagination) {
     return {
@@ -232,10 +198,11 @@ export class ServerGridExampleService {
   }
 
   /** Returns a query object based on columns setup. */
-  private getQueryObj(columns: Column[]): any {
+  private getQueryObj(columns: Column[], defaultFilter = {}): any {
     return transform(columns, (query, column) => this.addColumnQuery(query, column), {
       __filter: {},
-      __orderby: []
+      __orderby: [],
+      ...defaultFilter
     });
   }
 
@@ -251,7 +218,17 @@ export class ServerGridExampleService {
 
       // in the case of custom filtering form, we're storing the query in `externalFilterQuery.query`
       if (column.externalFilterQuery) {
-        query = this.queriesUtil.addAndFilter(query, column.externalFilterQuery.query);
+        const getFilter = column.filteringConfig.getFilter || identity;
+        const queryObj = getFilter(column.externalFilterQuery);
+
+        if (queryObj.__or) {
+          query.__filter.__and = query.__filter.__and || [];
+          query.__filter.__and.push(queryObj);
+        } else if (queryObj.__and && get(query, '__filter.__and')) {
+          queryObj.__and.map(obj => query.__filter.__and.push(obj));
+        } else {
+          assign(query.__filter, queryObj);
+        }
       }
     }
 

package/src/grids/server-grid-example/type-data-grid-column/type.data-grid-column.ts

@@ -1,47 +1,88 @@
 import { Type } from '@angular/core';
-import { Column, ColumnDataType, SortOrder, FilterPredicateFunction } from '@c8y/ngx-components';
-import { TypeHeaderCellRendererComponent } from './type.header-cell-renderer.component';
+import { BaseColumn, ColumnConfig, PartialFilterChipGenerationType } from '@c8y/ngx-components';
 import { TypeCellRendererComponent } from './type.cell-renderer.component';
 import { TypeFilteringFormRendererComponent } from './type.filtering-form-renderer.component';
+import { TypeHeaderCellRendererComponent } from './type.header-cell-renderer.component';
+
+const FILTER_TYPES = [
+  { key: 'group', label: 'Group' },
+  { key: 'device', label: 'Device' },
+  { key: 'smartRule', label: 'Smart Rule' },
+  { key: 'dashboard', label: 'Dashboard' },
+  { key: 'file', label: 'File' },
+  { key: 'application', label: 'Application' }
+];
 
 /**
- * Defines a class for custom Type column.
- * Implements `Column` interface and sets basic properties, as well as custom components.
+ * Defines a custom Type column with custom filtering form and chips generation.
  */
-export class TypeDataGridColumn implements Column {
-  name: string;
-  path?: string;
-  header?: string;
-  dataType?: ColumnDataType;
-
-  visible?: boolean;
-  positionFixed?: boolean;
-  gridTrackSize?: string;
+export class TypeDataGridColumn extends BaseColumn {
+  readonly name = 'type';
+  readonly header = 'Type';
 
-  headerCSSClassName?: string | string[];
-  headerCellRendererComponent?: Type<any>;
+  headerCellRendererComponent: Type<any> = TypeHeaderCellRendererComponent;
+  cellRendererComponent: Type<any> = TypeCellRendererComponent;
+  sortable = false;
+  filterable = true;
+  filteringFormRendererComponent: Type<any> = TypeFilteringFormRendererComponent;
 
-  cellCSSClassName?: string | string[];
-  cellRendererComponent?: Type<any>;
+  constructor(initialColumnConfig?: ColumnConfig) {
+    super(initialColumnConfig);
 
-  sortable?: boolean;
-  sortOrder?: SortOrder;
+    // Set the custom filtering configuration
+    this.filteringConfig = {
+      /**
+       * Generates filter chips based on the selected filters in the model.
+       * Each chip represents a filter and provides a way for users to visualize
+       * and remove the applied filters.
+       *
+       * @param model An object with defined structure (e.g. by schema).
+       * @returns return an array of partial filter chips with required properties 'displayValue' and 'value'.
+       */
+      generateChips: (model): PartialFilterChipGenerationType[] => {
+        const chips = [];
 
-  filterable?: boolean;
-  filteringFormRendererComponent?: Type<any>;
-  filterPredicate?: string | FilterPredicateFunction;
-  externalFilterQuery?: string | object;
+        FILTER_TYPES.forEach(type => {
+          if (model[type.key]) {
+            chips.push({
+              displayValue: type.label,
+              value: type.key,
+              remove: () => {
+                delete model[type.key];
+                return {
+                  externalFilterQuery: { ...model },
+                  columnName: this.name
+                };
+              }
+            });
+          }
+        });
 
-  constructor() {
-    this.name = 'type';
-    this.header = 'Type';
+        return chips;
+      },
+      /**
+       * Transforms a filtering config model (e.g. coming from schema form component) to a query object.
+       * However, using schema form component is not necessary.
+       * Model can be defined arbitrarily but must converted to a valid query object.
+       * @param model An object with defined structure (e.g. by schema).
+       * @returns A query object to be used to generate a query string (QueryUtils).
+       */
+      getFilter: model => {
+        const filter: any = {};
+        const ors = [];
 
-    this.headerCellRendererComponent = TypeHeaderCellRendererComponent;
-    this.cellRendererComponent = TypeCellRendererComponent;
+        if (model.group) ors.push({ type: 'c8y_DeviceGroup' });
+        if (model.device) ors.push({ __has: 'c8y_IsDevice' });
+        if (model.smartRule)
+          ors.push({ type: { __in: ['c8y_SmartRule', 'c8y_PrivateSmartRule'] } });
+        if (model.dashboard) ors.push({ type: { __has: 'c8y_Dashboard' } });
+        if (model.file) ors.push({ type: { __has: 'c8y_IsBinary' } });
+        if (model.application) ors.push({ type: 'c8y_Application_*' });
 
-    this.filterable = true;
-    this.filteringFormRendererComponent = TypeFilteringFormRendererComponent;
+        if (ors.length) filter.__or = ors;
 
-    this.sortable = false;
+        return filter;
+      }
+    };
   }
 }

package/src/grids/server-grid-example/type-data-grid-column/type.filtering-form-renderer.component.ts

@@ -1,6 +1,6 @@
-import { Component, Inject } from '@angular/core';
+import { Component } from '@angular/core';
 import { FilteringFormRendererContext, FormsModule } from '@c8y/ngx-components';
-import { ServerGridExampleService, TypeFilteringModel } from '../server-grid-example.service';
+import { TypeFilteringModel } from '../server-grid-example.service';
 
 /**
  * This is the example component for custom filtering form.
@@ -79,12 +79,9 @@ import { ServerGridExampleService, TypeFilteringModel } from '../server-grid-exa
 export class TypeFilteringFormRendererComponent {
   model: TypeFilteringModel;
 
-  constructor(
-    public context: FilteringFormRendererContext,
-    @Inject(ServerGridExampleService) public service: ServerGridExampleService
-  ) {
+  constructor(public context: FilteringFormRendererContext) {
     // restores the settings from current column setup
-    this.model = (this.context.property.externalFilterQuery || {}).model || {};
+    this.model = this.context.property.externalFilterQuery || {};
   }
 
   /**
@@ -94,10 +91,7 @@ export class TypeFilteringFormRendererComponent {
    */
   applyFilter() {
     this.context.applyFilter({
-      externalFilterQuery: {
-        model: this.model,
-        query: this.service.getTypeQuery(this.model)
-      }
+      externalFilterQuery: { ...this.model }
     });
   }
 

package/src/hooks/service/client/basic-view.component.html

@@ -0,0 +1,44 @@
+<c8y-title>Sharing a service between plugins</c8y-title>
+<div class="card-block">
+  <p>
+    A service instance can be used by components that need to communicate to each other or share a
+    common state. If these two components originate from different code bases, e.g. are deployed via
+    plugin-ins, then
+    <code>hookService</code>
+    comes as a way for such a shared service to be injected. The service interface might be declared
+    in a shared library known at compile time.
+  </p>
+  <p>
+    This example showcases two component instances that share a counter service. The counter service
+    interface is declared in the
+    <code>counder.model</code>
+    module which may be declared in a common library shared between plug-ins in a real world case.
+    The
+    <code>CounterHookModule</code>
+    leverages
+    <code>hookService</code>
+    to inject a service instance. This can happen in a plugin or in a shell application.
+  </p>
+</div>
+<div class="card-group">
+  <div class="col-md-6">
+    <div class="card">
+      <div class="card-header separator">
+        <p class="card-title">Component A</p>
+      </div>
+      <div class="card-block">
+        <c8y-dynamic-component componentId="counter.component"></c8y-dynamic-component>
+      </div>
+    </div>
+  </div>
+  <div class="col-md-6">
+    <div class="card">
+      <div class="card-header separator">
+        <p class="card-title">Component B</p>
+      </div>
+      <div class="card-block">
+        <c8y-dynamic-component componentId="counter.component"></c8y-dynamic-component>
+      </div>
+    </div>
+  </div>
+</div>

package/src/hooks/service/client/basic-view.component.ts

@@ -0,0 +1,13 @@
+import { Component } from '@angular/core';
+import { CoreModule } from '@c8y/ngx-components';
+
+/**
+ * This is the component that hosts the Service demo view.
+ */
+@Component({
+  selector: 'tut-basic-component-hook-view',
+  templateUrl: './basic-view.component.html',
+  standalone: true,
+  imports: [CoreModule]
+})
+export class BasicViewComponent {}

package/src/hooks/service/client/counter.component.html

@@ -0,0 +1,15 @@
+<p>
+  Hello there! I am a simple component added from a plugin by
+  <code>hookComponent</code>
+  . I use a shared counter service that has been provided in another plugin and injected by
+  <code>hookService</code>
+  .
+</p>
+<button
+  class="btn btn-default m-t-16"
+  type="button"
+  (click)="counter.count()"
+>
+  Click to increment counter
+  <span class="badge badge-system">{{ counter.counter }}</span>
+</button>

package/src/hooks/service/client/counter.component.ts

@@ -0,0 +1,21 @@
+import { Component } from '@angular/core';
+import { ServiceRegistry } from '@c8y/ngx-components';
+import { ICounterService } from '../counter/counter.model';
+
+@Component({
+  selector: 'tut-counter-component',
+  templateUrl: './counter.component.html',
+  standalone: true
+})
+export class CounterComponent {
+  counter: ICounterService;
+
+  constructor(registry: ServiceRegistry) {
+    /**
+     * To retrieve an instance of a service injected by `hookService` you can use ServiceRegistry.get(key) method.
+     * It will return all injected service instances in a type-safe manner if there is a typed extension key declared.
+     * For an example of such declaration check the declarations in `counter/counter.model.ts`.
+     */
+    this.counter = registry.get('counter').at(0);
+  }
+}

package/src/hooks/service/client/index.ts

@@ -0,0 +1,3 @@
+export * from './basic-view.component';
+export * from './counter.component';
+export * from './service-hook.module';

package/src/hooks/service/client/service-hook.module.ts

@@ -0,0 +1,29 @@
+import { NgModule } from '@angular/core';
+import { NavigatorNode, hookComponent, hookNavigator, hookRoute } from '@c8y/ngx-components';
+
+@NgModule({
+  providers: [
+    /* Hook the Service hook demo view */
+    hookRoute({
+      path: 'hooks/service',
+      loadComponent: () => import('./basic-view.component').then(m => m.BasicViewComponent)
+    }),
+    hookNavigator(
+      new NavigatorNode({
+        priority: 40,
+        path: 'hooks/service',
+        icon: 'gears',
+        label: 'Service',
+        parent: 'Hooks'
+      })
+    ),
+    /* Hook a client component for the service provided via `hookService` */
+    hookComponent({
+      id: 'counter.component',
+      label: 'Counter component',
+      description: 'This component can count',
+      loadComponent: () => import('./counter.component').then(m => m.CounterComponent)
+    })
+  ]
+})
+export class ServiceHookModule {}

package/src/hooks/service/counter/counter.model.ts

@@ -0,0 +1,43 @@
+/**
+ * Declare the contract of the service that will be injected via `hookService` in an interface.
+ * This interface will be used also to bind a type to the key used for providing and retrieving the service.
+ * This interface should be declared in a module that is shared between modules that use the service and those that implement and inject it.
+ */
+export interface ICounterService {
+  /**
+   * Current counter state.
+   */
+  counter: number;
+  /**
+   * Increment counter value.
+   */
+  count: () => void;
+}
+
+declare global {
+  /**
+   * The `CumulocityServiceRegistry` namespaces is declared in `@c8y/ngx-components` as part of the global scope.
+   * This allows you to augment the service registry by adding your typed extension keys.
+   */
+  // eslint-disable-next-line @typescript-eslint/no-namespace
+  namespace CumulocityServiceRegistry {
+    interface ExtensionKeys {
+      /**
+       * The extension key used for injecting and retrieving hooked services.
+       * To provide a service with a key provide the service using `hookService`:
+       *
+       * ```typescript
+       * @NgModule({
+       *   providers: [hookService('counter', CounterService)]
+       * })
+       * ```
+       *
+       * In your client code you can use `ServiceRegistry` to retrieve an instance of the injected service:
+       * ```typescript
+       * ServiceRegistry.get(key)
+       * ```
+       */
+      counter: ICounterService;
+    }
+  }
+}

package/src/hooks/service/counter/counter.module.ts

@@ -0,0 +1,13 @@
+import { NgModule } from '@angular/core';
+import { hookService } from '@c8y/ngx-components';
+import { CounterService } from './counter.service';
+
+@NgModule({
+  /**
+   * To provide a service using `hookService`, you pass a key that clients will use to retrieve the service instance.
+   * By extending the `ExtensionKeys` interface in the `CumulocityServiceRegistry` namespace, you declare the key for your service.
+   * `hookService` then enforces type safety, ensuring only services that implement the corresponding interface can be provided for that key.
+   */
+  providers: [hookService('counter', CounterService)]
+})
+export class CounterHookModule {}

package/src/hooks/service/counter/counter.service.ts

@@ -0,0 +1,10 @@
+import { Injectable } from '@angular/core';
+import { ICounterService } from './counter.model';
+
+@Injectable({ providedIn: 'root' })
+export class CounterService implements ICounterService {
+  counter = 0;
+  count() {
+    this.counter++;
+  }
+}

package/src/hooks/service/service-hook-codex-sample.module.ts

@@ -0,0 +1,13 @@
+import { NgModule } from '@angular/core';
+import { ServiceHookModule } from './client/service-hook.module';
+import { CounterHookModule } from './counter/counter.module';
+
+@NgModule({
+  imports: [ServiceHookModule, CounterHookModule]
+})
+/**
+ * `codex-tutorial-example` component supports a single module only, hence the module providing the service (CounterHookModule)
+ * and the one consuming the service (ServiceHookModule) need to be combined in a single module.
+ * In the general case, both modules above can be added as remotes separately.
+ */
+export class ServiceHookCodexSampleModule {}

package/src/properties-list/properties-list-example.component.html

@@ -19,4 +19,14 @@
     [properties]="specifiedPackageVersionProperties"
   ></c8y-properties-list>
   <!-- /important -->
+
+  <!-- important -->
+  <c8y-properties-list
+    [title]="'Properties with no parse enabled'"
+    [data]="[]"
+    [emptyLabel]="'--'"
+    [noParse]="true"
+    [properties]="customPropertiesNoParse"
+  ></c8y-properties-list>
+  <!-- /important -->
 </div>

package/src/properties-list/properties-list-example.component.ts

@@ -94,4 +94,25 @@ export class PropertiesListExampleComponent {
       key: 'custom'
     }
   ];
+
+  readonly customPropertiesNoParse: PropertiesListItem[] = [
+    {
+      label: 'String property',
+      key: 'string',
+      value: this.customData.string,
+      type: 'string'
+    },
+    {
+      label: 'Number property',
+      key: 'number',
+      value: this.customData.number,
+      type: 'string'
+    },
+    {
+      label: 'Array property',
+      key: 'array',
+      value: this.customData.array,
+      type: 'array'
+    }
+  ];
 }