Extension of Standard Controls

Objective

After completing this lesson, you will be able to use the capabilities of the standard controls in the SAPUI5 framework.

Extension of Standard Controls

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.

Sample code of a control extension showing the metadata section where new properties are defined.

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.

Sample code of a control extension. Metadata section defining one allowhover property and one hover event.

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.

Sample code of a control extension. Metadata aggregations section defining three components: acceptButton, content and worksetItems.
  • 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.

Sample code of a control extension showing the onmouseover method definition that fires the hover event..

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.

Sample View.xml file with the new control added in the namespaces and content of the page. the hover event is defined with the value onHover. In the view controller.js file, the onHover method is defined to display a message.

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 code of a control extension with a control renderer.

Sample: Control Renderer

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

Sample code of a control renderer.

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.

Sample code of a control renderer render function.

Log in to track your progress & complete quizzes