Working with Control Extensions in UI5 – Creating F4 control

One of the key feature of SAP UI5 is developing custom UI controls. This is one of the differentiating factor from WebDynpros. In this blog I will explain how to create a new control by extending the standard controls. I have taken the example of Value Help (F4) which is very much known in WD as EVS. SAP UI5 provides something called ValueHelpField which provides hook methods to write our own logic. I will explain how to extend this control to make it generic component to get EVS kind of functionality.

Concepts: SAP UI5 provides extend() method for all the controls and this can be used to define sub classes. Typically each control will have properties to define the behavior of the control and each control can aggregate other controls. And also controls can have associated controls as well define events. Each control has a method called renderer which defines the look and feel of the control. In this example I will be using the default render class defined for ValueHelpField which is ‘sap.ui.commons.ValueHelpFieldRenderer’.

How it works: The required logic is provided in the attached JS file (com.incture.commons.js). The control name is defined as ‘incture.commons.ext.ExtendedValueSelector’.  Copy the file locally and rename it to .js and copy to a folder in UI5 project. For example if the folder name is evscomp in the UI5 project, the folder structure should look like below:

Provide the JS reference in the html file script tags.

The control provides many features like automatic data validation when user inputs data manually and if data is wrong then the control will be rendered as error. And also it provides data validation state to know the status of input value.

We all set to use the custom control in the application. Follow the below steps to use the control.

1) Define the JSON Model which provides data set for EVS.

   
//Create json data. We can use REST URL instead of this dummy data.             
                   var      aData =
                  [ {
                       codeColId : "1000",
                       descpColId : "Plant 1000"
                  }, {
                       codeColId : "2000",
                       descpColId : "Plant 2000"
                  }, {
                       codeColId : "3000",
                       descpColId : "Plant 3000"
                  }, {
                       codeColId : "4000",
                       descpColId : "Plant 4000"
                  }, {
                       codeColId : "5000",
                       descpColId : "Plant 5000"
                  },{
                       codeColId : "6000",
                       descpColId : "Plant 6000"
                  },];
                        //Create JSON model with above test data
               var oModel = new sap.ui.model.json.JSONModel();
               oModel.setData({modelData : aData});

               //If the data set is provided as REST service in JSON format then use the below syntax
             //oModel = new sap.ui.model.json.JSONModel();
              //oModel.loadData("json url");
 

2)  Now  create the instance of the custom control and set all the required properties. The below mentioned properties are defined for the new control. Please check the file incture.commons.ext.ExtendedValueSelector for property details.

                var myEVSControl = new incture.commons.ext.ExtendedValueSelector("oPlantEVSFieldId",
                {
                           evsSourceFieldId           : "oPlantEVSFieldId",
                           evsTitle                              : "Plant EVS",
                             codeLable                      : "Plant",
                             descriptionLable            : "Plant Desc",
                             codeColModelField            : "codeColId",
                             descColModelField            : "descpColId",
                             dataPath                    : "/modelData",
                             valueHelpRequest : function(evt)
                         {                   
                               this.openEVS(this,oModel);//oModel is the model defined at the above step
                          },
                          change : function(evt)
                          {
                               this.validateInputs(evt,this,oModel);                   
                          }
                });

From the above properties,

evsSourceFieldId is the id of the control.

evsTitle is the EVS dialogue title.

codeLable is the first column name in the EVS popup.

descriptionLable is the second column name in the EVS popup which usually displays the description.

codeColModelField is the bind property from JSON model. From the above dummy JSON data the first field name.

descColModelField is the bind property from JSON model. From the above dummy JSON data the second field name.

dataPath: is the path to values in the REST service.

Note: In case if we have defined the REST service which provides the data in JSON format then the above three properties should be from the REST service.

3) Add the control to layout or any container along with Label control (in this example label with text ‘Plant’ is defined). And the control looks like below:

As we have used the renderer of ValueHelpField the look and feel of the custom control is same ValueHelpField.

4) Enter focus to the text field area and press F4 button or click on the Search Help Icon, which displays the data as below:

5) Select a row and click on Ok button which puts the value back to text field area. The control provides default validations like clicking on Ok button without selecting a row. And also provides default sorting, filtering on two columns.

6) Now try entering some value which is not part of the data set. The control provides default validation and highlights the field as error.

7) Once corrected , the field turns to green indicating valid value.

8) The control provides an API method to know the field validation state. We can check the status by calling the method through the control instance variable created above – myEVSControl.getValidationState();. This method returns true/false. If returned true means the data in the text field is valid data from the given model. If false, the data is not from the data set.

That’s it. The control can be instantiated as many times as we need in any application with different data sets. This version only supports JSON Model but easily it can be extended with OData model as well.

P.S: This initiative is to provide reusable components in UI5 which can be used across the UI5 developments. Looking forward to see more developments in UI5 area.