@c8y/tutorial 1022.4.17 → 1022.6.1

package/cumulocity.config.ts

@@ -213,6 +213,13 @@ export default {
         description: 'A sample for action bar hook.',
         scope: 'self'
       },
+      {
+        name: 'Preview feature',
+        module: 'PreviewFeatureModule',
+        path: './src/hooks/preview-feature/preview-feature.module.ts',
+        description: 'A sample for feature preview hook.',
+        scope: 'self'
+      },
       {
         name: 'Breadcrumbs hook',
         module: 'BreadcrumbsModule',

package/package.json

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

package/src/__mocks/global-mocks/feature-api.ts

@@ -0,0 +1,55 @@
+import { IFetchResponse } from '@c8y/client';
+import { ApiCall, HttpHandler, HttpInterceptor } from '@c8y/ngx-components/api';
+import { handleRequest } from '../utils/common';
+import { Observable } from 'rxjs';
+
+const LOCAL_STORAGE_KEY = 'previewFeatureState';
+
+export class FeatureApiInterceptor implements HttpInterceptor {
+  features = [
+    {
+      active: localStorage.getItem(LOCAL_STORAGE_KEY),
+      phase: 'PUBLIC_PREVIEW',
+      key: 'preview-feature-key',
+      strategy: 'TENANT'
+    }
+  ];
+
+  intercept(req: ApiCall, next: HttpHandler): Observable<IFetchResponse> {
+    return handleRequest(req, next, '/features', {
+      POST: this.mockPOST.bind(this),
+      PUT: this.mockPUT.bind(this),
+      GET: this.mockGET.bind(this)
+    });
+  }
+
+  mockPOST(_requestDescriptor: string) {
+    return null;
+  }
+
+  mockPUT(requestDescriptor: string) {
+    const match = requestDescriptor.match(/\/features\/([^/]+)\/by-tenant/);
+    if (match) {
+      const key = match[1];
+      const bodyStartIndex = requestDescriptor.indexOf('{');
+      const body = bodyStartIndex !== -1 ? JSON.parse(requestDescriptor.slice(bodyStartIndex)) : {};
+      const feature = this.features.find(f => f.key === key);
+      if (feature) {
+        feature.active = body.active;
+        localStorage.setItem(LOCAL_STORAGE_KEY, String(body.active));
+      }
+    }
+
+    return {
+      status: 200,
+      json: async () => this.features
+    };
+  }
+
+  private async mockGET(_requestDescriptor: string) {
+    return {
+      status: 200,
+      json: async () => this.features
+    };
+  }
+}

package/src/__mocks/index.ts

@@ -2,7 +2,12 @@ export * from './mock.service';
 export * from './mock.model';
 export * from './mock.realtime';
 export * from './mock.realtime-subject';
-import { AppStateService, OptionsService, RealtimeSubjectService } from '@c8y/ngx-components';
+import {
+  AppStateService,
+  OptionsService,
+  Permissions,
+  RealtimeSubjectService
+} from '@c8y/ngx-components';
 import { InventoryInterceptor } from './global-mocks/inventory.interceptor';
 import { MeasurementsInterceptor } from './global-mocks/measurements.interceptor';
 import { API_MOCK_CONFIG, ApiMockConfig } from './mock.model';
@@ -18,6 +23,7 @@ import { MeasurementsSeriesInterceptor } from './scoped-mocks/measurement-series
 import { EnvironmentProviders, Provider, inject, provideAppInitializer } from '@angular/core';
 import { MockService } from './mock.service';
 import { IUser } from '@c8y/client';
+import { FeatureApiInterceptor } from './global-mocks/feature-api';
 
 export function provideAPIMock() {
   return [
@@ -146,6 +152,15 @@ export function provideAPIMock() {
       } as ApiMockConfig,
       multi: true
     },
+    {
+      provide: API_MOCK_CONFIG,
+      useValue: {
+        // The interceptors are sorted by their ID, so the scoped interceptors should be before the global ones.
+        id: 'z-global-feature-preview-interceptor-interceptor',
+        mockService: FeatureApiInterceptor
+      } as ApiMockConfig,
+      multi: true
+    },
     {
       provide: RealtimeSubjectService,
       useExisting: RealtimeSubjectServiceWithMocking
@@ -161,7 +176,16 @@ export function provideAPIMock() {
             appStateService.currentUser.next({
               id: 'NO_LOGIN',
               userName: 'noLogin',
-              displayName: 'noLogin'
+              displayName: 'noLogin',
+              roles: {
+                references: [
+                  {
+                    role: {
+                      id: Permissions.ROLE_TENANT_MANAGEMENT_ADMIN
+                    }
+                  }
+                ] as any
+              }
             } as IUser);
           }
         };

package/src/grids/tree-grid-example/server-tree-grid-example.component.ts

@@ -20,8 +20,7 @@ import { DeviceGridModule } from '@c8y/ngx-components/device-grid';
 import { ServerTreeGridExampleService } from './server-tree-grid-example.service';
 
 /**
- * This is an example of using DataGridComponent for displaying, filtering and sorting managed objects
- * using customized columns and dynamically built inventory queries.
+ * This is an example of using DataGridComponent as a tree grid for displaying hierarchical data.
  */
 @Component({
   selector: 'c8y-server-tree-grid-example',
@@ -73,7 +72,7 @@ export class ServerTreeGridExampleComponent implements GridConfigContextProvider
        * You can provide data here that can be used for grid configration storage,
        * action control matchers, etc.
        */
-      key: 'server-grid-example'
+      key: 'server-tree-grid-example'
     };
   }
 
@@ -83,13 +82,14 @@ export class ServerTreeGridExampleComponent implements GridConfigContextProvider
   }
 
   /**
-   * This method loads data when data grid requests it (e.g. on initial load or on column settings change).
-   * It gets the object with current data grid setup and is supposed to return:
+   * This method loads data when data grid requests it (e.g. on initial load or when a row with child entries is expanded).
+   * It receives the `DataSourceModifier` context with current data grid setup and is supposed to return:
    * full response, list of items, paging object, the number of items in the filtered subset, the number of all items.
    */
   async onDataSourceModifier(
     dataSourceModifier: DataSourceModifier
   ): Promise<ServerSideDataResult> {
+    // If the `DataSourceModifier` context object has a `parentRow`, it means we are loading child nodes for a specific parent row.
     const { parentRow } = dataSourceModifier;
     if (parentRow) {
       const { res, data, paging } = await this.service.getChildDevices(
@@ -98,6 +98,8 @@ export class ServerTreeGridExampleComponent implements GridConfigContextProvider
       );
 
       data.forEach(row => {
+        // The `hasChildren` property should be set for each row to indicate if it has child entries.
+        // This is used by the grid to display expand/collapse icons.
         row.hasChildren = row.childDevices.count > 0;
       });
 

package/src/hooks/preview-feature/basic-view-custom/basic-view-custom.component.html

@@ -0,0 +1,11 @@
+<c8y-title>Custom hook preview</c8y-title>
+<div class="card">
+  <div class="card-block">
+    <p>
+      This is an example component of a feature which can be activated in "Manage preview features"
+      because it was registered with
+      <code>hookPreview</code>
+      with custom content.
+    </p>
+  </div>
+</div>

package/src/hooks/preview-feature/basic-view-custom/basic-view-custom.component.ts

@@ -0,0 +1,18 @@
+import { Component } from '@angular/core';
+import { CoreModule } from '@c8y/ngx-components';
+
+/**
+ * This is a standard angular component.
+ * Obviously it does not do anything.
+ */
+@Component({
+  selector: 'tut-custom-basic-preview-feature-view',
+  templateUrl: './basic-view-custom.component.html',
+  standalone: true,
+  imports: [CoreModule]
+})
+export class CustomBasicViewComponent {
+  /**
+   * Your content of the Basic View goes in here!
+   */
+}

package/src/hooks/preview-feature/basic-view-custom/preview-feature-custom.factory.ts

@@ -0,0 +1,31 @@
+import { inject, Injectable } from '@angular/core';
+import { NavigatorNode, NavigatorNodeFactory, PreviewService } from '@c8y/ngx-components';
+import { distinctUntilChanged, map, Observable } from 'rxjs';
+
+@Injectable()
+export class ExampleCustomPreviewFeatureNavigationFactory implements NavigatorNodeFactory {
+  private readonly previewFeatureService = inject(PreviewService);
+
+  get(): Observable<NavigatorNode[]> {
+    // For custom features we provide the label as they have no key
+    const customFeatureLabel = 'Custom feature preview';
+    return this.previewFeatureService.getState$(customFeatureLabel).pipe(
+      distinctUntilChanged(),
+      map(state => {
+        if (state) {
+          return [
+            new NavigatorNode({
+              priority: 100,
+              path: 'hooks/preview-feature-custom',
+              icon: 'science',
+              label: 'Feature Preview Custom',
+              parent: 'Hooks',
+              preventDuplicates: true
+            })
+          ];
+        }
+        return [];
+      })
+    );
+  }
+}

package/src/hooks/preview-feature/basic-view-custom/preview-feature-custom.module.ts

@@ -0,0 +1,45 @@
+import { NgModule } from '@angular/core';
+import { hookNavigator, hookPreview, hookRoute } from '@c8y/ngx-components';
+import { BehaviorSubject } from 'rxjs';
+import { ExampleCustomPreviewFeatureNavigationFactory } from './preview-feature-custom.factory';
+
+// needed only for the example, we will store the state in local storage
+const LOCAL_STORAGE_KEY = 'customPreviewFeatureState';
+const savedState = localStorage.getItem(LOCAL_STORAGE_KEY) === 'true';
+const customPreviewFeatureState$ = new BehaviorSubject<boolean>(savedState);
+
+/**
+ * Use our predefined InjectionTokens and provide your own classes to extend behavior
+ * and functionality of existing ones. Implement your own NavigationNodes, Tabs, Actions and Breadcrumbs.
+ * Note: Hooks should always be implemented in the module where they are used, so that
+ * a module can act standalone and has no dependencies on other modules.
+ */
+export const customHooks = [
+  hookRoute({
+    path: 'hooks/preview-feature-custom',
+    loadComponent: () =>
+      import('./basic-view-custom.component').then(m => m.CustomBasicViewComponent)
+  }),
+  hookNavigator(ExampleCustomPreviewFeatureNavigationFactory),
+  hookPreview({
+    active$: customPreviewFeatureState$.asObservable(),
+    onToggle: async (state: boolean) => {
+      localStorage.setItem(LOCAL_STORAGE_KEY, String(state));
+      customPreviewFeatureState$.next(state);
+      return true;
+    },
+    label: 'Custom feature preview',
+    description: () => Promise.resolve('This is a custom feature'),
+    settings: {
+      reload: true
+    }
+  })
+];
+
+@NgModule({
+  /**
+   * Adding the hooks to the providers:
+   */
+  providers: [...customHooks]
+})
+export class PreviewFeatureCustomModule {}

package/src/hooks/preview-feature/basic-view-default/basic-view-default.component.html

@@ -0,0 +1,11 @@
+<c8y-title>Hook Preview</c8y-title>
+<div class="card">
+  <div class="card-block">
+    <p>
+      This is an example component of a feature which can be activated in "Manage preview features"
+      because it was registered with
+      <code>hookPreview</code>
+      .
+    </p>
+  </div>
+</div>

package/src/hooks/preview-feature/basic-view-default/basic-view-default.component.ts

@@ -0,0 +1,18 @@
+import { Component } from '@angular/core';
+import { CoreModule } from '@c8y/ngx-components';
+
+/**
+ * This is a standard angular component.
+ * Obviously it does not do anything.
+ */
+@Component({
+  selector: 'tut-basic-preview-feature-view',
+  templateUrl: './basic-view-default.component.html',
+  standalone: true,
+  imports: [CoreModule]
+})
+export class BasicViewComponent {
+  /**
+   * Your content of the Basic View goes in here!
+   */
+}

package/src/hooks/preview-feature/basic-view-default/preview-feature-default.module.ts

@@ -0,0 +1,34 @@
+import { NgModule } from '@angular/core';
+import { hookNavigator, hookPreview, hookRoute } from '@c8y/ngx-components';
+import { ExamplePreviewFeatureNavigationFactory } from './preview-feature.factory';
+
+/**
+ * Use our predefined InjectionTokens and provide your own classes to extend behavior
+ * and functionality of existing ones. Implement your own NavigationNodes, Tabs, Actions and Breadcrumbs.
+ * Note: Hooks should always be implemented in the module where they are used, so that
+ * a module can act standalone and has no dependencies on other modules.
+ */
+export const hooks = [
+  hookRoute({
+    path: 'hooks/preview-feature-default',
+    loadComponent: () => import('./basic-view-default.component').then(m => m.BasicViewComponent)
+  }),
+  hookNavigator(ExamplePreviewFeatureNavigationFactory),
+  hookPreview({
+    key: 'preview-feature-key',
+    label: 'Example preview feature relying on feature toggles API',
+    description: () =>
+      import('@c8y/style/markdown-files/codex-example-markdown.md').then(m => m.default),
+    settings: {
+      reload: true
+    }
+  })
+];
+
+@NgModule({
+  /**
+   * Adding the hooks to the providers:
+   */
+  providers: [...hooks]
+})
+export class PreviewFeatureDefaultModule {}

package/src/hooks/preview-feature/basic-view-default/preview-feature.factory.ts

@@ -0,0 +1,29 @@
+import { inject, Injectable } from '@angular/core';
+import { NavigatorNode, NavigatorNodeFactory, PreviewService } from '@c8y/ngx-components';
+import { distinctUntilChanged, map, Observable } from 'rxjs';
+
+@Injectable()
+export class ExamplePreviewFeatureNavigationFactory implements NavigatorNodeFactory {
+  private readonly previewFeatureService = inject(PreviewService);
+
+  get(): Observable<NavigatorNode[]> {
+    return this.previewFeatureService.getState$('preview-feature-key').pipe(
+      distinctUntilChanged(),
+      map(state => {
+        if (state) {
+          return [
+            new NavigatorNode({
+              priority: 100,
+              path: 'hooks/preview-feature-default',
+              icon: 'science',
+              label: 'Preview Feature',
+              parent: 'Hooks',
+              preventDuplicates: true
+            })
+          ];
+        }
+        return [];
+      })
+    );
+  }
+}

package/src/hooks/preview-feature/index.ts

@@ -0,0 +1,3 @@
+export * from './preview-feature.module';
+export * from './basic-view-custom/preview-feature-custom.module';
+export * from './basic-view-default/preview-feature-default.module';

package/src/hooks/preview-feature/preview-feature.module.ts

@@ -0,0 +1,11 @@
+import { NgModule } from '@angular/core';
+import { PreviewFeatureCustomModule } from './basic-view-custom/preview-feature-custom.module';
+import { PreviewFeatureDefaultModule } from './basic-view-default/preview-feature-default.module';
+
+/**
+ * This module combines both PreviewFeatureDefaultModule and PreviewFeatureCustomModule.
+ */
+@NgModule({
+  imports: [PreviewFeatureDefaultModule, PreviewFeatureCustomModule]
+})
+export class PreviewFeatureModule {}