Developing Angular Widgets

This section describes how you can use Angular framework to develop your widgets.

Creating the Project#

About this task#

You can create a Web Component widget using Angular framework. The following instruction provides an example of creating a demo-web-component widget.

Procedure#

Install Angular CLI running the command in your terminal ⁄ console. This will install the latest version of Angular available:

npm i -g @angular/cli

Create a new Angular web component project file (demo-web-component in this case). As of Angular 17 the default app creation will create itself in standalone mode. This will not make use of an app.module file, hence the creation of the Project will vary slightly:

ng new demo-web-component

// You can confirm the angular version used by running 'ng version' in the command line
// If running Angular 17+ and an app.module file is still desired, run the following command instead
ng new demo-web-component --no-standalone

Navigate to the project folder and run the following command:

npm install @angular/elements

Create your Angular component:

ng g component my-web-component -v None

Open your component and update View Encapsulation:

encapsulation: ViewEncapsulation.Emulated

Navigate to /src/app directory and import the following elements into app.module.ts

Note Section 6-9 are only relevant when not creating an angular app in standalone mode. If running in standalone mode (default behaviour from Angular 17 onwards) skip steps 6-9 and carry out the changes specified in step 10:

import  { Injector} from '@angular/core';
import  { createCustomElement } from '@angular/elements';

Add an entryComponents array with your component inside:

entryComponents :  [
   MyWebComponent
]

Remove the bootstrap array from the ngModule in app.module.ts.
Transform the Angular component into a Web Component adding the following code to the AppModule class in app.module.ts:

export class AppModule {
constructor(private injector: Injector) {
    const componentElement = createCustomElement(MyWebComponent, { injector });
    customElements.define('my-web-component', componentElement);
}

ngDoBootstrap() {}
}

This step is only relevant if creating an Angular app in standalone mode, which is the default behaviour from Angular 17 onwards. This should not be followed if your app makes use of an app.module file and you've followed steps 6-9 above. Transform the Angular component into a Web Component by adding the following code to the MyWebComponent component in my-web-component.component.ts:

// Ensure the import statements at the top of the file match the following
import { Component, Injector, ViewEncapsulation } from '@angular/core';
import { createCustomElement } from '@angular/elements';

// Add a constructor inside your component class as follows

constructor(private injector: Injector) {
    const webComponent = createCustomElement(MyWebComponentComponent, { injector: this.injector });
    customElements.define('app-my-web-component', webComponent);
}

Please note that this code will register the custom element when an instance of the Angular component is created. If you want to register the custom element when the application starts, you should move the custom element registration code to the main.ts file or another appropriate place in your application.

Include the contents of your widget. You can use HTML, CSS, and JavaScript files.

Next step#

The component is now set up as a Web Component. At this point, the component files only contain the default Angular <my-web-component works!> example code. You can continue on with development in the HTML, JavaScript and CSS files. When your project is ready as a Web Component, you must build it for later use.

Building the Project#

About this task#

You must build the project to use your widget in Avaya Workspaces.

Procedure#

From the root project folder, run the following command in your terminal / console:

ng build

2a. In the root project folder, create a concatenate.js file with the following contents if running Angular 14 or below:

const fs = require('fs-extra');
const concat = require('concat');

(async function build() {
    const files = [
        './dist/demo-web-component/runtime.js',
        './dist/demo-web-component/polyfills.js',
        './dist/demo-web-component/main.js',
    ]

await fs.ensureDir('elements')
await concat(files, 'elements/demo-web-component.js');
await fs.copyFile('./dist/demo-web-component/styles.css', 'elements/styles.css')
})()

2b. In the root project folder, create a concatenate.js file with the following contents if running Angular 15 or above:

const fs = require('fs-extra');
const concat = require('concat');

(async function build() {
    const files = [
        './dist/demo-web-component/browser/polyfills.js',
        './dist/demo-web-component/browser/main.js',
    ]

await fs.ensureDir('elements')
await concat(files, 'elements/demo-web-component.js');
await fs.copyFile('./dist/demo-web-component/browser/styles.css', 'elements/styles.css')
})()

Run the following command to install the required dependencies:

npm install fs-extra concat --save-dev

Add the following build script into the package.json file. Note: When ran, it generates the Angular build files and uses the concatenate script to bundle them into a single file.

{
"scripts": {
    "build:elements": "ng build --prod --output-hashing none && node concatenate.js"  // Use this if running Angular 14 of below, prod keyword removed above Angular 14
    "build:elements": "ng build --configuration production --output-hashing none && node concatenate.js"  // Use this if running Angular 15 of later
    }

To build and bundle your project, create the elements folder running the following command:

npm run build:elements

Next step#

When your project is bundled and built, continue configuring the widget JSON file that you can import in the Avaya Workspaces Widget Manager.