UI5 Controls vs UI5 Web Components – Technical dif...

Project setup

UI5 Control

UI5 Web Component

Layers

UI5 Library containing the controls
UI5 App consuming the controls through the library

UI5 Web Component package containing the UI5 Web Components
UI5 Library containing the UI5 Controls that act as a proxy control to the UI5 Web Components
UI5 App consuming the UI5 Web Components of the UI5 Web Component Package through the UI5 Proxy controls of the UI5 Library

Generators

Easy UI5 generator for the library
Easy UI5 or Fiori generator for app

UI5 Web Components generator
Easy UI5 generator for the library specific for Web Components
Generator for UI5 Controls based on the UI5 Web Components
Easy UI5 or Fiori generator for app

Technology

UI5 only

UI5 Web Components
UI5

Project structure

UI5 Control

UI5 Web Component

The recommendation for UI5 Controls is to bundle them in a UI5 library for reusability. The main structure for a library looks like this:

Src folder for storing the control renderer and the controller behind the renderer
Also a folder for the themes in src folder to place the styling of the control
Translatable text files are stored directly in the src folder or could be a dedicated i18n folder in the src folder
Test folder with a test html file for testing the UI5 Web Component
A library.ts file that provides the metadata of all controls that are part of the library

There are more files for building and running the library but the once listed above are the most important once.

A UI5 Web Component packages looks similar to a UI5 Library:

It also comes with an src folder for the control renderer file and the controller behind the renderer
The renderer is in this case a template file using handlebars with the extension .hbs
The controller is similar to the controller of a UI5 control which is a TS or JS file with a class in that handles the logic of the UI5 Web Component
It also comes with a themes and i18n folder just like in the library
It also comes with a bundle.esm.js file to bundle the UI5 Web Components to consume them later on

It is not the same technology but it comes with some overlap and similarities.

Implementation logic

UI5 Control

UI5 Web Component

A UI5 control is defined by a class that extends from the core Control class. For TS support it requires to have the namespace added in the JSDoc and the different constructors accordingly to the metadata.

A UI5 Web Component is also a class that extens from UI5Element. This is similar to the Control class for a UI5 control but for building Web Components.

Next to that, the UI5 Web Components require additional configuration/JSDocs for making the mapping to UI5 Proxy Controls to be generated, eg @alias contains the namespace and name for the UI5 Control. (Web Components do not use namespaces like UI5 does)

It uses “@customElement” decorator to define it as a web component and connect it with the html template, read more details here: https://sap.github.io/ui5-webcomponents/docs/development/component/#the-customelement-decorator

In a UI5 Control we have to define the properties and aggregations as part of the metadata.

Same needs to be done with Web Components but slightly different. The properties and aggregations are defined as properties of the class with additional decorator. For every option we have in the UI5 Control metadata, we have a decorator in the Web Component:

Property: https://sap.github.io/ui5-webcomponents/docs/development/properties/
Slots, which is the name for an aggregation in Web Components: https://sap.github.io/ui5-webcomponents/docs/development/slots/
Events: https://sap.github.io/ui5-webcomponents/docs/development/events/

Associations are not available for Web Components.

Each property and slot also have additional JSDoc information that will be used by the UI5 Control generator. This is needed for a smooth integration with UI5, eg: “@name” is used for mapping the property with the UI5 Control property when generating the UI5 control for the UI5 Web Component.

Just like for UI5 Controls, Web Components have lifecycle methods, eg onAfterRendering . More details on lifecycle methods for Web Components can be found here: https://sap.github.io/ui5-webcomponents/docs/development/events/

Custom defined functions can be just added to the class the same way for both:

Styling

UI5 Control

UI5 Web Component

Both have a folder with a subfolder for every UI5 theme with a stylesheet file for each control. There are a few differences:

Base folder for the controls
Less instead of css
Less will be converted to css during build

Web Component stylesheet is stored in the themes folder
Css files instead of less

Additional layer for Web Components

UI5 Web Components cannot be used directly in a UI5 app. Each UI5 Web Component needs a UI5 control that acts as a proxy to the Web Component. This Proxy Control will be used to map the properties of the UI5 control (and thus the bindings) to the properties in the Web Component. Luckily, this can be generated using the easy-ui5 generator as described here: https://community.sap.com/t5/technology-blogs-by-members/ui5con-2023-generate-ui5-library-controls-f... .

Consuming the UI5 Control and UI5 Web Component

UI5 Control

UI5 Web Component

In the end, both can be used exactly the same way because the UI5 Web Components are already integrated into UI5 with the UI5 Proxy controls in the UI5 Library. From here, UI5 handles it as controls and doesn’t care what’s behind it.

Dependency in package.json

Dependency in manifest.json

Consume the control

Dependency in package.json

Dependency in manifest.json

Consume it as a normal control