This document provides instructions for creating custom UI5 controls and libraries. It discusses the technologies used, how to configure the SAP Web IDE, generate a UI5 library, include an existing lightbox library, and the anatomy of a custom control and library. The document demonstrates how to create a lightbox control, update test code to use it, deploy the library, consume it in an application, and add the control to a view.

1. Emanuele Ricci & Wouter Lemaire
June 22, 2018
Get started with UI5 custom
controls

2. 2
Revisions and Usage
2
i
 Author Emanuele Ricci & Wouter Lemaire
 Creation Date 04/06/2018
 Document Usage Presentation for internal use.
 Document Revision 2018.06.04-21.35
 Validity Starting June 04th 2018 – Replaces all previous templates
Contact Emanuele.ricci@techedgegroup.com for any questions regarding this
document

3. 3
Contact Information
3
Emanuele Ricci
SAPUI5 Ninja Developer
SAPUI5 Ninja, Android Enthusiastic and tech lover in general. I’m a
full stack engineer based in Lucca that works with bleeding edge
technologies since high school.
Wouter Lemaire
SAP Development Consultant
• SAPUI5
• Fiori
• ABAP
• SAP Web IDE
• SAP Mentor

4. Let’s start

5. 5
• This talk will help you to learn how to create a custom control and
how to build a custom library to be re-used in all your project.
• Final Project: openui5-lightbox2
Introduction
5

6. 6
• OpenUI5
• WebIDE
Technologies Used
6

7. Configure SAP Web IDE

8. 8
• UI5 Lab Feature: contains the template for the UI5 Library
• UI5 Library Manager
Configure Destinations
8

9. 9
Enable this plugins on your WebIDE
9

10. Generate UI5 Library

11. 11
Generate your Library from UI5Lab Library 1/2
11

12. 12
Generate your Library from UI5Lab Library 2/2
12

13. 13
Build & Test
13

14. Include Lightbox2

15. 15
Include the Lightbox2 JS Library 1/3
15

16. 16
Images will not be
downloaded due to CORS.
Include the Lightbox2 JS Library 2/3
16

17. 17
Include the CSS file by
adding the reference in your
library.source.less base
folder
Include the Lightbox2 JS Library 3/3
17
@import (inline)
"../../libs/lightbox
2/css/lightbox.cs
s";

18. Anatomy Custom Control

19. 19
A custom control is a JavaScript object that has two special sections
(metadata and renderer) and a number of methods that implement the
functionality of the control.
Anatomy of a Custom Control 1/2
19

20. 20
Anatomy of a Custom Control 2/2
20

21. 21
The metadata section defines the data structure and thus the API of
the control. With this meta information on the properties, events, and
aggregations of the control OpenUI5 automatically creates setter and
getter methods and other convenience functions that can be called
within the app.
Metadata

22. 22
• A property is defined by a name and a type. Additionally, a default
value can be defined for a property.
• type: Data type of the control property; SAPUI5 provides an
automatic type validation. Valid types are, for example, string
(default) for a string property, int or float for number properties, int[],
etc. for arrays and sap.ui.core.CSSSize for a custom-defined type.
• defaultValue: Default value that is set if the application does not set
a value; if no default value is defined, the property value is
undefined.
Properties

23. 23
• An aggregation is a strong relation that also manages the lifecycle of
the related control, for example, when the parent is destroyed, the
related control is also destroyed.
• An association is a weak relation that does not manage the lifecycle
and can be defined multiple times. To have a clear distinction, an
association only stores the ID, whereas an aggregation stores the
direct reference to the control.
Aggregations and Associations

24. 24
• Events allow you to expose which events will be fired by your
custom control and which parameters will be shipped with it.
• For each event, methods for registering, de-registering and firing the
event are created.
• You can gather more documentation about the metadata
section here.
Events
24

25. 25
• The renderer defines the HTML structure that will be added to the
DOM tree of your app whenever the control is instantiated in a view.
It is usually called initially by the core of OpenUI5 and whenever a
property of the control is changed. The parameter oRM of the render
function is the OpenUI5 render manager that can be used to write
strings and control properties to the HTML page.
• You can gather more documentation about the renderer
section here and here.
Renderer
25

26. 26
• library.js
• Translations: messagebundle.properties (not needed in this
example)
• Themes: library.source.less, shared.css, img, img-RTL (not needed
in this example)
• Control and Renderer
• For a deeper explanation on the development process you can take
a look a the official control library documentation.
Anatomy of a Custom Library
26

27. 27
• The library.js file is a central file for each control library that contains
the library declaration and any enums, simple types and interfaces
present in the library. There can also be additional code and the
definition of lazy loading stubs for non-controls.
• The most important feature in this file from the perspective of a
control developer is the list of controls maintained in the library
declaration: all controls must be added there in order to make their
constructors available immediately when the library is loaded (so
applications only need to require the library, not each control).
Library.js 1/2
27

28. 28
Library.js 1/2
28

29. 29
Update the WebIDE Test Code
29
sap.ui.getCore().attachInit(function() {
var oLightbox = new com.sap.ui5con.Lightbox({
gallery:"lightbox-gallery",
alwaysShowNavOnTouchDevices:false,
albumLabel:"UI5image %1of %2",
disableScrolling:false,
fadeDuration:600,
fitImagesInViewport:true,
imageFadeDuration:600,
positionFromTop:50,
resizeDuration:700,
showImageNumberLabel:true,
wrapAround:false,
content:[
new com.sap.ui5con.LightboxImage({src:"https://s3-us-west-
2.amazonaws.com/s.cdpn.io/82/orange-tree.jpg",title:"Title 1",alt:"Alt1"}),
new com.sap.ui5con.LightboxImage({src:"https://s3-us-west-
2.amazonaws.com/s.cdpn.io/82/submerged.jpg",title:"Title2",alt:"Alt2"})
]
});
oLightbox.placeAt("content");
});

30. Get your hands dirty

31. 31
Now you have all the informations to start writing code and build your UI5 Custom Library on
WebIDE
https://goo.gl/zVkCoM
Get your hands dirty!
31

32. Consume the library

33. 33
Remember the Application name  Deploy
Deploy the library on SCP
33

34. 34
Consume the Library
34

35. 35
Configure neo-app.json
35
{
"path": "/resources/com/sap/ui5con",
"target": {
"type": "application",
"name": "myui5library",
"entryPath":
"/resources/com/sap/ui5con"
},
"description": "UI5Lab Space Library"
}

36. 36
Add the library dependency in your manifest.json
36

37. 37
Add the control to your View
37

38. 38
Enjoy!
38

39. Thank you.
Contact information:
Emanuele Ricci
Wouter Lemaire