Cumulocity IoT Web Development Tutorial - Part 5: Provide widget as a UI Plugin

[Christian_Guether1 (Christian Guether)]

Cumulocity IoT Web Development Tutorial - Part 1: Start your journey
Cumulocity IoT Web Development Tutorial - Part 2: Create your first component
Cumulocity IoT Web Development Tutorial - Part 3: Query data from Cumulocity IoT
Cumulocity IoT Web Development Tutorial - Part 4: Convert component into a widget
Cumulocity IoT Web Development Tutorial - Part 5: Provide widget as a UI Plugin

UI Plugins? UI Plugins!

Part 5 of this web development tutorial series concludes the first part of your journey about becoming an Cumulocity web development expert. It’s great that you’ve gotten this far.

In the last part, you have learned how to create your own custom Cumulocity widget, which can then be used on dashboards in Cumulocity web applications. Normally, you want to share your awesome widget with others, so they can use it in their applications and solutions. In the past, the process of sharing and integrating a widget in one of the default applications (same for custom applications) of Cumulocity was rather cumbersome. This changes with the release of Cumulocity 10.16. Cumulocity 10.16 introduces the Micro-Frontend framework, which allows you to easily install your widget as a UI plugin for any Cumulocity application. There is already an article The power of micro frontends – How to dynamically extend Cumulocity IoT Frontends, which gives you a good introduction and overview about the Micro-Frontend framework. Furthermore, you can find additional information in the official documentation.

In this part of the Cumulocity web development tutorial series, you will learn how you can provide your widget as a UI plugin to Cumulocity using the Micro-Frontend Framework.

Your widget as a UI Plugin

Prerequisite - new project, new template

For part 5 you will create a new project using the @angular/cli and @c8y/websdk tools. The @c8y/websdk tool comes with a template specific to UI plugins. Create a new project running the following command:

npx @angular/cli@v17-lts new --style=less --standalone=false

Provide this configuration:

$ npx @angular/cli@v17-lts new --style=less --standalone=false
? What name would you like to use for the new workspace and initial project? my-first-plugin
? Do you want to enable Server-Side Rendering (SSR) and Static Site Generation (SSG/Prerendering)? No

Once the Angular project has been generated, change directory into the my-first-plugin project and add the @c8y/websdk to the project.

cd my-first-plugin

and run

ng add @c8y/websdk

Use the widget-plugin as a template and scaffold the project based on the latest version:

? Which base project do you want to scaffold from? widget-plugin
? Which base version do you want to scaffold from? 1020.0.15 (latest)

The base project

The base project already comes with a widget. As you want to provide your custom device-info widget as a UI plugin, you can remove the existing widget and add your widget like the following:

1. Delete the directory widget inside the ./src/app directory from the project.

2. Delete the content of the assets directory inside the ./src folder.

3. Create a new directory called modules inside the ./src directory of the project.

4. Copy the device-info directory and its content, which you have built in part 4, into the newly created modules directory. You can also copy the device-info module from the github project.

5. Next you need to update the cumulocity.config.json file, to have your widget be recognized as a UI plugin. All configuration is done within the runtime options of the application options in the cumulocity.config.ts.

6. Update the name and description of your plugin by adding them to the runTime object. The name and description will be shown when your plugin is later listed in the packages section:

   name: 'My first plugin',
   description: 'Plugin contains a fancy widget',
   

7. Furthermore, Cumulocity needs to know, which modules should be part of your plugin. This can be configured in the application option exports. As you have removed the default widget, you can update the existing entry :

    exports: [
         {
           name: 'Device Info Widget',
           module: 'DeviceInfoModule',
           path: './src/modules/device-info/device-info.module.ts',
           description: 'My custom device info widget',
         },
       ]
   

   A plugin can consist of multiple modules. If you later upload your plugin to Cumulocity, the included modules will be listed. The name and description from above are used in the list of modules to describe each module. The module and path properties are necessary to identify the module, which should be used once it is installed as part of the plugin.

That’s it already!. You have configured your first UI-Plugin.

Test your UI plugin locally

The logical next step is to test your plugin locally before deploying and sharing it. The plugin is a Cumulocity widget, which should be used on Cumulocity dashboards, e.g. in the Cockpit application. Therefore, you want to test it locally in the Cockpit application. To test the plugin inside the Cockpit application, you need to adjust the start script in the package.json:

"start": "ng serve -u {{C8Y_URL}} --shell cockpit"

Replace the {{C8Y_URL}} placeholder with the Cumulocity instance you want to proxy data from. The additional --shell cockpit parameter, will run your plugin inside the Cockpit application, which acts as a shell. In order for the shell to recognize your plugin, you must configure and register your plugin as a remote in the cumulocity.config.ts. In the cumulocity.config.ts update the application options for remotes of the runTime property and register your plugin:

remotes: {
  'widget-plugin': ['DeviceInfoModule'],
},

Once you have updated the cumulocity.config.ts, you can run npm start.

Click on the link for the shell application to open the Cockpit application, which now includes your plugin. Navigate to a device dashboard and try to add the device-info widget:

Note: The shell application must have at least the same version as the UI Plugin, you have developed. If your UI Plugin uses the Cumulocity version 1020.0.x, the shell application, e.g. Cockpit application, must be at least version 1020.0.x or higher. This is necessary to ensure the Angular version and certain features of Angular are supported. Otherwise, you might receive errors.

Build and deploy your UI-Plugin

Building your plugin is similar to how you build and deploy C8Y web applications. Inside your project run the command npm run build. This command will execute the script ng serve and build your UI-Plugin. Once your plugin has been built, you can deploy it to your target tenant by running npm run deploy (ng deploy). The command will upload your plugin to your Cumulocity tenant and list it in the Extension section as part of the Administration application.

If you click on your deployed plugin, you can view its details of it. Along with some basic information, the content of the README.md is displayed as well. Make sure to provide some meaningful description about your widget in the readme. Take a look at the README.md in GitHub.

Note: If you want to use images or gifs inside your README, you need to copy these during the build process. To copy assets you can use the copy statement as part of the c8y application options inside the cumulocity.config.ts

With the widget deployed, you can now install it as part of an application, for example, the Cockpit application. If you want to install your plugin as part of the Cockpit application, you first need to clone the Cockpit application and afterward, you can add the plugin to it:

Conclusion

Part 5 concludes the first stage of you becoming an experienced Cumulocity web developer. You have now learned how you can serve your Cumulocity widget as a UI Plugin and share it within Cumulocity with other users.

The Web Development Tutorial Series will not stop here. Upcoming articles will cover specific topics in the context of Cumulocity web development. These can be about best practices or the coverage of specific components from the @c8y/ngx-components library.

If you have a topic, which you want to see as part of this tutorial series, feel free to add it as a suggestion in the comment section.