Web UI Projects - Widget Development Kit

Development Kit for creating individual Widgets for the WinCC Open Architecture Dashboard using Angular and Nx.

Requirements

You need an installation of WinCC OA Version 3.19.6 or higher. See the WinCC OA Documentation for how to setup a dashboard project.

Setup a Node.js development environment:

• Node.js ^16.13.0 || ^18.12.0
• npm ^8.5.5 || ^9.5.0
• Nx v19.3.0

It is recommended to use NVM (node version manager) - available for Windows and Linux.

Installation

The WDK is based on Angular 14 and expects to be installed within a Nx workscape. If you create a new project you can start directly with an empty workspace:

npm init [email protected] -- --preset=angular-monorepo

Need to install the following packages:
[email protected]
Ok to proceed? (y) y
√ Workspace name (e.g., org name) · wdk-project
√ Application name · example-app
√ Default stylesheet format · scss
√ Test runner to use for end to end (E2E) tests · none
√ Would you like to use Standalone Components in you application? · No
√ Would you like to add routing · No
√ Enable distributed caching to make your CI faster · No

This will create a new folder named wdk-project and install all necessary npm packages to create an Angular app - which may take some time.

If you already have an Angular project you need to add Nx capabilities to it. See the official transition guide from Nx for more information.

Next go into your projects folder and install the WDK and all necessary dependencies:

npm install @etm-professional-control/widget-development-kit

Now your workspace is ready to create a new dashboard widgets.

Developing a new widget

A very easy way to create a new widget is the WDK generator which will be installed automatically.

You can start it through the Nx console or the cli command. It will ask you all necessary details about your widget:

npx nx generate @etm-professional-control/widget-development-kit-generator:widget

✔ Give a full name of the widget you want to create: · My First Widget
✔ Give a unique keyword for your widget · demo
✔ Provide a short description: · A basic example implementation of a dashboard widget
✔ Enter a port number on which you want to serve the widget: · 4201
✔ Do you want to support multiple datapoints as inputs: (y/N) · false
✔ Would you like to use Standalone Components? (y/N) · false

This will create a new app in your Nx workspace called widgets-demo along with a library called dashboard-widgets-demo. The term demo is used from your keyword input. A brief example for custom widget translations can be found in the folder apps/widgets/demo/data/WebUI/msg. The widget definition including its full name, a description and a preview image can be found in the folder: apps/widgets/demo/data/WebUI/widgets.

canWrite permission

Starting from WinCC OA version 3.20 a new licensing model was introduced. If you want to validate if the user has write rights it is as simple as checking the checkCanWritePermission() property from DefaultAuthService.

This can be used to disable edit options of widgets for users that do not have required permissions.

Deploying your widget

To use your widget within a dashboard, you first have to compile it using the command:

npx nx build widgets-demo

This will create a production build of your widget. Your generated widget components will be put in dist/data/WebUI and your custom translations and your definition files in the folder apps/widgets/demo/data/WebUI - the contents of those folders needs to be copied to your WinCCOA project under data/WebUI.

Your dashboard should show the new widget in the widget selector after a page refresh.

To make development easier, you can also serve your widget and let the dashboard react to changes on the fly. For this you start your widget in serve mode:

npx nx serve widgets-demo

Then open the widget definition file located in the folder which you previously copied to your WinCCOA project. e.g.: data/WebUI/widgets/demo.json. At the very end you will find a section that defines where your widget is located. In this section switch the content of remoteEntry with remoteEntryDev to get something like this:

"moduleFederationSettings": {
  "remoteEntry_original": "/data/WebUI/components/demo/remoteEntry.js",
  "remoteEntry": "http://127.0.0.1:4201/remoteEntry.js",
  "remoteName": "demo",
  "exposedModule": "./Module"
}

If you now make changes to your widget, you will see their effect after a page refresh. Keep in mind that you still need to build and copy your widget to your OA project at least once in the beginning and after any changes made in your translation files.

Please note that custom widgets created with this version of the widget development kit are only compatible with the dashboard in WinCCOA 3.19. Widgets created with previous versions of the WDK needs to be updated to Angular 14 to be compatible. The nx migrate mechanism can be used for this along, supplementary adaptations of the webpack configuration.

For more details about the WDK API see the WinCC OA Documentation

Changelog

Dashboard 7.1.1

• It is now possible to find internal datapoints in the dashboard by starting the search term with "_".

Dashboard 7.0.2

• Update to Angular 16
  • The Easy Dashboard, all custom widgets and the Widget Development Kit have been migrated to Angular 16.
  • To continue using your custom widgets in the dashboard, you will also need to update your workspace.
  • Learn more about Angular 16 about how nx migrate works or get some nx update tips

Dashboard 6.1.0

• A new widget: Sankey
  • The Sankey Widget displays flow data of current or historical values of different data sources.

Dashboard 6.0.0

• Interface modification for form components (wui-container, wui-fieldset, wui-form-group and wui-input-group)
  • Affects the users who already use custom widgets and want to migrate to WinCC OA 3.19.P005 or higher
  • This change is not backward compatible and it is required to update the usage of the aforementioned components and all WinCC OA instances
  • Components do not accept control/controls as properties anymore
  • Instead new properties like isInvalid or isDirty are introduced (for more details please check the corresponding .md files with examples for each component)
  • To simplify the migration new pipes were introduced (isDirty, isInvalid and isTouched). They accept a list of controls to be verified. Details are to be found in corresponding .md files.

License

MIT