This little project was made to explore and explain how to work with UI5 Control Extensions and Custom UI5 Controls.
This repo contains a very simple UI5 application, which will display only a welcome page, show-casing a few Custom Controls and Control Extensions.
In the /controls themselves, I have done my best at describing how everything works in detail. Below I will explain broadly how everything works together.
Here is a quick overview of what each control does:
ClickCountButtonis an Extension to Button, which has custom hover- and press functionality.LabelValueis a Custom Control that includes a Label and a single aggregation, allowing an Input, Select, DatePicker, etc. to be rendered below or beside the label, depending on the 'orientation' specified.CustomCardis a Custom Control that renders aggregated content in a card format, complete with title, header, content, and footer.
Nothing fancy, just another UI5 app...
npm i
npm run startWhile developing Custom Controls or Extensions, TypeScript needs to know which getters/setters and properties are available on your new Controls. Otherwise, your control files will be lighting up like Christmas trees, and nobody likes that.
Luckily, UI5 has an early stage package for this, that works just fine: @ui5/ts-interface-generator
I have had this running while working on my controls in watch mode - check the ts:ifs script in package.json - and in short it runs through all my TS files initially, looking for classes that inherits from either sap.ui.base.ManagedObject or sap.ui.core.Control (this includes controls like Button, etc.) and generates *.gen.d.ts files with all the getters and setters we specifically asked for.
While in watch mode, it will on subsequent saves, while in a control file, update/overwrite the associated *.gen.d.ts file, making sure they up-to-date.
For the full documentation go here.
The ability to create our own UI5 Controls or Extend existing ones, allow us make custom components, ready for use in XML.
An example of this could be the LabelValue Control, which will always have a label, but also has a default aggregation to any other Control.
This means, that if we add the a LabelValue Control to our XML view, we can write the label text in the text property like normal, but between its opening and closing tag, we can add a single Control of any kind - Input, DatePicker, Select, etc. - and use them like normal.
We can then specify whether the Label should be above or besides the Control using the orientation property, which makes it much easier to make custom forms for example.
Take a look at Main.view.xml and look for the <gl:...> tags to see this in action.
The only real difference between the two, comes from whether you extend an existing Control like Button (Extension) or whether you extend Control directly (Custom).
It is important to note that Extensions do not necessarily need to use a custom renderer, since the framework already knows how to render a Button, an Input field, etc. Take a look at the ClickCountButton Control to see an example of Extension.
Custom Controls on the other hand, needs to have their renderer specified, which is much simpler than it sounds. See LabelValue Control for an example of Custom Control and its renderer.
For an introduction/overview of how this works in theory I can recommend SAP's own Learning Journey
For more a more advanced example with in-depth descriptions look into step 33 of SAP's UI5 TypeScript Walkthrough
This project is licensed under the Apache Software License, version 2.0 except as noted otherwise in the LICENSE file.