Xena WebComponents

This project is part of the new strategy for further development of the current Xena UI.

It is a wrapper project for exposing lazyloaded modules as webcomponents for use in Xena. It allows for developing parts of the Xena UI in Angular and use them in the existing Xena UI as webcomponents with the smallest possible bundle size possible for each view. This is done by making sure that we:

• only load the parts needed for the specific view in Xena and only WHEN needed.
• load the Angular codebase only once.
• combine all modules in one build to ensure we benefit the most from tree-shaking.

It is strongly encouraged to use(and enhance) the Xena Design System for dumb components (button, dropdowns, inputs etc.) - both in Angular components and in the existing Xena UI. This will further shrink the overall bundle size of the page as the same dumb-components can be reused and hence loaded only once.

The following diagram shows how it comes together:

Getting started developing

In order to install all packages, you need to have a valid personal access token for your Github profile ready. This is because this project depends on @eg-brs/eg.ng.element which is hosted together with its repo on Github. The personal access token needs only to be able to read packages. When you have it ready, this is how you do:

1. Create/Edit your ~/.npmrc (~ means you home folder, for Windows C:/Users/XXXXX)
2. Add //npm.pkg.github.com/:_authToken=TOKEN to the file and replace TOKEN with your personal access token.

• Find token / create token in Github (Setting-> Developer settings -> Personal access tokens) https://github.com/settings/tokens
• Under Generate new token select(read:packages Download packages from GitHub Package Registry)

3. Run npm install
4. Run npm start
5. Voila!

How to add new components

When you need to create a new component, you need to figure out where to put it. The following questions can help you decide that:

1. If it is a smart component, then it should be added as a new module in the Xena.WebComponents repository.
2. If it is a dumb component then it should be created as a Stenciljs Component in Xena.DesignSystem repository. Then that component will be usable in both Xena Core UI as well as in Angular components.

Creating a new Module for use in Xena.WebComponents

Adding a new module to the Xena.WebComponents repository is quite simple. You go to the folder containing the Xena.WebComponents project and type this:

ng g m my-component-name

Afterwards you can easily create a new component under that module like this:

ng g c my-component-name/my-component-name

Define the Component to expose as a WebComponent

In your module you can define one (and only one) component to expose as a webcomponent. You do that by defining a conventional property called customElementComponent.

export class MyComponentModule {
  customElementComponent: Type<any> = MyComponent;
}

Setup selector in Xena.WebComponents AppModule

Final step is to add the selector for your component in the main module of Xena.WebComponents. You do that by expanding the lazyConfig in app.module. You can do it like this:

const lazyConfig:: LazyComponentRegistry = {
  definitions: [
    createDef('sign', () => import('./sign/sign.module').then(m => m.SignModule)),
    createDef('my-component', () => import('./my-module/my-module.module').then(m => m.MyModule))
  ],
  ....
}

Remark: Your selector will always be prefixed with xwc- as defined in the lazyConfig.

Development server

Run npm start for a dev server. Navigate to http://localhost:4200/. The app will automatically reload if you change any of the source files.

Hosting build locally (fx. for test in Xena locally)

Run npm run host to build a development release and host it locally on http://localhost:8081.

Change value of XenaWebComponentsUrl in src/Xena.Web/Web.config to http://127.0.0.1:8081/{lang}/xena-webcomponents.js

<add key="XenaWebComponentsUrl" value="http://127.0.0.1:8081/{lang}/xena-webcomponents.js" />

Remark: Don't commit these changes

Running unit tests

Run ng test to execute the unit tests.

Watch test

Run ng test --watch to watch tests. Will run when files change. se teset on web http://localhost:9876/

Code coverage

Run ng test --code-coverage to run tests with coverage. This will also generate the Code Coverage report coverage/index.html. (your path) ~/Xena.WebComponents/coverage/webstall/index.html

More options

See advanced options here: https://angular.io/cli/test

Deploying new version to Xena

1. Create a new release of Xena.WebComponents by merging into master branch.
2. In the Xena repository update the value of XenaWebComponentsUrl in src/Xena.Web/Web.config to point to the newest version like:

<add key="XenaWebComponentsUrl" value="https://cdn.jsdelivr.net/npm/@xenabiz/[email protected]/dist/prod/{lang}/xena-webcomponents.js" />

Online Demo

Demo

Known issues

Running translations gives error

This solution has been added to i18n script! So you wont need to manually run it!

Running npm run i18n will result in Error: error:0308010C:digital envelope routines::unsupported error

This is due to our old Angular version and the new Node version (nodejs v17+) isn't compatible.

Fix this by going to Visual Studio Code open a terminal run export NODE_OPTIONS=--openssl-legacy-provider