@c8y/tutorial 1021.4.3 → 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.4.3",
+  "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.4.3",
-    "@c8y/ngx-components": "1021.4.3",
-    "@c8y/client": "1021.4.3",
-    "@c8y/bootstrap": "1021.4.3",
+    "@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.4.3",
-    "@c8y/devkit": "1021.4.3"
+    "@c8y/options": "1021.6.0",
+    "@c8y/devkit": "1021.6.0"
   },
   "peerDependencies": {
     "@angular/common": ">=18 <19"

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'
+    }
+  ];
 }