MultiComboBox, variable selections and how to load sap.m into your SDK component

If you were always wondering what kind of variable selections you could use with your DesignStudio queries and how to expose that functionality without the boring standard dialog, today is your luck day. In addition to that I am going to introduce you to the shiny world of sap.m or at least give away the secret how to load the sap.m library discovered by Karol Kalisz.

sap.m.MultiComboBox

The MultiComboBox is just perfect to be used with BEx query multi selections. Most of the time you can get away with ranges but sometimes it is unavoidable to pick multiple single values. The SAP standard dialog supports all possible BEx variable options.

     Figure 1: SAP standard dialog, multi and range selection example

That approach works out of the box and handles wrong input gracefully. The only downside is that you can’t customize the selection screen except for some CSS tricks (and/or SAP themes) to adjust the look and feel by manipulating DOM elements. The classes involved use the prefix zenDialog* for example. Now what is left to do if a client tells you to adjust the variable selection screen anyway?

You build your own screen of course. After all you are the expert, right 😉 That’s where the DesignStudio selection components come into play.

• Dropdown Box
• Date Field
• List Box

They support single selections and ranges. For ranges it usually makes sense to use two of them (e.g. date from and date to). It is also possible to construct more complex selection scenarios by combining several components (e.g. Dropdown + Check Box to switch variables on box checked or not) via scripting. So far so good but what about multi selections? You could think of a crazy workaround with global scripting variables and functions using standard components. But that is light-years from being easy to use and maintain. The MultiComboBox ticks all the boxes for us. Let’s take a peek into it:

     Figure 2: MultiComboBox dropdown view

The UI5 MultiComboBox basically enhances a simple dropdown with checkboxes that remember your decisions and tokens that serve as visual feedback for your selections once the dropdown menu area is closed. In addition to that, you get an input area with auto-complete for the values you type in and an easy to use delete functionality either through the close button or by pressing delete/backspace on your keyboard. Awesome component isn’t it?!

Now we have all the tools to replace the SAP standard screen. You can switch it off by putting “Force Prompts on Startup” to false on the APPLICATION object (top level element of your outline tree) of your app and load your data sources in script. Otherwise, when not provided with variables, your queries will trigger the standard screen by themselves during the load phase.

How does the scripting actually work?

There are two major script functions you will need to use. They are called setVariableValue and setVariableValueExt. They are available on the APPLICATION object and on your data source aliases. This is important, if you are using the option “Merge Prompts” (check the further reading section for additional info regarding that topic). In the following I will give some examples for values to achieve various selection scenarios:

• Single selection (internal format): Date 10/12/2015
  • DS_1.setVariableValue(“DATE”,“20151012”);
• Single selection (external format): Date 10/12/2015
  • DS_1.setVariableValueExt(“DATE”,“10/12/2015”);

This could also be 10.12.2015 depending on your locale

• Range selection: Company code 10US – 11US
  • DS_1.setVariableValueExt(“COMPCO”,“10US – 11US”);

Ranges always need to be applied using external variable representation. Also important are the spaces before and after the dash. If you don’t stick to the syntax your DesignStudio dashboard will crash! Same goes for wrong range declarations in terms of entry order like 11US – 10US for example.

• Empty/All selection: Simply select all values
  • DS_1.setVariableValueExt(“COMPCO”,“”);

Empty selections always need to be applied using external variable representation. Otherwise you will get COMPCO = “#” instead, which is “not assigned”.

• Multi selection: Select multiple company codes 10US, 11US and 13US
  • DS_1.setVariableValueExt(“COMPCO”,“10US;13US;11US”);

Multi Selections need to be applied using the external variable representation as well.

• Complex multi selection: Select some company codes but exclude those being bigger than 13US
  • DS_1.setVariableValueExt(“05US;07US – 10US;>13US”);

Find more examples on the DS15 user documentation chapter 32.1.18.

In general all of the variables you are adjusting through scripting need to be input ready.

My MultiComboBox SDK implementation allows you to retrieve your value selection using the following methods:

• getSelectedKey

This method returns a string containing an array of keys of the selected entries (for example [“10US”,”13US”,”11US”])

• getSelectedText

This method returns a string containing an array of all the texts of the selected entries (for example [“SAP AG”,”SAP Pty”,”SAP Ltd.”])

• getSelectedKeyBexReady

This method returns a string containing all the keys of the selected entries separated by a semicolon (for example “10US;13US;11US”). Due to that you can put the result into setVariableValueExt method right away.

The other return values need some additional parsing before they can be fed into the variable value methods. You could for example use the SCN community’s SDK array util component to achieve that.

Note: The strings of arrays will be replaced with Karol’s loop-able arrays as soon as I find the time to make the adjustment.

MultiComboBox properties

     Figure 3: MultiComboBox DesignStudio properties view

You can either assign a data source using data binding (and select a specific dimension) or use my scripting method setItems. The method takes a string as argument which has to contain a JSON object holding the key value pairs. The easiest way to provide the correct structure is to use the SCN community’s SDK Collection component and method getCollectionAsJSON. Depending on the BEx query setup you might want to define some layout options. You can specify the sorting property by key or text and direction (ascending or descending), define if you want to skip result rows and texts for the default checkboxes. Those checkboxes enable the user to select/deselct all entries at once.

In addition to that two event are exposed. On every checkbox-click on the dropdown the onChange event is triggered. The selectionFinished event fires when the dropdown area closes. Unfortunately there is an UI5 bug in DesignStudio 1.5 which doesn’t register the selectionFinished event properly on IE and Firefox. Only chrome still works correctly. In order to avoid unexpected selection results I moved the selection routines to the onChange event which impacts on the user experience but ensures correct selection any time. The Bug is fixed on the newest UI5 release. Therefore I hope the MultiComboBox will be fully functional again on DesignStudio 1.6. My first DesignStudio 1.4 version however works perfectly. You can check out the old version on our deprecated rel-1.0 branch on the community repository. Find the link to our master repository at the end of this post.

I will let you know if 1.6 fixes the problem as soon as possible.

Loading sap.m

As a first start to develop a SDK component on top of sap.m you might try the following:

jQuery.sap.require(“sap.m.MultiComboBox”);

sap.m.MultiComboBox.extend(“org.scn.community.databound.MultiComboBox”, {

…

}

That will work to some extent. But you will soon notice, that all of the MultiComboBox events are not registered and you basically can’t use it at all. Luckily Karol Kalisz established a workaround to load sap.m into you DesignStudio SDK component properly. You can find some more in depth info to the problem here:

http://scn.sap.com/message/15769661#15769661

http://scn.sap.com/thread/3643674#15782624

Karol’s solution, which I also used for the MultiComboBox on the SCN community repository, looks as follows:

jQuery.sap.require(“sap.m.MultiComboBox”);

//mark forced re-load of sap.m events bundle 

oCfgData = window[“sap-ui-config”] 

// check of the library sap.m is already in declared libs (to avoid second execution) 

if(oCfgData.libs.indexOf(“sap.m”) == -1) { 

  // append the information that sap.m is loaded 

  oCfgData.libs = oCfgData.libs + “,sap.m”; 

  // load sap.m and sap.me 

  var oCore = sap.ui.getCore(); 

  oCore.loadLibrary(“sap.m”); 

  if(!sap.ui.Device.support.touch) { 

    // unload events bundle 

    jQuery.sap.unloadResources(“jquery.sap.events.js”, false, true, true); 

    // reload events bundle to assure that sap.m events are active 

    jQuery.sap.require(“jquery.sap.events”); 

  } 

} 

sap.m.MultiComboBox.extend(“org.scn.community.databound.MultiComboBox”, {

initDesignStudio: function() {

…

},

afterDesignStudioUpdate: function() {

…

}

}

This approach is considered temporary until SAP provides standard means to load the sap.m library.

Final words

I hope you can put the MultiComboBox to some good use. To me it actually was the missing piece to be able to replace the SAP standard variable dialog entirely.

As great as the workaround for sap.m is we hope that the library will finally be supported by DesignStudio 1.6.

You don’t know the DesignStudio SDK community? You haven’t downloaded our SDK components yet? Find us, our SDK repository installation link and the MultiComboBox over here:

http://scn.sap.com/community/businessobjects-design-studio/blog/2014/12/10/scn-design-studio-sdk-development-community

Thanks to Karol Kalisz and Mustafa Bensan for doing the research and finding a solution to integrate sap.m despite all the obstacles.

As always feel free to ask lots of follow up questions.

Yours

Martin

Further reading:

• Variable unmerge scenario:  http://scn.sap.com/docs/DOC-63888
• Variable synchronization:     http://scn.sap.com/docs/DOC-64462
• Sap.m.Button discussion:    http://scn.sap.com/thread/3492679
• Sap.m.List problem:            http://scn.sap.com/thread/3643674