Mobile Menu

How to Create a Custom Control Using SAPUI5 Framework

As we know SAPUI5 offers a great amount of different UI controls which may help to develop almost any type of application. But what should we do if we need something specific or project’s UI/UX designer wants some customizations on the existing controls? It seems like the only one good approach will be to create our own (or extend existing) controls and use them like we usually use native SAPUI5 UI elements.

SAPUI5 Control: What is This?

Base class for all SAPUI5 controls is sap.ui.core.Control which extends from class sap.ui.core.Element. Elements couldn’t be used standalone and don’t have renderer method (like ListItem for ListBox).

Control usually contains of:

  • Control name string that consists of the library name and the control name, separated by a dot.
  • Properties or metadata. This properties are usually used to define some modifications on appearance of control (width, color), or data which will be displayed in control.
  • Aggregations are used for defining container for child controls.
  • Associations define which of other controls will be used as a part of this control.
  • Events and methods. Controls usually fire some internal events (like triggerSearch for example), methods usually contains some public functions for the control defined by developer and including standard getter and setter methods which are generated by SAPUI5 automatically when you define control properties.
  • Appearance. Every control has a renderer method which defines control’s HTML output.

SAP recommends to create control libraries instead of simple notepad controls for reuse in different applications.

Simple Traffic Light Control

Let’s create some test control and explore some features which are proposed by SAPUI5 in this area.

Requirements: we need to develop a traffic light control, which could have 3 different states, colors of each light should be customized by properties metadata, current state should be delivered with some OData service data.

So what should we know?

control properties – it is possible to use some properties as metadata for newly created control. In our case the traffic light control have the following properties: currentState, stopColor, warningColor, goColor. Let’s say colors are string HEX values of colors and current state is string with the states from 0 (stop), to 2 (go). In this case properties will look as shown below:

properties : {
    currentState: {type: "string"},
    stopColor: {type: "string"},
    warningColor: {type: "string"},
    goColor: {type: "string"}
}

init() method – this method is invoked by SAPUI5 right after the constructor method, this method could be used for setting up some control’s variables.

exit() method – this method is called when control is destroyed.

event handler methods started with ‘on’ – these events are defined in jquery.sap.events.js and their names start with “sap” (like onclick, onsapnext).

browser events – jQuery.bind() method is usually used for registering browser events and implementation of events handlers.

renderer event – this method is used for creating HTML structure of a control. This method is static, so it doesn’t contain this object, but it has RenderManager object as an input parameter.

You can see an example of renderer method below:

render : function(oRm, oControl) {
    var iCurrentState = parseInt(oControl.getCurrentState()),
        aColors = [];

    aColors.push(oControl.getStopColor());
    aColors.push(oControl.getWarningColor());
    aColors.push(oControl.getGoColor());

    oRm.writeClasses();
    oRm.writeStyles();

    oRm.write("<div");
    oRm.writeControlData(oControl);
    oRm.addClass("traffic-light-container");
    oRm.writeClasses();
    oRm.write(">");

    for(var i=0; i<3; i++){
        oRm.write("<div");

        if(currentState == i){
            oRm.addStyle("background-color", aColors[i]);
            oRm.writeStyles();
        }

        oRm.addClass("traffic-light-indicator");
        oRm.writeClasses();
        oRm.write(">");
        oRm.write("</div>");
    }
    oRm.write("</div>");
}

Additionally we need to describe styles for the ‘traffic-light-indicator’ and ‘traffic-light-container’ classes:

.traffic-light-container {
    width: 50px;
    height: 150px;
    background-color: #cccccc;
    padding: 5px;
}

.traffic-light-indicator {
    width: 50px;
    height: 50px;
    border-radius: 25px;
    background-color: #aaaaaa;
}

Creating a File for the Control (Putting All Things Together)

Let’s combine properties and render method in a separate JS file for a new SAPUI5 control. In the project folder we need to create controls folder and place new JS in that folder.

jQuery.sap.declare("myApp.controls.TrafficLightIndicator");

jQuery.sap.require("sap.ui.core.Control");

sap.ui.core.Control.extend("myApp.controls.TrafficLightIndicator", {
          metadata: {
          library: "myApp.controls",
                   properties : { … }
           },
           render: function(oRm, oControl) { … }
});

Using New Control

First of all we need to declare created control in the view file where we want to use it:

jQuery.sap.require("myApp.controls.TrafficLightIndicator");

Then we can use new control like any standard SAPUI5 control:

var oTrafficLight = new myApp.controls.TrafficLightIndicator({
        currentState: “0”, //{} declaration can be used for the binding as well
        stopColor: “#CC00111”,
        warningColor: “#FFF400”,
        goColor: “#009900”
    });

Some properties might be defined with default values in metadata and this isn’t a required thing to pass all control’s properties to constructor when new control is created. Example of working control is shown below.

Fig. 1. SAPUI5 Custom Traffic Light Control

SAP provides good documentation with detailed information about new SAPUI5 controls development and also extension of the existing controls.

You can read more under the link.