(UI5) Web Components enablement for OpenUI5/SAPUI5

Introduction

It has been a while since the usage of UI5 Web Components inside OpenUI5 has been shown as part of the UI5ers live episode 6 in March 2021. Finally, it’s time for an update.

The goal is to enable the support of Web Components in general inside OpenUI5/SAPUI5. Therefore, we need to enhance the framework. In this blog post, you will get some basics around Web Components, learn about the benefits of UI5 Web Components and finally get some insights into the Web Components enablement inside OpenUI5/SAPUI5 plus some hands-on instructions to make your fingers dirty.

UPDATE 2022-07-19

UI5 Web Components enablement is now also available for SAPUI5 1.104.0 in an experimental state (for OpenUI5 it is available since 1.97.0)! Please provide feedback for the UI5 Web Components enablement for SAPUI5 in this blog post for us to improve it further.

Web Components

Web Components are the browsers` built-in UI element framework. It comes with a 0kB of footprint and is available in all major browsers as of today. Web Components enhance the browsers standard vocabulary by custom HTML tags which encapsulate the content (HTML), presentation (CSS) and behavior (JS). Web Components are built on top of the following web platform APIs: Custom Elements, Shadow DOM, ES Module and HTML Templates. As Web Components rely on web standards support by all modern browsers, their benefit is to work with most of the HTML-based web UI frameworks out-of-the-box.

UI5 Web Components

UI5 Web Components add the “enterprise-flavored sugar” on top of the native APIs. While you can develop Web Components easily with Vanilla JS some parts may be a bit cumbersome to implement. Therefore, the UI5 Web Components add some convenience to simplify and streamline the development of Web Components:

• Metadata to declare the available properties, slots, and events
• Lifecycle hooks to be able to i.e., register event handler at the right time
• Synchronize the attributes and the properties, enhanced slot handling
• Declarative syntax to write the renderer by using a markup-centric handlebars syntax
• Utilities to help you making your UI elements accessible, globalized, themable, and secure

Besides that, UI5 Web Components already provide a comprehensive set of UI elements for your application development, and they are available for free as Open-Source under the Apache 2.0 license.

Web UI Framework Support

Web Components are UI elements and no application programming model. To create an application, still a proper web UI framework is needed. As of today, most of the web UI frameworks support Web Components without any additional effort.

But there are still some web UI frameworks which have some troubles using Web Components, i.e., React. Therefore, UI5 Web Components for React is wrapping all UI5 Web Components as React Components. This allows to use them natively into the React programming model. Those React Components ensure that boolean attributes, as well as custom events can be used without breakouts in JSX.

And what about OpenUI5 and SAPUI5?

(UI5) Web Components Enablement for OpenUI5/SAPUI5

Also, OpenUI5/SAPUI5 doesn’t support Web Components natively. The reason for that is that it abstracts HTML/CSS from developers. Instead of working with HTML/CSS directly, the developers are working with UI5 controls when creating their user interface.

UI5 controls are the link between the HTML/CSS world, the framework, and the programming model. When embedding 3^rd party controls, such as Chart.js, ACE, or TinyMCE, best is to write a custom UI5 control to manage the rendering and properly connect to the rendering lifecycle.

For Web Components the framework has been extended by adding special base classes which take care for the rendering of the custom tag, managing the properties, assigning the aggregations to slots, and registering the custom events. Every Web Component which should be used in OpenUI5/SAPUI5 needs to be wrapped by such a so-called wrapper UI5 control.

Technical Structure

The Web Components have been added as additional UI5 libraries. The central UI5 library for the enablement is sap.ui.webc.common which provides the base classes. The most important module is sap.ui.webc.common.WebComponent. It extends sap.ui.core.Control and is the wrapper UI5 control providing the glue code to integrate Web Components into the programming model. This wrapper control takes care to propagate the properties, the aggregation, and the events. It also ensures to render the control and put the aggregated controls in the dedicated slots of the Web Component.

Besides the central UI5 library, two additional Web Component UI5 libraries have been added:

• ui.webc.main: provides the wrapper UI5 controls for the bread & butter Web Components
• ui.webc.fiori: provides the wrapper UI5 controls for the SAP Fiori specific Web Components

These libraries are optional and can be added on-demand. But with the availability of these libraries in OpenUI5, some controls are redundant. There is i.e., a sap.m.Button and a sap.ui.webc.main.Button. The question now is: which UI5 control should I use?

Mixing UI5 Libraries? (sap.m vs. sap.ui.webc.main)

Finally, which Button UI5 control you use depends on your scenario. If you develop Ui5 applications in the context of the SAP Fiori launchpad which is using sap.m UI5 controls, you also should stick to use the sap.m UI5 controls. If you start a new UI5 application from scratch for a standalone scenario using the sap.ui.webc.main UI5 controls may be used. Only for sap.m and sap.ui.webc.main it is an either or decision. All other UI5 libraries can be freely combined. I.e., it makes sense to use sap.ui.layout with sap.ui.webc.main to create a proper user interface as UI5 Web Components do not provide layout components.

In future, new UI5 controls will first be developed as UI5 Web Components and then put back into OpenUI5/SAPUI5 via the UI5 Web Components enablement. These UI5 controls or to be precise wrapper UI5 controls can be mixed with sap.m UI5 controls or sap.ui.webc.main UI5 controls. By developing the UI elements as Web Components and use them in OpenUI5/SAPUI5 will ensure the highest possible return of invest and another huge benefit is that the UI elements can be used with other web UI frameworks.

Performance

Before we start to make our hands dirty, I would like to mention the performance topic. Performance is always key and is related to the number of bytes being loaded. Here, UI5 Web Components have a benefit compared to the classic UI5 controls. UI5 Web Components are atomic and provide their content (HTML), presentation (CSS) and behavior (JS) individually. UI5 controls just provide their content (HTML) and behavior (JS) individually but the presentation (CSS) is managed as part of the UI5 library. This is a big difference as the CSS per library grows with the number of controls being included in the library. So, using just a few UI5 Web Components vs. classic UI5 controls will require less bytes to be loaded. In future, we will see what is possible with this benefit – let’s wait for UI5con ON AIR in July 2022! 😉

Availability in SAPUI5

Right now, the UI5 Web Components enablement is only available in OpenUI5. Still, there are a few things missing. The API documentation needs to be reviewed and proper sample pages need to be created. Right now, we are also checking the usage of the wrapper UI5 controls in combination with the classic UI5 controls. Another reason for this is that we want to get some feedback first before we finally submit the enablement in SAPUI5 because once it is submitted in SAPUI5, we need to stay compatible forever! But there might be the possibility to release them even earlier in SAPUI5 by marking them experimental.

Versioning of UI5 Web Components vs. SAPUI5

UI5 Web Components will not stick with major release 1. At any time, we may need to release another major version. Developers using the UI5 Web Components directly from NPM have control on the version which is being used. This is different once part of the OpenUI5 or SAPUI5 distribution. Here the UI5 team defines which version of the UI5 Web Components is used under the hood. And what if now the UI5 Web Components upgrade to version 2? Then, the UI5 team can ensure the compatibility by keeping the APIs of the wrapper UI5 controls stable.

Getting Started

The fastest way to get started with OpenUI5 and the UI5 Web Components enablement layer is to use a very simple JSBin example: https://jsbin.com/peqaxet/1/edit?html,output. This sample is loading OpenUI5 from CDN and is directly using a sap/ui/webc/main/Button and put it into the body:

<!DOCTYPE html>
<html>
	<head>
		<meta http-equiv='X-UA-Compatible' content='IE=edge'>
		<meta charset="utf-8">

		<title>UI5 Web Components Enablement for OpenUI5</title>

		<script id='sap-ui-bootstrap'
			src='https://openui5.hana.ondemand.com/1.104.0/resources/sap-ui-core.js'
			data-sap-ui-theme='sap_fiori_3'
			data-sap-ui-libs='sap.ui.webc.main'
			data-sap-ui-async='true'
			data-sap-ui-compatVersion='edge'></script>

		<script>

			sap.ui.getCore().attachInit(function() {
				sap.ui.require(["sap/ui/webc/main/Button"], function(Button) {
					new Button({
						text: "Hello World"
					}).placeAt("content");
				});
			});
										 
		</script>

	</head>
	<body id='content' class='sapUiBody'>
	</body>
</html>

This looks exactly like using the sap/m/Button within a UI5 application and if you run the application you will see the UI5 Web Components Button integrated as UI5 control.

Using TypeScript and UI5 Web Components in OpenUI5

Now, we will use the Yeoman generator easy-ui5 to kick-start your TypeScript UI5 application. Here you can see how all different pieces play well together: the Easy-UI5 generator, the UI5 Community templates, the OpenUI5 programming model, TypeScript, and most important here the UI5 Web Components inside OpenUI5.

To get started, please follow the instructions here. The repository which hosts the state of the example below can be cloned from here (the state has been tagged as “blogpost”):

git clone https://github.com/petermuessig/ui5-webcomponents-enablement.git

The example will also be enhanced in future…

Prerequisites

To get started, you need to ensure that you have a recent Node.js version 14 or higher installed on your machine.

Install Yeoman And Easy-UI5

As a next step, you should install Yeoman and the easy-ui5 generator:

npm install -g yo generator-easy-ui5

To verify, that the installation was successful, just run the following command:

yo --generators

Make sure you see the “easy-ui5” generator listed.

!! To verify the version of the installed generator-easy-ui5 you can run the following command:

npm info generator-easy-ui5 version

The version should be at least 3.3.0 to be able to consume the templates from the UI5 Community GitHub organization listed here.

Create Your Project

Now, you can start to create your first UI5 TypeScript application project by running the following command:

yo easy-ui5 ts-app

This directly calls the ts-app sub-generator of easy-ui5 which creates the project for the UI5 TypeScript application based on e.g. the following parameters:

? How do you want to name this application? myapp
? Which namespace do you want to use? com.myorg
? Which framework do you want to use? OpenUI5
? Which framework version do you want to use? 1.104.0
? Who is the author of the library? Your Name
? Would you like to create a new directory for the application? Yes

After entering the parameters, easy-ui5 already runs npm install to ensure that you can immediately start working in your new project. If this fails, just re-run the npm install command again.

Open Your Project

Switch into new folder com.myorg.myapp and open the editor of your choice (best for this example would be the VSCode). In the project root of the UI5 TypeScript application you will find the well-known package.json and ui5.yaml. Compared to the classic UI5 application projects, the characteristic of the UI5 TypeScript application project is that the sources can be found in the src folder instead of the webapp folder and includes TypeScript instead of JavaScript sources:

project-root
\- src
   \- controller
      \- [...]
      \- App.controller.ts
   \- view
      \- [...]
      \- App.view.xml
   \- [...]
   \- Component.ts
   \- manifest.json
   \- index.html
\- [...]
\- package.json
\- README.md
\- ui5.yaml

More details about the project, the project structure and how to use this project can be found in the project root in the README.md. As the project template is based on the ui5-typescript-helloworld project, you can also read the following README.md online.

Running Your Project

To get an impression about the project and what it finally provides, just run your project in the development mode with the following command:

npm start

Now a browser window should appear which runs the UI5 application.

Using UI5 Web Components in an XMLView

Before we can start to use the sap.ui.webc.main.Button in an XMLView we need to prepare the UI5 application.

1) Add the dependency to the sap.ui.webc.main library:

In the project root execute the following command:

npx ui5 add sap.ui.webc.main

The UI5 tooling is adding the sap.ui.webc.main library as dependency to the ui5.yaml. After that you can run your project again.

2) Clean-up the manifest.json:

In the manifest.json, we replace the sap.m library with the sap.ui.webc.main library and remove the sap.ui5/routing section.

{
	"_version": "1.12.0",

	"sap.app": {
		"id": "com.myorg.myapp",
		"type": "application",
		"i18n": "i18n/i18n.properties",
		"title": "{{app_title}}",
		"description": "{{app_description}}",
		"applicationVersion": {
			"version": "1.0.0"
		}
	},

	"sap.ui": {
		"technology": "UI5",
		"icons": {

		},
		"deviceTypes": {
			"desktop": true,
			"tablet": true,
			"phone": true
		}
	},

	"sap.ui5": {
		"rootView": {
			"viewName": "com.myorg.myapp.view.App",
			"type": "XML",
			"async": true,
			"id": "app"
		},

		"dependencies": {
			"minUI5Version": "1.104.0",
			"libs": {
				"sap.ui.core": {},
				"sap.ui.layout": {},
				"sap.ui.unified": {},
				"sap.ui.webc.main": {}
			}
		},

		"handleValidation": true,

		"contentDensities": {
			"compact": true,
			"cozy": true
		},

		"models": {
			"i18n": {
				"type": "sap.ui.model.resource.ResourceModel",
				"settings": {
					"bundleName": "com.myorg.myapp.i18n.i18n"
				}
			}
		}

	}
}

This is how the manifest.json should look like now.

3) Disable the router in the Component.ts:

In the Component.ts file, you need to comment the line which initializes the router:

import UIComponent from "sap/ui/core/UIComponent";
import { support } from "sap/ui/Device";

/**
 * @namespace com.myorg.myapp
 */
export default class Component extends UIComponent {

[...]

	public init() : void {
		// call the base component's init function
		super.init();

		// create the views based on the url/hash
		//this.getRouter().initialize();
	}

[...]

}

4) Use UI5 Web Components wrapper controls in an XMLView:

Open the App.view.xml and replace the content of the view with the following one:

<mvc:View
	controllerName="com.myorg.myapp.controller.App"
	displayBlock="true"
	xmlns="sap.ui.webc.main"
	xmlns:layout="sap.ui.layout"
	xmlns:mvc="sap.ui.core.mvc">

	<Panel>
		<header>
			<Label text="UI5 Web Components Enablement"/>
		</header>
		<layout:VerticalLayout width="100%">
			<Input id="myInput" value="Enter your text here!" width="100%"/>
			<Button text="Don't click me!" click="onClick" width="100%"/>
		</layout:VerticalLayout>
	</Panel>

	<Toast id="myToast"/>

</mvc:View>

With this content, the default namespace for the XML tags is sap.ui.webc.main. So all tags, without a namespace will be the wrapper UI5 controls for the UI5 Web Components. In the code snippet above, we are using the UI5 Web Components Panel and in the header aggregation of the Panel we render a UI5 Web Components Label. In the default aggregation which is the content of the Panel we render a VerticalLayout from the UI5 controls and a UI5 Web Components Input and Button. Next to the Panel we render a Toast which we will use to visualize some feedback.

5) Work with UI5 Web Components wrapper controls in TypeScript:

Open the App.controller.ts and replace the content of the controller with the following one:

import Event from "sap/ui/base/Event";
import Button from "sap/ui/webc/main/Button";
import Input from "sap/ui/webc/main/Input";
import Toast from "sap/ui/webc/main/Toast";
import BaseController from "./BaseController";

/**
 * @namespace com.myorg.myapp.controller
 */
export default class App extends BaseController {

	public onInit() : void {
		// apply content density mode to root view
		this.getView().addStyleClass(this.getOwnerComponent().getContentDensityClass());
	}

	public onClick(event : Event) : void {
		const button = event.getSource() as Button;
		const input = this.byId("myInput") as Input;
		const toast = this.byId("myToast") as Toast;
		toast.setText(`Button text: "${button.getText()}"\nInput value: "${input.getValue()}"`);
		toast.show();
	}

}

In the controller we add the onClick event handler which refers to the Button from the event and looks up the Input and Toast by their ids. The toast will be finally used to display the text of the Button and the value of the Input.

When you add the code step by step on your own, you will notice that you get a lot of code completion support and assistance by your editor. TypeScript is automatically supported also for the UI5 Web Components wrapper controls as they also provide their control metadata and JSDoc which is used to generate the type definitions.

If you want to learn more about the TypeScript support for UI5, you can also follow the tutorial here: https://github.com/SAP-samples/ui5-typescript-tutorial.

Wrap-up

The (UI5) Web Components enablement for OpenUI5 is already in a good shape. Besides the missing samples and improving the API documentation, there is already a good foundation to start playing around with the UI5 Web Components wrapper controls and develop UI5 applications using them. They play well in the whole UI5 ecosystem. If you are brave enough to do some experiments with the UI5 Web Components wrapper controls, we would highly appreciate to get your feedback. Enjoy working with the evolution of the UI elements in OpenUI5!

Time is ready for Web Components: now even more! 😉 

Links

• Examples:
  • JSBin: https://jsbin.com/peqaxet/1/edit?html,output
  • GitHub: https://github.com/petermuessig/ui5-webcomponents-enablement/tree/blogpost

• UI5 Web Components:
  • https://sap.github.io/ui5-webcomponents
  • https://github.com/SAP-samples/ui5-webcomponents-sample-svelte
  • https://github.com/SAP-samples/ui5-webcomponents-sample-react
  • https://github.com/SAP-samples/ui5-webcomponents-sample-vue
  • https://github.com/SAP-samples/ui5-webcomponents-sample-angular
  • https://sap.github.io/ui5-webcomponents-react

• Related Blog Posts:
  • https://blogs.sap.com/2019/02/11/ui5-web-components-the-beta-is-there/
  • https://blogs.sap.com/2019/04/01/the-fastest-way-to-get-started-with-ui5-web-components/
  • https://blogs.sap.com/2020/03/10/ui5-framework-and-ui5-web-components/
  • https://blogs.sap.com/2021/11/10/lift-off-ui5-web-components-1.0.0-launched/
  • https://blogs.sap.com/2021/05/28/getting-started-with-ui5-web-components-in-2021/
  • https://blogs.sap.com/2021/03/24/latest-developments-in-and-around-ui5/
  • https://blogs.sap.com/2021/07/01/getting-started-with-typescript-for-ui5-application-development/