Part II: Creating a User Lookup Application using the jQuery Mobile Framework
In Part I I’ve explained how to install the Neptune Application Designer (NAD). We also created a little application using a boilerplate and added some modifications to see how the designer basically works.
In this blog i want to show how to create a ‘real’ application using jQuery Mobile, one of the frameworks coming with the Neptune Application Designer.
If you change to the ‘Application’ TAB of the designer and select the ‘Library’ TAB you can see the included frameworks and Addons:
- The ‘Custom’ library is mainly for backward compatibility. If there are any future changes in the frameworks, your existing applications will be set to the custom library to run without any problems. Certainly it’s still possible to make changes to this applications.
- The ‘Wijmo’ library includes many awesome components of the wijmo UI framework. It’s great for creating Tablet and Desktop UI’s as well as mobile UI’s. Here’s an example of one of my projects using the wijmo framework. My aim was to show as many of information as you would get from a SAP GUI done with a TreeView and ALV: Roles Insight
- The ‘jQuery Mobile’ option includes all components of their mobile framework. It’s optimized for all popular mobile device platforms: jQuery Mobile
- The ‘jQuery Mobile & Wijmo’ option gives you the ability to combine this two frameworks. So you have the possibility create an application such as showing jQuery Mobile components combined with the Wijmo Grids for tables. It’s a bit tricky, because you need to know the difference between both frameworks. We will look into it later in this blog.
- ‘SAPUI5’ includes the components of the SAP framework. As you may know usually you would need to use oData and the NetWeaver Gateway for it. Beside that you need to work with the Eclipse. There’s a very interesting blog John Moy wrote about it.
So far i thought webapplications consist of a number of ‘pages’ you are navigating through by sending requests to the server and getting the next page via response. So even if i was familiar with client side scripting to change things without a server roundtrip, i did not understand the basic concept jQuery Mobile is using:
Having that in mind, let’s start with our application. First the ABAP part. Again we need an application class to get the values from the view, select records from our database and provide the results in the attributes of our application class.
Create the application class:
Step 1: Go to transaction SE80 and create a standard ABAP class. Name it i.e ‘Z_LOOKUP_CONTROLLER’
Step 2: Go to the TAB ‘Interfaces’ and implement the interface ‘/NEPTUNE/IF_NAD_SERVER’
Step 3: Activate the class and check the provided neptune interface methods
Step 4: Go to the TAB ‘Attributes’ and create this attributes our elements of the can be bound to later:
Attribute Level Visibility Associated Type
V_SEARCH_NAME Instance Attribute Public Type STRING
T_USERLIST Instance Attribute Public Type HRBAS_BAPIUSNAME_TABLE
T_BAPI_RETURN Instance Attribute Private Type BAPIRET2_T
S_BAPI_RETURN Instance Attribute Private Type BAPIRET2
For this example we will use the FM ‘BAPI_USER_GETLIST’ to get a list of users first.
There are many other ways to do this, but i recommend to follow the steps just to keep it as simple as possible. All DDIC elements are provided in the minisap i’m using.
Step 4: Create a new class method and name it ‘GET_USER_LIST’. Level = Instance Method Visibility = Private. Activate the class.
Step 5: Navigate into the implementation of the method.
Step 6: Insert the following ABAP code and activate the method:
data lt_selection_range type table of BAPIUSSRGE.
data ls_selection_range type BAPIUSSRGE.
*We need the username in upper case
translate me->v_search_name to upper case.
*Check for an empty search and fix it
if me->v_search_name = space.
me->v_search_name = '*'.
move 'CP' to ls_selection_range-option.
*Check for used wildcards
elseif me->v_search_name cp '*'.
move 'CP' to ls_selection_range-option.
move 'EQ' to ls_selection_range-option.
*Prepare the selection range
move 'USERNAME' to ls_selection_range-parameter.
move 'I' to ls_selection_range-sign.
move me->v_search_name to ls_selection_range-low.
append ls_selection_range to lt_selection_range.
CALL FUNCTION 'BAPI_USER_GETLIST'
* MAX_ROWS = 0
WITH_USERNAME = 'X'
* ROWS =
SELECTION_RANGE = lt_selection_range
* SELECTION_EXP =
USERLIST = me->t_userlist
RETURN = me->t_bapi_return.
Step 7: Doubleclick on the method HANDLE_ON_SUBMIT and implement it.
Step 8: Change to the implementation of HANDLE_ON_SUBMIT and insert the following ABAP code:
data ls_message type /neptune/message.
*Usually I'm doing this with try / catch.
*But for this example we keep it simple,
*this is no ABAP training ;-)
*Check if we got an error message
if not me->t_bapi_return is initial.
loop at me->t_bapi_return into me->s_bapi_return.
*Mapping bapi message for output
ls_message-type = me->s_bapi_return-type.
ls_message-number = me->s_bapi_return-number.
ls_message-message = me->s_bapi_return-message.
ls_message-message_v1 = me->s_bapi_return-message_v1.
ls_message-message_v2 = me->s_bapi_return-message_v2.
ls_message-message_v3 = me->s_bapi_return-message_v3.
ls_message-message_v4 = me->s_bapi_return-message_v4.
*Show message on page
server->api_message_create( ls_message ).
*We don't want to navigate to the next page
*Overwrite the nav_to we defined in the form element
*We could also use the current application id (Z_USER_LOOKUP)
*or a different one if we want to show the message there.
*In this case: Just clear it, so we don't trigger a server roundtrip
nav_to = ''.
elseif me->t_userlist is initial.
*Mapping bapi message for output
ls_message-type = 'E'.
concatenate 'Nothing found for' me->v_search_name into ls_message-message SEPARATED BY space.
*Show message on page
server->api_message_create( ls_message ).
nav_to = ''.
The coding checks which event_id is send, calls the the method and provides some actions if we don’t get a result or get an error.
Our search results should be found later in the class attribute ‘T_USERLIST’.
Creating the Application
Note: I’m not explaining the steps from the first blog again! Please read there if you are missing something.
Creating the user search page:
Step 1: Call the Neptune Application Designer
Step 2: Create an application i.e ‘Z_USER_LOOKUP’
Step 3: Assign the application class ‘Z_LOOKUP_CONTROLLER’ (TAB Application’)
Step 4: Select ‘jQuery Mobile’ as framework (TAB Library)
Step 5: Change to the Designer TAB.
Step 6: Check in the library view the components the jQuery Mobile framework provides to get an overview.
Step 7: Select the Container type Page from the jQuery Mobile libraryand move it under the node ‘HTML5 Document’ in the Objects view. Name it i.e ‘pageSearch’.
Note: I recommend to use exclusively objects from the library you are using in your application and not mix them up with elements from HTML5. You would lose a lot of features the other libraries offer. Example: Even if the element button from HTML5 would work in a jQuery Mobile environment you would have to do the layout for it yourself. Use elements from other frameworks only, if the are not provided by the library you are using.
Activate the application and press ‘Preview’. You should see a page with grey background and Trial Version on it. jQuery Mobile is using ‘swatches’ for the layout. Check out the Themeroller. Every swatch (A,B,C, and so on) can have his own design. Let’s switch the swatch for our application:
Step 8: Select the page container in the objects view and change to the ‘Attribute’ TAB on the right side of the designer. Search for the attribute ‘data-theme’. Select ‘a’ from the dropdown, activate the application and preview it again. The background of the page should have changed to black. Swatch ‘a’ is a layout using black, white and blue colors.
Step 9: Add a header. Select the container type ‘Header’ and move it as child node below the node ‘pageSearch’. Name it ‘headerSearch’.
Step 10: Select a ‘Heading’ element from the HTML5 library and move it as child under the node ‘headerSearch’. Select the ‘General’ Tab for this element and enter something into the field ‘Label’. Select a type from the dropdown in the field ‘Type’. ie. H3. Activate and preview.
So far the tree in the designer should look like this:
And the page like this:
In the next steps we will add some content to the page. We need an input field, a submit button and a message area to view errors if we get some in the application class.
Step 11: Move a container type ‘Content’ to the same level under the node ‘headerSearch’. If the popup comes up, select ‘No’ to do this. Name it ‘contentSearch’.
Step 12: Move a form element from the jQuery Mobile library belo the node ‘contentSearch’.
Remember: Only fields inside a formelemt are transported on submit!
Name it ‘formSearch’. In the field ‘Nav. to App’ we need to set the page we will navigate to after the form is submitted. So far we don’t have another ‘page’. So, for the moment lets fill the field with ‘Z_USER_LOOKUP’. So the application is navigating to the current page.
Step 13: Move a input element from the jQuery Mobile library as child below the node ‘formSearch’. Name it ‘inputUsername’. On the ‘General’ TAB enter i.e. ‘Username’ to the field ‘Label’. Now we need to bind this field to the application class. Select the button on the field ‘Datasource’ . In the popup doubleclick on the field V_SEARCH_NAME.
Active the and previe the application. You should see the input field now.
If everything is ok, you could try to find out how to change the layout of the input field. It’s easy.
Step 14: Now we need a submit button to start our search. Move a Button from the jQuery library below the input field. It should be on the same level. Name it. Put something into the Label field on the general TAB.
Important: Fill the Event ID field i.e. with ‘SEARCH’. This ID is important to decide which element called the method in the application class.
Select the TAB Attribute now. We will add an icon to our button. Select ‘check’ from the dropdown for the field ‘data-icon’ and ‘right’ from the dropdown for the field ‘data-iconpos’.
Step 15: to get some space between the input field and the button let’s add some elements type ‘Line Break’ from the HTML5 library between them.
Step 16: Move a element type ‘Message Area’ from the HTML5 library below the node ‘contentSearch’ (same level). We need this element in to show possible errors.
Activate and preview.
At this point you already also could test our search. Just use some breakpoints inside the application class to check what’s happening.
I will stop adding things to this page here and start to show how we create the next page to show the results from our search.
If you want, you can add a footer to the page with some navigation, try to show a logo in the header and so on later. I just want to show the basics, but there still is a lot to discover.
Creating the result page:
We want to show the results of our search and get some details about a selected user. So we need to create a second page with a list showing the records in our table.
Step 1: Copy the application ‘Z_USER_LOOKUP’ in the designer to a new application. Name it ‘Z_USER_OVERVIEW’
Step 2: Select the new page and activate it.
Step 3: Delete all child elements of the container ‘formSearch’.
Step 4: Rename the page container from ‘pageSearch’ to ‘pageOverview’. Remember that all ‘pages’ in a jQuery Mobile application are just parts of the same DOM. So we need to rename the page container, otherwise the application would be messed up.
I would also recommend to rename all other containers, but the most important one is the page container.
Step 5: Rename the label of the heading inside the header to ‘User Overview’
Step 6: Activate.
Step 7: Now go back to the application ‘Z_USER_LOOKUP’. Select the form container and change the field ‘Nav. to App’ to ‘Z_USER_OVERVIEW’.
Change to the ‘Attrubute’ TAB and search for the attribute ‘data-transition’. Check the values from the dropdown list.
This attribute determines which kind of transition is used while navigating to the next application on a mobile device. Set it to ‘slide’ for now and activate the application.
If you are able to calll your SAP system from a mobile device, Just copy the url of the preview of ‘Z_USER_LOOKUP’ to the browser on your device to see how the transition works there.
Step 8: Preview the application. If you press the submit button the application should navigate to the user overview now or stay on the first page and show a message.
Step 9: Change to the application ‘Z_USER_OVERVIEW’ again.
Step 10: Move the listview element from the jQuery Mobile library / List as child below the form element. Name it.
Step 11: Move the Data Loop element from the HTML5 library as child below your listview element and name it.
Step 12: Change to the ‘General’ TAB of the element Data Loop. Bind the field ‘Datasource’ to the attribute table T_USERLIST.
Step 13: Move a element Listview Item from the jQuery Mobile library / List as child below the element ‘Data Loop’.
Step 14: Move a button element from the jQuery Mobile library as child below the element Listview Item and name it.
You objectstree should look like this now:
Step15: Select the element button and go to the ‘General’ TAB for that element. Bind the field ‘Label’ to the field ‘USERNAME’ of the attribut table T_USERLIST:
So far we will get a list of found users as buttons. Now we need to submit the information which of the buttons was pressed to our application class:
Step 16: Select the TAB ‘General’ and enter ‘GET_DETAIL’ to the field ‘Event ID’.
Step 17: Bind the field ‘Event Value’ to the field ‘USERNAME’ of the attribut table T_USERLIST.
Step 18: Call Njal Stabell to deliver new coffee ;-)
Now we can check inside the ‘HANDLE_ON_SUBMIT’ method if the parameter ‘EVENT_ID’ contains the value ‘GET_DETAIL’ and use the username from the parameter ‘EVENT_VALUE’ to call the BAPI_USER_GET_DETAIL, store the result in a new attribute table and navigate to a page where the details are shown.
But that’s up to you to implement it. So far you should have all information to get it to work yourself.
I hope everything worked for you and you had fun. If you want, you can also implement the list as jQuery Mobile Collapsible Set with Collapsibles and just open it to show the detail information for a user. Just discover the power of the jQuery Mobile framework.
In my opinion it’s great to build applications for smartphones and tablets. But I would not use it for portal- and desktop applications. There i would use wijmo or sapui5.
After some training you are now able to create a mobile application like this one in about 1 hour (including checking your twitter account and getting some cups of coffee). What i want to highlight again is the following:
- All we did was some ABAP coding and moving and configuring elements in the Neptune
- All that on a simple ABAP stack
The next time i will explain how to start with the Wijmo framework and create a TreeView and a table using the power of the AJAX Link. Something like this (just kidding): SAP Roles Insight
As far as I know, the Naptune Application Designer with the integration of the SAPUI5 framework will be released in a couple of weeks. I already had the chance to test it:
Isn’t that pretty? So maybe the blog after the next will already show how to create a SAPUI5 application with the Neptune Application Designer. Without any oData, Java and so on.
See you soon and May the Power of Neptune be with You....