@c8y/sample-plugin 1022.3.2

package/.browserslistrc

@@ -0,0 +1,16 @@
+# This file is used by the build system to adjust CSS and JS output to support the specified browsers below.
+# For additional information regarding the format and rule options, please see:
+# https://github.com/browserslist/browserslist#queries
+
+# For the full list of supported browsers by the Angular framework, please see:
+# https://angular.io/guide/browser-support
+
+# You can see what browsers were selected by your queries by running:
+#   npx browserslist
+
+last 2 Chrome versions
+last 1 Firefox version
+last 2 Edge major versions
+last 2 Safari major versions
+last 2 iOS major versions
+Firefox ESR

package/CHANGELOG.md

@@ -0,0 +1,5 @@
+## Change log
+
+If you want a change log to be provided to you package, place the `CHANGELOG.md` file in the root folder of your package.
+
+Examples and best practices of how the change log should be formatted can be found at the [Keep a Changelog](https://keepachangelog.com) website.

package/README.md

@@ -0,0 +1,36 @@
+# Cumulocity sample plugin
+
+This is the Cumulocity module federation plugin. Plugins can be developed like any Cumulocity application, but can be used at runtime by other applications. Therefore, they export an Angular module which can then be imported by any other application. The exports are defined in `cumulocity.config.ts`:
+
+```json
+"exports": [
+  {
+     "name": "Example sample plugin widget",
+     "module": "samplePluginWidgetProviders",
+     "path": "./src/app/index.ts",
+     "description": "Adds a custom widget to the shell application"
+  }
+]
+```
+Once the application has been built, the exports are also defined in the `cumulocity.json` file.
+
+**How to start**
+Run the commands below to scaffold a `sample-plugin`.
+
+```bash
+npx @angular/cli@v19-lts new --style=less # Install the correct version of Angular, which should be the same as your application.
+cd <new-application-name>
+ng add @c8y/websdk --application @c8y/sample-plugin
+```
+
+As the app.module is a typical Cumulocity application, any new plugin can be tested via the CLI:
+
+```bash
+ng serve --shell cockpit
+```
+
+In the Module Federation terminology, `sample` plugin is called `remote` and the `cockpit` is called `shell`. Modules provided by this `sample` will be loaded by the `cockpit` application at the runtime. This plugin provides a basic custom widget that can be accessed through the `Add widget` menu and a new view in a left-hand navigator, where you can find links to Codex hooks entries.
+
+> Note that the `--shell` flag creates a proxy to the cockpit application and provides `samplePluginWidgetProviders` as an `remote` via URL options.
+
+Also deploying needs no special handling and can be simply done via `npm run deploy`. As soon as the application has exports it will be uploaded as a plugin.

package/cumulocity.config.ts

@@ -0,0 +1,56 @@
+import type { ConfigurationOptions } from '@c8y/devkit';
+import { author, description, license, name, version } from './package.json';
+
+export default {
+  runTime: {
+    author,
+    description,
+    version,
+    name,
+    contentSecurityPolicy:
+      "base-uri 'none'; default-src 'self' 'unsafe-inline' http: https: ws: wss:; connect-src 'self' http: https: ws: wss:;  script-src 'self' *.bugherd.com *.twitter.com *.twimg.com *.aptrinsic.com 'unsafe-inline' 'unsafe-eval' data:; style-src * 'unsafe-inline' blob:; img-src * data: blob:; font-src * data:; frame-src *; worker-src 'self' blob:;",
+    dynamicOptionsUrl: true,
+    remotes: {
+      [name]: ['samplePluginWidgetProviders']
+    },
+    package: 'plugin',
+    isPackage: true,
+    noAppSwitcher: true,
+    license,
+    exports: [
+      {
+        name: 'Example sample plugin widget',
+        module: 'samplePluginWidgetProviders',
+        path: './src/app/index.ts',
+        readmePath: './src/app/README.md',
+        description: 'Adds a custom widget to the shell application'
+      },
+      {
+        name: 'Example sample plugin view',
+        module: 'samplePluginViewProviders',
+        path: './src/app/index.ts',
+        readmePath: './src/app/README.md',
+        description: 'Adds a custom navigator node to the shell application'
+      }
+    ]
+  },
+  buildTime: {
+    federation: [
+      '@angular/animations',
+      '@angular/cdk',
+      '@angular/common',
+      '@angular/compiler',
+      '@angular/core',
+      '@angular/forms',
+      '@angular/platform-browser',
+      '@angular/platform-browser-dynamic',
+      '@angular/router',
+      '@angular/upgrade',
+      '@c8y/client',
+      '@c8y/ngx-components',
+      'ngx-bootstrap',
+      '@ngx-translate/core',
+      '@ngx-formly/core'
+    ]
+  }
+} as const satisfies ConfigurationOptions;

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@c8y/sample-plugin",
+  "version": "1022.3.2",
+  "description": "",
+  "dependencies": {
+    "@c8y/style": "1022.3.2",
+    "@c8y/ngx-components": "1022.3.2",
+    "@c8y/client": "1022.3.2",
+    "@c8y/bootstrap": "1022.3.2",
+    "@angular/cdk": "^19.2.18",
+    "ngx-bootstrap": "19.0.2",
+    "rxjs": "7.8.1"
+  },
+  "devDependencies": {
+    "@c8y/options": "1022.3.2",
+    "@c8y/devkit": "1022.3.2"
+  },
+  "peerDependencies": {
+    "@angular/common": ">=19 <20"
+  },
+  "author": "Cumulocity GmbH",
+  "license": "Apache-2.0"
+}

package/src/app/README.md

@@ -0,0 +1,26 @@
+# SAMPLE-PLUGIN Readme Example
+
+## Adding a Readme File to Your Plugin
+
+Follow these steps to include a readme file in your plugin:
+
+1. Add the `readmePath` property to the `exports` array in your `cumulocity.config.ts` file.
+2. Place the readme file in the same folder as your `index.ts` file.
+
+### Example
+
+```ts
+exports: [
+  {
+    name: 'Example sample plugin view',
+    module: 'samplePluginWidgetProviders',
+    path: './src/app/index.ts',
+    readmePath: './src/app/README.md',
+    description: 'Adds a custom widget and navigator node to the shell application'
+  }
+];
+```
+
+### What Happens When You Build?
+
+When you build your plugin (e.g., by running `ng build sample-plugin`), the generated zip file will include the readme file. It will be placed in a folder named after your module, such as `SamplePluginModule` or `samplePluginWidgetProviders`.

package/src/app/app.config.ts

@@ -0,0 +1,13 @@
+import { ApplicationConfig, importProvidersFrom } from '@angular/core';
+import { provideAnimations } from '@angular/platform-browser/animations';
+import { CoreModule, RouterModule } from '@c8y/ngx-components';
+import { CockpitDashboardModule } from '@c8y/ngx-components/context-dashboard/cockpit-home-dashboard';
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    provideAnimations(),
+    importProvidersFrom(RouterModule.forRoot()),
+    importProvidersFrom(CoreModule.forRoot()),
+    importProvidersFrom(CockpitDashboardModule)
+  ]
+};

package/src/app/index.ts

@@ -0,0 +1,52 @@
+import {
+  DynamicWidgetDefinition,
+  gettext,
+  hookNavigator,
+  hookRoute,
+  hookWidget,
+  NavigatorNode,
+  NavigatorNodeData
+} from '@c8y/ngx-components';
+import {
+  exportConfigWithDevice,
+  importConfigWithDevice
+} from '@c8y/ngx-components/widgets/import-export-config';
+import { assetPaths } from '../assets/assets';
+import { CODEX_HOOK_LINKS } from './sample-plugin.model';
+import { SamplePluginConfigComponent } from './widget/sample-widget-config.component';
+import { SamplePluginComponent } from './widget/sample-widget.component';
+
+export const samplePluginWidgetDefinition = {
+  id: 'angular.widget.plugin',
+  label: gettext('Module Federation widget'),
+  description: gettext('Sample added via Module Federation'),
+  component: SamplePluginComponent,
+  configComponent: SamplePluginConfigComponent,
+  previewImage: assetPaths.previewImage,
+  data: {
+    schema: () =>
+      import('c8y-schema-loader?interfaceName=SamplePluginConfig!./sample-plugin.model'),
+    export: exportConfigWithDevice,
+    import: importConfigWithDevice,
+    settings: {
+      noNewWidgets: false
+    }
+  }
+} satisfies DynamicWidgetDefinition;
+
+export const samplePluginWidgetProviders = [hookWidget(samplePluginWidgetDefinition)];
+
+export const samplePluginViewProviders = [
+  hookRoute({
+    path: 'codex-hook-links',
+    loadComponent: () => import('./view/sample-view.component').then(m => m.SampleViewComponent)
+  }),
+  hookNavigator(
+    new NavigatorNode({
+      priority: -1,
+      path: 'codex-hook-links',
+      icon: 'navigation',
+      label: CODEX_HOOK_LINKS
+    } as NavigatorNodeData)
+  )
+];

package/src/app/sample-plugin.model.ts

@@ -0,0 +1,8 @@
+import { IIdentified, IManagedObject } from '@c8y/client';
+
+export const CODEX_HOOK_LINKS = 'Codex hook links';
+
+export interface SamplePluginConfig {
+  text?: string;
+  device?: IIdentified & Partial<IManagedObject>;
+}

package/src/app/view/sample-view.component.html

@@ -0,0 +1,59 @@
+<c8y-title>{{ CODEX_HOOK_LINKS }}</c8y-title>
+
+<!-- Include in the action bar -->
+<c8y-list-display-switch
+  class="form-inline"
+  (onListClassChange)="listClass = $event"
+  [listLength]="cards.length"
+></c8y-list-display-switch>
+
+<!-- The record list wrapper -->
+<div
+  class="card-group"
+  [ngClass]="listClass"
+>
+  <!-- The sticky header -->
+  <div class="page-sticky-header hidden-xs">
+    <div class="d-flex">
+      <div class="card-header card-column-20">
+        <span>Name</span>
+      </div>
+      <div class="card-block card-column-40">
+        <span>Description</span>
+      </div>
+    </div>
+  </div>
+  <!-- The records list -->
+  <div
+    class="col-sm-6 col-md-4 col-lg-4 col-xs-12"
+    *ngFor="let card of cards"
+  >
+    <div class="card pointer">
+      <div class="card-header separator card-column-20">
+        <span
+          class="card-title text-truncate"
+          title="{{ card.name }}"
+        >
+          {{ card.name }}
+        </span>
+        <div class="card-actions">
+          <a
+            class="btn btn-link p-0 text-muted"
+            title="Open in new tab"
+            [attr.role]="'button'"
+            [target]="'_blank'"
+            [attr.rel]="'noopener noreferrer'"
+            [attr.href]="card.url"
+          >
+            <i c8yIcon="external-link"></i>
+          </a>
+        </div>
+      </div>
+      <div class="card-block card-column-40">
+        <small>
+          {{ card.description }}
+        </small>
+      </div>
+    </div>
+  </div>
+</div>

package/src/app/view/sample-view.component.ts

@@ -0,0 +1,110 @@
+import { CommonModule } from '@angular/common';
+import { Component } from '@angular/core';
+import { HeaderModule, IconDirective, ListDisplaySwitchModule } from '@c8y/ngx-components';
+import { CODEX_HOOK_LINKS } from '../sample-plugin.model';
+
+interface HookCards {
+  name: string;
+  description: string;
+  url: string;
+}
+
+@Component({
+  selector: 'c8y-app-sample-view',
+  templateUrl: './sample-view.component.html',
+  standalone: true,
+  imports: [CommonModule, HeaderModule, IconDirective, ListDisplaySwitchModule]
+})
+export class SampleViewComponent {
+  readonly CODEX_HOOK_LINKS = CODEX_HOOK_LINKS;
+  cards: HookCards[] = [];
+  listClass = '';
+
+  constructor() {
+    this.cards = this.getHookCards();
+  }
+
+  private getHookCards(): HookCards[] {
+    return [
+      {
+        name: 'hookActionBar',
+        description:
+          'The action bar offers a user-friendly interface to efficiently navigate and manage records. ',
+        url: 'https://styleguide.cumulocity.com/apps/codex/#/develop/hooks/action-bar/overview'
+      },
+      {
+        name: 'hookAction',
+        description:
+          'This hook adds a global action to the page header, which is displayed or enabled under certain conditions via `c8y-action-outlet`.',
+        url: 'https://styleguide.cumulocity.com/apps/codex/#/develop/hooks/action/overview'
+      },
+      {
+        name: 'hookBreadcrumb',
+        description: 'This hook shows the navigation breadcrumbs in the header bar.',
+        url: 'https://styleguide.cumulocity.com/apps/codex/#/develop/hooks/breadcrumbs/overview'
+      },
+      {
+        name: 'hookComponent',
+        description: 'This hook adds dynamic components, for example, widgets, to the UI.',
+        url: 'https://styleguide.cumulocity.com/apps/codex/#/develop/hooks/dynamic-component/overview'
+      },
+      {
+        name: 'hookDrawer',
+        description: 'This hook adds a component to left or right drawer.',
+        url: 'https://styleguide.cumulocity.com/apps/codex/#/develop/hooks/drawer/overview'
+      },
+      {
+        name: 'hookNavigator',
+        description: 'This hook allows for the registration and display of navigator nodes.',
+        url: 'https://styleguide.cumulocity.com/apps/codex/#/develop/hooks/navigator-route/overview'
+      },
+      {
+        name: 'hookRoute',
+        description: 'A hook used to add new routes.',
+        url: 'https://styleguide.cumulocity.com/apps/codex/#/develop/hooks/navigator-route/overview'
+      },
+      {
+        name: 'hookService',
+        description: 'This hook adds services that can be shared between plugins and host app.',
+        url: 'https://styleguide.cumulocity.com/apps/codex/#/develop/hooks/service/overview'
+      },
+      {
+        name: 'hookStepper',
+        description: 'This hook adds a step into an existing stepper.',
+        url: 'https://styleguide.cumulocity.com/apps/codex/#/develop/hooks/stepper/overview'
+      },
+      {
+        name: 'hookTab',
+        description: 'This hook allows you to show tabs on certain conditions.',
+        url: 'https://styleguide.cumulocity.com/apps/codex/#/develop/hooks/tabs/overview'
+      },
+      {
+        name: 'hookUserMenu',
+        description: 'Add user menu to the right drawer.',
+        url: 'https://styleguide.cumulocity.com/apps/codex/#/develop/hooks/user-menu/overview'
+      },
+      {
+        name: 'hookVersion',
+        description: 'Add versions to the right drawer.',
+        url: 'https://styleguide.cumulocity.com/apps/codex/#/develop/hooks/versions/overview'
+      },
+      {
+        name: 'hookWidget',
+        description: 'This hook adds widgets to the UI.',
+        url: 'https://styleguide.cumulocity.com/apps/codex/#/develop/hooks/dynamic-widget-component/overview'
+      },
+      {
+        name: 'hookWizard',
+        description: 'This hook adds an entry into an existing wizard.',
+        url: 'https://styleguide.cumulocity.com/apps/codex/#/develop/hooks/wizard/overview'
+      }
+      // TODO: Uncomment when the codex entry is available
+      // {
+      //   name: 'hookWidgetConfig',
+      //   description:
+      //     'This hook adds sections to the widget configuration view, like: "Time context".',
+      //   url: 'https://styleguide.cumulocity.com/apps/codex/#/develop/hooks/widget-config/overview'
+      // }
+    ];
+  }
+}

package/src/app/widget/sample-widget-config.component.ts

@@ -0,0 +1,52 @@
+import { Component, inject, Input, OnInit, TemplateRef, ViewChild } from '@angular/core';
+import { ControlContainer, NgForm } from '@angular/forms';
+import { AlertService, CommonModule, DynamicComponent, FormsModule } from '@c8y/ngx-components';
+import { WidgetConfigService } from '@c8y/ngx-components/context-dashboard';
+import { SamplePluginConfig } from '../sample-plugin.model';
+import { SamplePluginComponent } from './sample-widget.component';
+
+@Component({
+  selector: 'c8y-sample-plugin-config',
+  template: `
+    <div class="form-group">
+      <c8y-form-group>
+        <label>Text</label>
+        <textarea
+          style="width:100%"
+          name="text"
+          [(ngModel)]="config.text"
+          [required]="true"
+        ></textarea>
+      </c8y-form-group>
+    </div>
+
+    <ng-template #sampleWidgetPreview>
+      <c8y-sample-plugin [config]="config"></c8y-sample-plugin>
+    </ng-template>
+  `,
+  viewProviders: [{ provide: ControlContainer, useExisting: NgForm }],
+  standalone: true,
+  imports: [CommonModule, FormsModule, SamplePluginComponent]
+})
+export class SamplePluginConfigComponent implements DynamicComponent, OnInit {
+  @Input() config: SamplePluginConfig = {};
+
+  private readonly alert = inject(AlertService);
+  private readonly widgetConfigService = inject(WidgetConfigService);
+
+  @ViewChild('sampleWidgetPreview')
+  set previewMapSet(template: TemplateRef<any>) {
+    if (template) {
+      this.widgetConfigService.setPreview(template);
+      return;
+    }
+    this.widgetConfigService.setPreview(null);
+  }
+
+  ngOnInit(): void {
+    this.widgetConfigService.addOnBeforeSave(config => {
+      this.alert.success('Widget added successfully', JSON.stringify(config, null, 2));
+      return true;
+    });
+  }
+}

package/src/app/widget/sample-widget.component.css

@@ -0,0 +1,4 @@
+.text {
+  transform: scaleX(-1);
+  font-size: 3em;
+}

package/src/app/widget/sample-widget.component.ts

@@ -0,0 +1,21 @@
+import { CommonModule } from '@angular/common';
+import { Component, Input } from '@angular/core';
+import { FormsModule } from '@c8y/ngx-components';
+import { SamplePluginConfig } from '../sample-plugin.model';
+
+@Component({
+  selector: 'c8y-sample-plugin',
+  template: `
+    <div class="p-16">
+      <h1>Sample-plugin</h1>
+      <p class="text">{{ config?.text || 'No text' }}</p>
+      <small>My context is: {{ config?.device?.name || 'No context' }}</small>
+    </div>
+  `,
+  styleUrls: ['./sample-widget.component.css'],
+  standalone: true,
+  imports: [CommonModule, FormsModule]
+})
+export class SamplePluginComponent {
+  @Input() config: SamplePluginConfig;
+}

package/src/assets/assets.ts

@@ -0,0 +1,14 @@
+/**
+ * This file is to include certain images or CSS files into the bundle. As for plugins,
+ * you need to bundle *all* assets due to a relative or absolute path might not work.
+ *
+ * Currently supported file extensions are: jpeg, jpg, gif, png, woff(2), eot, ttf, svg, css, sass and less
+ *
+ * If you need more types supported, add them to the d.ts file and add a webpack rule.
+ */
+import previewImage from './sample-plugin-pr.png';
+
+// paths can be shared via this module if needed
+export const assetPaths = { previewImage };
+
+import './example.css';

package/src/assets/example.css

@@ -0,0 +1,10 @@
+/* 
+Global styles:
+Add the path to "example.css" in the "styles" entry of the angular.json file.
+This will be a global style -> try to avoid as it could break existing styles
+better use component based styling (see ../widget/sample-plugin.component.css)
+For more information, please check: https://angular.io/guide/workspace-config#styles-and-scripts-configuration
+*/
+.text {
+  color: var(--brand-primary);
+}

package/src/assets/index.d.ts

@@ -0,0 +1,9 @@
+declare module '*.jpg';
+declare module '*.jepg';
+declare module '*.png';
+declare module '*.gif';
+declare module '*.svg';
+declare module '*.woff';
+declare module '*.woff2';
+declare module '*.eot';
+declare module '*.ttf';

package/src/bootstrap.ts

@@ -0,0 +1,18 @@
+import './polyfills';
+import '@angular/compiler';
+
+import { enableProdMode } from '@angular/core';
+import { bootstrapApplication } from '@angular/platform-browser';
+import { BootstrapComponent, provideBootstrapMetadata } from '@c8y/ngx-components';
+import { BootstrapMetaData } from '@c8y/bootstrap';
+import { appConfig } from './app/app.config';
+
+declare const __MODE__: string;
+if (__MODE__ === 'production') {
+  enableProdMode();
+}
+
+export function bootstrap(metadata: BootstrapMetaData) {
+  appConfig.providers.push(...provideBootstrapMetadata(metadata));
+  return bootstrapApplication(BootstrapComponent, appConfig).catch(err => console.log(err));
+}

package/src/i18n.ts

@@ -0,0 +1,6 @@
+/**
+ * Internationalizing files in po format (https://en.wikipedia.org/wiki/Gettext#Translating)
+ * You can always add additional strings by adding your own po file. All po files are
+ * combined to one JSON file per language and are loaded if the specific language is needed.
+ */
+import './locales/de.po'; // <- adding additional strings to the german translation.

package/src/locales/de.po

@@ -0,0 +1,10 @@
+msgid ""
+msgstr ""
+"Project-Id-Version: c8y.plugin\n"
+"Language: de\n"
+"Content-Type: text/plain; charset=UTF-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Plural-Forms: nplurals=2; plural=(n != 1);\n"
+
+msgid "Module Federation widget"
+msgstr "Modul Federation Dingsbums"

package/src/main.ts

@@ -0,0 +1,17 @@
+import './i18n';
+
+const barHolder: HTMLElement | null = document.querySelector('body > .init-load');
+export const removeProgress = () => barHolder?.parentNode?.removeChild(barHolder);
+
+applicationSetup();
+
+async function applicationSetup() {
+  const { loadMetaDataAndPerformBootstrap } = await import('@c8y/bootstrap');
+  const loadBootstrapModule = () =>
+    import(
+      /* webpackPreload: true */
+      './bootstrap'
+    );
+
+  loadMetaDataAndPerformBootstrap(loadBootstrapModule).then(removeProgress);
+}

package/src/polyfills.ts

@@ -0,0 +1,33 @@
+/**
+ * This file includes polyfills needed by Angular and is loaded before the app.
+ * You can add your own extra polyfills to this file.
+ *
+ * This file is divided into 2 sections:
+ *   1. Browser polyfills. These are applied before loading ZoneJS and are sorted by browsers.
+ *   2. Application imports. Files imported after ZoneJS that should be loaded before your main
+ *      file.
+ *
+ * The current setup is for so-called "evergreen" browsers; the last versions of browsers that
+ * automatically update themselves. This includes Safari >= 10, Chrome >= 55 (including Opera),
+ * Edge >= 13 on the desktop, and iOS 10 and Chrome on mobile.
+ *
+ * Learn more in https://angular.io/docs/ts/latest/guide/browser-support.html
+ */
+
+/***************************************************************************************************
+ * BROWSER POLYFILLS
+ */
+
+/**
+ * By default, zone.js will patch all possible macroTask and DomEvents
+ * user can disable parts of macroTask/DomEvents patch by setting following flags
+ */
+
+(window as any).__Zone_disable_requestAnimationFrame = true; // disable patch requestAnimationFrame
+// (window as any).__Zone_disable_on_property = true; // disable patch onProperty such as onclick
+(window as any).__zone_symbol__BLACK_LISTED_EVENTS = ['scroll', 'mousemove', 'message'];
+
+/***************************************************************************************************
+ * Zone JS is required by default for Angular itself.
+ */
+import 'zone.js'; // Included with Angular CLI.

package/tsconfig.app.json

@@ -0,0 +1,19 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "./out-tsc/app",
+    "noImplicitOverride": false,
+    "skipLibCheck": true,
+    "strict": false
+  },
+  "files": [
+    "src/main.ts"
+  ],
+  "include": [
+    "src/**/*.ts",
+    "../ngx-components/**/*.ts"
+  ],
+  "exclude": [
+    "../ngx-components/dist",
+  ]
+}