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").
Rules of Custom Controls
The following rules apply to Custom Controls:
A control consists of the following elements:
- Interface:PropertiesEventsAggregationsAssociationsMethods
Behavior
Renderer
CSS Theme Data
You can define properties
You can define Aggregations and associations
You can define events
You can define normal methods
You can have a renderer method
As stated, there is not much difference between extending a control and creating a custom control.
Control Metadata
Control metadata consists of properties, events, aggregations, and associations. Let's now look at each of these in more detail.
Rules for Control Method Implementations
Rules for Control Method Implementations are as follows:
After adding the metadata, you add method implementations to the control.
Method naming restrictions:
- 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. Inside the event handler method, we have access to getters and setters of properties defined by the control.
Control Renderer
The following is information about 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.
Static, so you cannot use "this". Control instance and RenderManager instance are given to the method.
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.
The renderer method has access to the control’s property getters and setters.
The renderer method also has access to any aggregations and associations defined by the control.
Referencing the Control Renderer
The UI-control definition takes a reference to the renderer class.
Sample: Control Renderer
The figure, Sample: Control Renderer, 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.
Contract for Renderer.apiVersion 2:
To facilitate a more efficient in-place DOM patching, and to ensure the compatibility of the control, the following prerequisites must be fulfilled for the controls using the new rendering technology.
Legacy control renderers must be migrated to the new semantic renderer API:
- openStart,
- voidStart,
- style,
- class,
- attr,
- openEnd,
- voidEnd,
- text,
- unsafeHtml,
- icon,
- accessibilityState,
- renderControl,
- cleanupControlWithoutRendering
During the migration, restrictions that are defined in the API documentation of those methods must be taken into account - for example, tag and attribute names must be set in their canonical form. Fault tolerance of HTML5 markup is not applicable for the new semantic rendering API - for example, except void tags, all tags must be closed; duplicate attributes within one HTML element should not exist.
Existing control DOM structure will not be removed from the DOM tree. Therefore, all custom events, including the ones that are registered with jQuery, should be de-registered correctly at the onBeforeRendering and exit hooks. Classes and attribute names should not be escaped.
Styles should be validated using types (for example, sap.ui.core.CSSSize). However, this might not be sufficient in all cases, for example, validated URL values can contain harmful content - in this case, encodeCSS can be used.
To enable a more efficient DOM update, second parameter of the openStart or voidStart methods must be used to identify elements, for example, use rm.openStart("div", oControl.getId() + "-suffix") instead of rm.openStart("div").attr("id", oControl.getId() + "-suffix"). Controls that listen to the focusin event must double-check their focus handling. Since DOM nodes are not removed and only reused, the focusin event might not be fired during re-rendering.
Render Function Implementation
The figure, Render Function Implementation, shows a sample implementation of the render method. The method has access to the RenderManager instance and to the control that should be rendered.