@c8y/tutorial 1019.0.3

package/src/grids/server-grid-example/server-grid-example.component.html

@@ -0,0 +1,26 @@
+<c8y-title>Data grid examples</c8y-title>
+
+<c8y-data-grid
+  [title]="title"
+  [loadMoreItemsLabel]="loadMoreItemsLabel"
+  [loadingItemsLabel]="loadingItemsLabel"
+  [displayOptions]="displayOptions"
+  [columns]="columns"
+  [pagination]="pagination"
+  [infiniteScroll]="infiniteScroll"
+  [serverSideDataCallback]="serverSideDataCallback"
+  [refresh]="refresh"
+  (rowClick)="onRowClick($event)"
+  [actionControls]="actionControls"
+  [selectable]="selectable"
+  (itemsSelect)="onItemsSelect($event)"
+  [bulkActionControls]="bulkActionControls"
+  (onConfigChange)="onConfigChange($event)"
+>
+  <c8y-ui-empty-state
+    [icon]="'search'"
+    [title]="'No results to display.' | translate"
+    [subtitle]="'Refine your search terms or check your spelling.' | translate"
+    [horizontal]="true"
+  ></c8y-ui-empty-state>
+</c8y-data-grid>

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

@@ -0,0 +1,121 @@
+import { Component, EventEmitter } from '@angular/core';
+import { RouterModule } from '@angular/router';
+
+import {
+  ActionControl,
+  BulkActionControl,
+  Column,
+  Pagination,
+  GridConfig,
+  LoadMoreMode,
+  DataSourceModifier,
+  ServerSideDataResult,
+  Row,
+  DisplayOptions,
+  CoreModule
+} from '@c8y/ngx-components';
+import { DeviceGridModule } from '@c8y/ngx-components/device-grid';
+import { ServerGridExampleService } from './server-grid-example.service';
+import { TypeCellRendererComponent } from './type-data-grid-column/type.cell-renderer.component';
+import { TypeFilteringFormRendererComponent } from './type-data-grid-column/type.filtering-form-renderer.component';
+import { TypeHeaderCellRendererComponent } from './type-data-grid-column/type.header-cell-renderer.component';
+
+/**
+ * This is an example of using DataGridComponent for displaying, filtering and sorting managed objects
+ * using customized columns and dynamically built inventory queries.
+ */
+@Component({
+  selector: 'c8y-server-grid-example',
+  templateUrl: './server-grid-example.component.html',
+  standalone: true,
+  imports: [
+    CoreModule,
+    DeviceGridModule,
+    RouterModule,
+    TypeCellRendererComponent,
+    TypeFilteringFormRendererComponent,
+    TypeHeaderCellRendererComponent
+  ],
+  providers: [ServerGridExampleService]
+})
+export class ServerGridExampleComponent {
+  title = 'Managed objects';
+  loadMoreItemsLabel = 'Load more managed objects';
+  loadingItemsLabel = 'Loading managed objects…';
+
+  displayOptions: DisplayOptions = {
+    bordered: true,
+    striped: true,
+    filter: true,
+    gridHeader: true
+  };
+
+  columns: Column[] = this.service.getColumns();
+  pagination: Pagination = this.service.getPagination();
+  infiniteScroll: LoadMoreMode = 'auto';
+  serverSideDataCallback: any;
+
+  refresh: EventEmitter<any> = new EventEmitter<any>();
+
+  selectable = true;
+  actionControls: ActionControl[] = this.service.getActionControls();
+  bulkActionControls: BulkActionControl[] = this.service.getBulkActionControls();
+
+  constructor(private service: ServerGridExampleService) {
+    // we're setting up `serverSideDataCallback` to execute a method from this component with bound `this`
+    this.serverSideDataCallback = this.onDataSourceModifier.bind(this);
+    // we're setting up `onRefreshClick` to be executed on refresh event
+    this.refresh.subscribe(() => this.onRefreshClick());
+  }
+
+  /** Used in ngFor for columns iteration. */
+  trackByName(_index, column: Column): string {
+    return column.name;
+  }
+
+  /**
+   * 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:
+   * 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> {
+    const { res, data, paging } = await this.service.getData(
+      dataSourceModifier.columns,
+      dataSourceModifier.pagination
+    );
+    const filteredSize: number = await this.service.getCount(
+      dataSourceModifier.columns,
+      dataSourceModifier.pagination
+    );
+    const size: number = await this.service.getTotal();
+
+    const serverSideDataResult: ServerSideDataResult = { res, data, paging, filteredSize, size };
+
+    return serverSideDataResult;
+  }
+
+  /** Executes an action on row click. */
+  onRowClick(row: Row) {
+    console.log('row clicked:');
+    console.dir(row);
+  }
+
+  /** Executes an action on the selected items. */
+  onItemsSelect(selectedItemIds: string[]) {
+    console.log('selected item ids:');
+    console.dir(selectedItemIds);
+  }
+
+  /** Executes an action on grid config change. */
+  onConfigChange(gridConfig: GridConfig) {
+    console.log('grid config changed:');
+    console.dir(gridConfig);
+  }
+
+  /** Executes an action on refresh event. */
+  onRefreshClick() {
+    console.log('refresh clicked');
+  }
+}

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

@@ -0,0 +1,24 @@
+import { NgModule } from '@angular/core';
+import { CommonModule } from '@angular/common';
+import { NavigatorNode, hookNavigator, hookRoute } from '@c8y/ngx-components';
+
+@NgModule({
+  imports: [CommonModule],
+  providers: [
+    hookRoute({
+      path: 'grids/server-grid-example',
+      loadComponent: () =>
+        import('./server-grid-example.component').then(m => m.ServerGridExampleComponent)
+    }),
+    hookNavigator(
+      new NavigatorNode({
+        priority: 20,
+        path: 'grids/server-grid-example',
+        icon: 'table',
+        label: 'Server grid',
+        parent: 'Data grid examples'
+      })
+    )
+  ]
+})
+export class ServerGridExampleModule {}

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

@@ -0,0 +1,266 @@
+import { Injectable } from '@angular/core';
+import { transform } from 'lodash-es';
+
+import { IManagedObject, InventoryService, QueriesUtil } from '@c8y/client';
+import {
+  ActionControl,
+  BuiltInActionType,
+  BulkActionControl,
+  Column,
+  Pagination
+} from '@c8y/ngx-components';
+
+import { TypeDataGridColumn } from './type-data-grid-column/type.data-grid-column';
+
+/** Model for custom type filtering form. */
+export interface TypeFilteringModel {
+  group?: boolean;
+  device?: boolean;
+  smartRule?: boolean;
+  dashboard?: boolean;
+  file?: boolean;
+  application?: boolean;
+}
+
+/**
+ * This is the example service for a data grid:
+ * provides the list of columns, initial pagination object, actions;
+ * as well as performs the query for data based on the current grid setup.
+ */
+@Injectable()
+export class ServerGridExampleService {
+  /** This will be used to build the inventory queries. */
+  protected queriesUtil: QueriesUtil;
+
+  constructor(protected inventoryService: InventoryService) {
+    this.queriesUtil = new QueriesUtil();
+  }
+
+  /**
+   * Returns a list of columns.
+   * We define 2 columns with inline objects (they display simple properties
+   * and use default header, cell and filtring form).
+   * The last column is defined via a class instance (it displays a value based on
+   * several properties of the row item and has custom header, cell and filtering form).
+   */
+  getColumns(): Column[] {
+    const columns = [
+      {
+        name: 'id',
+        header: 'ID',
+        path: 'id',
+        filterable: true,
+        sortable: true
+      },
+      {
+        name: 'name',
+        header: 'Name',
+        path: 'name',
+        filterable: true,
+        sortable: true
+      },
+      new TypeDataGridColumn()
+    ];
+
+    return columns;
+  }
+
+  /** Returns initial pagination object. */
+  getPagination(): Pagination {
+    return {
+      pageSize: 10,
+      currentPage: 1
+    };
+  }
+
+  /** Returns an array of individual row actions. */
+  getActionControls(): ActionControl[] {
+    return [
+      { type: BuiltInActionType.Edit, callback: item => console.dir(item) },
+      { type: BuiltInActionType.Export, callback: item => console.dir(item) },
+      { type: BuiltInActionType.Delete, callback: item => console.dir(item) },
+      {
+        type: 'customAction',
+        icon: 'online',
+        text: 'Custom action',
+        callback: item => console.dir(item)
+      }
+    ];
+  }
+
+  /** Returns an array of bulk row actions. */
+  getBulkActionControls(): BulkActionControl[] {
+    return [
+      {
+        type: BuiltInActionType.Export,
+        callback: selectedItemIds => console.dir(selectedItemIds)
+      },
+      {
+        type: BuiltInActionType.Delete,
+        callback: selectedItemIds => console.dir(selectedItemIds)
+      },
+      {
+        type: 'customAction',
+        icon: 'online',
+        text: 'Custom action',
+        callback: selectedItemIds => console.dir(selectedItemIds)
+      }
+    ];
+  }
+
+  /** Returns data for current columns and pagination setup. */
+  async getData(columns: Column[], pagination: Pagination) {
+    // build filters based on columns and pagination
+    const filters = this.getFilters(columns, pagination);
+    // execute inventory query for the list of managed objects
+    return this.inventoryService.list(filters);
+  }
+
+  /** Returns the number of items matching current columns and pagination setup. */
+  async getCount(columns: Column[], pagination: Pagination) {
+    const filters = {
+      // build filters based on columns and pagination
+      ...this.getFilters(columns, pagination),
+      // but we only need the number of items, not the items themselves
+      pageSize: 1,
+      currentPage: 1
+    };
+    return (await this.inventoryService.list(filters)).paging.totalPages;
+  }
+
+  /** Returns the total number of items (with no filters). */
+  async getTotal(): Promise<number> {
+    const filters = {
+      pageSize: 1,
+      withTotalPages: true
+    };
+    return (await this.inventoryService.list(filters)).paging.totalPages;
+  }
+
+  /** Returns an icon and label representing the type of the managed object. */
+  getTypeIconAndLabel(mo: IManagedObject): { icon: string; label: string } {
+    let icon = 'question';
+    let label = 'Other';
+
+    if (mo.type === 'c8y_DeviceGroup') {
+      icon = 'c8y-group';
+      label = 'Group';
+    }
+
+    if (mo.c8y_IsDevice !== undefined) {
+      icon = 'exchange';
+      label = 'Device';
+    }
+
+    if (mo.type === 'c8y_SmartRule' || mo.type === 'c8y_PrivateSmartRule') {
+      icon = 'c8y-smart-rules';
+      label = 'Smart rule';
+    }
+
+    if (mo.c8y_Dashboard !== undefined) {
+      icon = 'th';
+      label = 'Dashboard';
+    }
+
+    if (mo.c8y_IsBinary !== undefined) {
+      icon = 'file';
+      label = 'File';
+    }
+
+    if (mo.type && mo.type.startsWith('c8y_Application')) {
+      icon = 'c8y-atom';
+      label = 'Application';
+    }
+
+    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 {
+      query: this.getQueryString(columns),
+      pageSize: pagination.pageSize,
+      currentPage: pagination.currentPage,
+      withChildren: false,
+      withTotalPages: true
+    };
+  }
+
+  /** Returns a query string based on columns setup. */
+  private getQueryString(columns: Column[]): string {
+    const fullQuery = this.getQueryObj(columns);
+    return this.queriesUtil.buildQuery(fullQuery);
+  }
+
+  /** Returns a query object based on columns setup. */
+  private getQueryObj(columns: Column[]): any {
+    return transform(columns, (query, column) => this.addColumnQuery(query, column), {
+      __filter: {},
+      __orderby: []
+    });
+  }
+
+  /** Extends given query with a part based on the setup of given column. */
+  private addColumnQuery(query: any, column: Column): void {
+    // when a column is marked as filterable
+    if (column.filterable) {
+      // in the case of default filtering form, `filterPredicate` will contain the string entered by a user
+      if (column.filterPredicate) {
+        // so we use it as the expected value, * allow to search for it anywhere in the property
+        query.__filter[column.path] = `*${column.filterPredicate}*`;
+      }
+
+      // 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);
+      }
+    }
+
+    // when a column is sortable and has a specified sorting order
+    if (column.sortable && column.sortOrder) {
+      // add sorting condition for the configured column `path`
+      query.__orderby.push({
+        [column.path]: column.sortOrder === 'asc' ? 1 : -1
+      });
+    }
+
+    return query;
+  }
+}

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

@@ -0,0 +1,31 @@
+import { Component, Inject } from '@angular/core';
+import { CellRendererContext, CoreModule } from '@c8y/ngx-components';
+import { ServerGridExampleService } from '../server-grid-example.service';
+
+/**
+ * The example component for custom cell renderer.
+ * It gets `context` with the current row item and the column.
+ * Additionally, a service is injected to provide a helper method.
+ * The template displays the icon and the label with additional styling.
+ */
+@Component({
+  template: `
+    <span>
+      <i class="m-r-5" [c8yIcon]="value.icon"></i>
+      <code>{{ value.label }}</code>
+    </span>
+  `,
+  standalone: true,
+  imports: [CoreModule]
+})
+export class TypeCellRendererComponent {
+  /** Returns the icon and label for the current item. */
+  get value() {
+    return this.service.getTypeIconAndLabel(this.context.item);
+  }
+
+  constructor(
+    public context: CellRendererContext,
+    @Inject(ServerGridExampleService) public service: ServerGridExampleService
+  ) {}
+}

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

@@ -0,0 +1,47 @@
+import { Type } from '@angular/core';
+import { Column, ColumnDataType, SortOrder, FilterPredicateFunction } from '@c8y/ngx-components';
+import { TypeHeaderCellRendererComponent } from './type.header-cell-renderer.component';
+import { TypeCellRendererComponent } from './type.cell-renderer.component';
+import { TypeFilteringFormRendererComponent } from './type.filtering-form-renderer.component';
+
+/**
+ * Defines a class for custom Type column.
+ * Implements `Column` interface and sets basic properties, as well as custom components.
+ */
+export class TypeDataGridColumn implements Column {
+  name: string;
+  path?: string;
+  header?: string;
+  dataType?: ColumnDataType;
+
+  visible?: boolean;
+  positionFixed?: boolean;
+  gridTrackSize?: string;
+
+  headerCSSClassName?: string | string[];
+  headerCellRendererComponent?: Type<any>;
+
+  cellCSSClassName?: string | string[];
+  cellRendererComponent?: Type<any>;
+
+  sortable?: boolean;
+  sortOrder?: SortOrder;
+
+  filterable?: boolean;
+  filteringFormRendererComponent?: Type<any>;
+  filterPredicate?: string | FilterPredicateFunction;
+  externalFilterQuery?: string | object;
+
+  constructor() {
+    this.name = 'type';
+    this.header = 'Type';
+
+    this.headerCellRendererComponent = TypeHeaderCellRendererComponent;
+    this.cellRendererComponent = TypeCellRendererComponent;
+
+    this.filterable = true;
+    this.filteringFormRendererComponent = TypeFilteringFormRendererComponent;
+
+    this.sortable = false;
+  }
+}

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

@@ -0,0 +1,107 @@
+import { Component, Inject } from '@angular/core';
+import { FilteringFormRendererContext, FormsModule } from '@c8y/ngx-components';
+import { ServerGridExampleService, TypeFilteringModel } from '../server-grid-example.service';
+
+/**
+ * This is the example component for custom filtering form.
+ * The form can contain any inputs you want.
+ * The important thing is to invoke one of the 2 methods:
+ *
+ * - `applyFilter` which sets `filterPredicate` or `externalFilterQuery` in the column,
+ *   these values will later be used to generate the query
+ * - `resetFilter` which resets filter settings in the column
+ *
+ * Our example shows the list of checkboxes. Selecting them modifies the query being sent.
+ */
+@Component({
+  template: `
+    <form #filterForm="ngForm">
+      <strong>Show managed objects of type:</strong>
+      <c8y-form-group class="m-b-0">
+        <label class="c8y-checkbox">
+          <input name="group" type="checkbox" [(ngModel)]="model.group" />
+          <span></span>
+          <span>Group</span>
+        </label>
+      </c8y-form-group>
+      <c8y-form-group class="m-b-0">
+        <label class="c8y-checkbox">
+          <input name="device" type="checkbox" [(ngModel)]="model.device" />
+          <span></span>
+          <span>Device</span>
+        </label>
+      </c8y-form-group>
+      <c8y-form-group class="m-b-0">
+        <label class="c8y-checkbox">
+          <input name="dashboard" type="checkbox" [(ngModel)]="model.dashboard" />
+          <span></span>
+          <span>Dashboard</span>
+        </label>
+      </c8y-form-group>
+      <c8y-form-group class="m-b-0">
+        <label class="c8y-checkbox">
+          <input name="smartRule" type="checkbox" [(ngModel)]="model.smartRule" />
+          <span></span>
+          <span>Smart rule</span>
+        </label>
+      </c8y-form-group>
+      <c8y-form-group class="m-b-0">
+        <label class="c8y-checkbox">
+          <input name="file" type="checkbox" [(ngModel)]="model.file" />
+          <span></span>
+          <span>File</span>
+        </label>
+      </c8y-form-group>
+      <c8y-form-group class="m-b-0">
+        <label class="c8y-checkbox">
+          <input name="application" type="checkbox" [(ngModel)]="model.application" />
+          <span></span>
+          <span>Application</span>
+        </label>
+      </c8y-form-group>
+    </form>
+
+    <div class="data-grid__dropdown__footer d-flex separator-top">
+      <button class="btn btn-default btn-sm m-r-8 flex-grow" (click)="resetFilter()">Reset</button>
+      <button
+        class="btn btn-primary btn-sm flex-grow"
+        [disabled]="filterForm.invalid"
+        (click)="applyFilter()"
+      >
+        Apply
+      </button>
+    </div>
+  `,
+  standalone: true,
+  imports: [FormsModule]
+})
+export class TypeFilteringFormRendererComponent {
+  model: TypeFilteringModel;
+
+  constructor(
+    public context: FilteringFormRendererContext,
+    @Inject(ServerGridExampleService) public service: ServerGridExampleService
+  ) {
+    // restores the settings from current column setup
+    this.model = (this.context.property.externalFilterQuery || {}).model || {};
+  }
+
+  /**
+   * Applies the filter.
+   * Sets `externalFilterQuery.model` to restore the same settings the next time the form is displayed.
+   * Sets `externalFilterQuery.query` to pass the query object to be included in the final data grid query.
+   */
+  applyFilter() {
+    this.context.applyFilter({
+      externalFilterQuery: {
+        model: this.model,
+        query: this.service.getTypeQuery(this.model)
+      }
+    });
+  }
+
+  /** Restes the filter, just call the method from context. */
+  resetFilter() {
+    this.context.resetFilter();
+  }
+}

package/src/grids/server-grid-example/type-data-grid-column/type.header-cell-renderer.component.ts

@@ -0,0 +1,20 @@
+import { Component } from '@angular/core';
+import { CellRendererContext } from '@c8y/ngx-components';
+
+/**
+ * The example component for custom header renderer.
+ * The header text is taken from `this.context.property` which contains current column object.
+ * Additionally the header has custom icon element and styled span element.
+ */
+@Component({
+  template: `
+    <i c8yIcon="rocket"></i>
+    <span style="text-transform: uppercase; font-variant: small-caps; text-decoration: underline;">
+      {{ context.property.header }}
+    </span>
+  `,
+  standalone: true
+})
+export class TypeHeaderCellRendererComponent {
+  constructor(public context: CellRendererContext) {}
+}