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 @c8y/cli tool. The command line tool comes with a template specific to UI plugins. Create a new project running the following command:
npx @c8y/cli@1017.0.325 new
Provide this configuration:
? Enter the name of the project: my-first-plugin
? Which base version do you want to scaffold from? 1017.0.x
? Which base project do you want to scaffold from? widget-plugin
You want to go with at least version 1016.0.x as this is the version of the Micro-Frontend Framework that has officially been released. The base project needs to be widget-plugin. This will configure your project as a UI plugin.
Next, download the required dependencies for the project. Navigate into the project
cd my-first-plugin
and run
npm install
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:
-
Delete the directory
widgetfrom the project. -
Delete the references of the
WidgetPluginModulefrom theapp.module.tsotherwise you will get confronted with errors if you want to build and test your plugin later. -
Create a new directory at the root level of the project called
modules. -
Copy the
device-infodirectory and its content, which you have built in part 4, into the newly created modules directory. You can also copy thedevice-infomodule from the github project. -
Next you need to update the
package.jsonfile, to have your widget be recognized as a UI plugin. All configuration is done within the application options in thepackage.json. -
Update the name and description of your plugin. 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", -
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 :{ "name": "Device Info Widget", "module": "DeviceInfoModule", "path": "./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
nameanddescriptionfrom above are used in the list of modules to describe each module. Themoduleandpathproperties 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": "c8ycli server -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 package.json. In the package.json update the application options for remotes and register your plugin:
"remotes": {
"widget-plugin": [
"DeviceInfoModule"
]
}
Once you have updated the package.json, 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: In Cumulocity 10.16, the shell, which you use to test your plugins, must have the same version as your plugin. As the plugin is using 10.16, the cockpit application needs to be on version 10.16 as well, otherwise, you will get an error. If your cockpit application’s version differs (e.g. it is using 10.15), you can clone the Cockpit application using version 10.16 as base version and deploy the Cockpit application to your tenant.
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 c8ycli build and build your UI-Plugin. Once your plugin has been built, you can deploy it to your target tenant by running npm run deploy (c8ycli 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
copystatement as part of the c8y application options inside the package.json
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.
