Sometimes, the needs of the customer go beyond the capabilities of existing SAPUI5 controls. If this is the case, developers can extend existing controls and elements to fulfill customer needs.
Before we start with a detailed look on how to extend an existing SAPUI5 control, let's understand what makes a control a control.
What is a Control?
- Conceptually:
- A control is a UI component (usually a visible one) that can react to the activities of the user and expose properties, methods, and events to the application (and other controls) using JS API.
- Technically, a UI5 control at design time consists of:
The Control API definition that defines the properties, events, methods, and sometimes the associations and aggregations.
The Control Renderer that is responsible for creating the HTML string that defines the structure of the control.
The Control Behavior, which is the JavaScript code taking care of the control interactivity, reacting to user events, firing control events, handling method calls, and property changes.
The Control Style that defines the visuals of the control (usually a control that has different visual designs, bundled as "Themes").
Control API
The control API is represented by the keyword metadata.
Control metadata consists of properties, events, aggregations, and associations. Let's now look at each of these in more detail.
Control Metadata - Properties
The control properties are made up of a name and a type, and optionally, a default value. Valid types are string (default), boolean, int or float for numeric properties, int[ ] (for example, array of int) and sap.ui.core. CSSSize for a property that holds (for example, px) or rem values for size.
Control Metadata - Events
The control events are defined by their name only.
Methods for registering, de-registering, and firing the event are created by the framework. For example, attachHover, detachHover and fireHover.
Control Metadata - Aggregations and Associations
SAPUI5 also knows composite UI-controls. To implement a composite UI-control, the control developer has to define aggregations or associations to other controls.
- Aggregations
Aggregations are defined by their name and a configuration object. It is a relationship between two controls. It shows a parent/child relationship. For example, table rows (parent) and cells (children) The name of the aggregation has to be a string value written in plural. The below image shows how to define an aggregation.
- Type The type property contains the subclass of the control. If type is all you want to set, you can do so as a string instead of the configuration object.
- Multiple The property defines the cardinality and can contain the values 0..1 or 0..n. The default is 0..n.
- singularName This property contains the name of the aggregation in singular. The framework will provide methods like addWorksetItem.
- Associations
- An association is a relationship between two controls. It is not a parent/child relationship. It represents a loose coupling. For example, a label is associated with a text field.
Control Behavior
After adding the metadata, you add method implementations to the control.
Rules for Control Method Naming
- Do not use names of methods provided in superclass. This would result in overriding the superclass methods.
- Private methods are identified by name starting with a underscore, for example, _checkForZero. All other methods are considered public.
- Do not use names starting with get…, set…, insert…, add…, remove… or indexOf… as they could collide with automatically generated methods of the properties or aggregations.
Method names with special meanings are as follows:
- on…: are used for event handlers.
- init: are used to initialize the control, after its instantiation. This is a private method only called by the SAPUI5 core.
- renderer: used for the function that creates the control’s HTML.
Event handler methods are called automatically. For example, if you hover the mouse on top of a control, the system automatically fires the onmouseover event.
You can find the automatically managed events in the API reference .sap/ui/events/ControlEvents
Inside the event handler method, we have access to getters and setters of properties. Those are automatically provided by the framework.
Our example extended button control has an allowHover property. As a result of that, you should understand that the framework creates the getAllowHover( ) method as seen in the code below.

To handle the event at runtime, you should know that the framework creates a method with "on" in front of the event name.
Our extended control has an event named "hover", so we must use the onHover method.

Control Rendering
- The Control Renderer
The renderer is responsible for creating the HTML structure for the control.
A renderer is assigned to the render method of the control.
It is static, so you cannot use "this". Control instance and RenderManager instance are given to the method.
The renderer method has access to the control’s property getters and setters, as well as to any aggregations and associations defined by the control.
- The RenderManager
RenderManager collects and concatenates string fragments and places them in the DOM at the appropriate position by using its methods such as the following:
openStart - Opens the start tag of an HTML element,
openEnd - Ends an open tag started with openStart,
style - Adds a style name-value pair to the style collection of the last open HTML element. This is only valid when it is called between openStart/voidStart and openEnd/voidEnd.
Referencing the Control Renderer
The UI-control definition takes a reference to the renderer class.

Sample: Control Renderer
The following figure shows you (in a sample implementation) the anatomy of a renderer implementation.

As of SAPUI5 1.67, the RenderManager provides a set of new APIS to describe the structure of the DOM that can be used by the control renderers. To use the new API, assign the property apiVersion with the value 2 to your Renderer implementation.
Render Function Implementation
The following figure shows a sample implementation of the render method. The method has access to the RenderManager instance and to the control that should be rendered.
