Skip to Content
Author's profile photo Abhilash Gampa

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:

/wp-content/uploads/2013/08/1_265674.png

Provide the JS reference in the html file script tags.

  <script src=”evscomp/com.incture.commons.js” type=”text/javascript”>
  </script>

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:

/wp-content/uploads/2013/08/2_265686.png

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:

/wp-content/uploads/2013/08/3_265697.png

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.

/wp-content/uploads/2013/08/4_265698.png

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.

/wp-content/uploads/2013/08/5_265699.png

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

/wp-content/uploads/2013/08/6_265703.png

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.

Assigned Tags

      11 Comments
      You must be Logged on to comment or reply to a post.
      Author's profile photo Former Member
      Former Member

      Hi Abhilash,

      Nice Article

      metadata,properties,renderer,openEVS,destroyEVS,validateInputs these functions are standard ?

      Regards

      Manoj

      Author's profile photo Abhilash Gampa
      Abhilash Gampa
      Blog Post Author

      Hi Manoj,

      metadata,properties,renderer are standard methods where as openEVS, destroyEVS and validateInputs are custom functions created as part of custom control development.

      Thanks

      Abhilash

      Author's profile photo srinivas sistu
      srinivas sistu

      Hi Abhilash,

      Very nice blog and very well explained. 🙂

      Author's profile photo Former Member
      Former Member

      Nice blog Abhilash.

      Author's profile photo Former Member
      Former Member

      Nice Blog Abhilash, really helpful.

      Author's profile photo Former Member
      Former Member

      Hi Abhilash,

      Thanks for a great example.

      I am new to Openui5 and JS I ahve some basic questions.

      We have not defined any constructor function for ExtendedValueHelpField but we are using it "new incture.commons.ext.ExtendedValueSelector( " how?

      Where exactly is the extend method if we can see the source I think it is added to protoype for all the sap objects but can we see the source so that things get more clear.

      regards,

      Sagar

      Author's profile photo Abhilash Gampa
      Abhilash Gampa
      Blog Post Author

      Hi Sagar,

      You can look at the attachment and it has all the required source code.  The definition of the F4 help is inside the JS file.

      Thanks

      Abhilash

      Author's profile photo Holger Schäfer
      Holger Schäfer

      Hi Abhilash,

      i am just migrating my valuehelps from Sencha to UI5.


      I will have a look into your code to get some ideas.


      What we did around this is a custom DDIC service to be able to easily use ValueHelps (locallly and remote).


      We have addtional config options like


      {

      ...

      domain: [KUNNR|Z_MY_DOM|/UNIORG/Z_DOM]'

      mode: ['local'|'remote'],

      pageSize: 10,

      autoTpl: ['STRAS','ORT01','CITY','COUNTRYCODE'],

      valueField: 'KUNNR',

      displayField: 'NAME1',

      select: [...]

      }


      We have created a custom service to deliver domain based valuehelp out-of-the-box.


      If the domain is flat, the value can directly be returned. If there is a special valuehelp table like for domain KUNNR the table will be used for returning values instead from ddic.


      You can use mode:local if there are less results <=1000 that will completely be returned to widget and then locally sorted. For larger VHs like KUNNR the paging will be used and filtering,sorting,limiting will be done remotely (see pageSize).


      You can also configure something like projection (select) where you can tell the backend which attributes should be transfered back (like hana). the output structure will be build dynamically.


      Another nice option is autoTpl ex. the KUNNR (customer) value help will not be useable without addtionall infos like street, country, etc. So the widget will generally build a flat selection list, but using autoTpl will use a table instead with all that fields. We will also generate filters for each table column to be filtered on ABAP side.


      valueField will be the primary_key while displayFiled will be the shown text.

      Inside our widget the used model will be created on-the-fly and it is quite easy to have valuehelps for all ddic relevant things.

      The ddic services methods can also be overwritten on abap side to inject customer/businessobject specific logic to filter out values depending on userrights, etc.

      So i will have a look into your code when we start mobile-first migrate our sencha valuehelper to sap.m.valuehelp (evs).

      Cheers Holger

      Author's profile photo Abhilash Gampa
      Abhilash Gampa
      Blog Post Author

      Hi Holger,

      Thanks for sharing your idea. Yes, we can extend this further and make it more usable. In the above example, the complete business logic is left with the REST service which can be a service from GW, Java, HANA or any other source. We just need to map meta attributes to display the F4 dynamically. We can add more attributes so that we can define the GW service behavior.

      Let me know if you need any help in extending this further.

      Thanks

      Abhilash

      abhilash.g@gmail.com

      Author's profile photo Andy Choi
      Andy Choi

      Hi Holger,

      Do you have progress with your idea? I thought similar idea as my team have to do lots of F4 possible entry related oData service development.

      Author's profile photo Holger Schäfer
      Holger Schäfer

      Hi Andy,

      currently sapui5 supports ValueHelp out-of-the-box!

      have a look at the sdk SmartField.

      SmartFields control ValueHelp using Odata Annotations,

      that is the prefered way of doing this.

      you can simply map input and output fields to yout value help.

      the sdk is Tellling, that this is a feature of CDS only, but you can use smart fields with the sap gw directly.

      regards

      Holger