The document describes adding a mobile coupons ("My Offers") feature to the IBMBank mobile application. It involves using the MobileFirst Platform Service Discovery wizard to generate an adapter for a SOAP web service, adding HTML/JS to display offer data from the service, and implementing local storage of selected offers using the JSON Store database. Key steps include discovering and testing the SOAP service, importing JS files, initializing JSON Store, modifying the app code to retrieve and save offers, and previewing the updated app.
3. IBM Software
Contents Page 3
Contents
“Offers
Lab”
-‐
Using
Service
Discovery
and
the
JSON
Store
Database
.................................................
4
1.1
Getting
Started
with
the
Offers
Lab
.................................................................................................................
4
1.2
Starting
the
Application
and
Adapters
...........................................................................................................
7
1.3
Using
the
Service
Discovery
Wizard
................................................................................................................
9
1.4
Extending
the
IBMBank
App
...........................................................................................................................
13
1.5
Test
the
Newly
Modified
IBMBank
Application
........................................................................................
17
1.6
Review
Code
for
the
IBMBank
Application
................................................................................................
20
1.7
Adding
the
Capability
to
View
Locally
Stored
Offers
Without
Logging
On
......................................
26
1.8
Test
the
Capability
to
View
Locally
Stored
Offers
Without
Logging
On
............................................
29
4. IBM Software
Page 4 MobileFirst Platform Proof of Technology – “Offers” Lab
“Offers Lab” - Using Service Discovery and the JSON Store
Database
In this section, you will extend the application from the Intro lab with a new feature for mobile coupons,
called “My Offers”. You will use the Service Discovery wizard to interrogate a SOAP-based web service
and generate a MobileFirst Platform adapter to use in accessing the service from the application. The
SOAP service returns offer details, including text and graphics. You will add HTML and JavaScript
content to view and manage the list of offers returned from the service, and implement a local storage
pattern to download selected offers into a local JSONstore database on the device. The lab will
showcase:
• The ease of integration and consumption of SOAP or SAP NetWeaver Gateway services using
the Service Discovery Wizard to generate adapters.
• How to add local storage capability to your applications using the JSON Store Database for
offline/online connectivity and synchronization.
• And how to build your application and preview it in the Mobile Browser Simulator, and on a
device (physical or virtual).
1.1 Getting Started with the Offers Lab
IBMBank Application
The starting point for this lab is the completed IBMBank application from the Intro lab. You have two
options to continue with the Offers lab. The recommended approach is option 2 below.
Option 1
If you’ve finished the Intro lab and tested successfully, you can start directly from there and just continue
with instructions starting in section 1.2.
Option 2
The recommend option is to switch to a different Studio workspace already populated with the solution
for the Intro lab. This isolates this lab from any problems with the Intro lab. If you have not run the Intro
lab, or did not complete the steps, then you have to take this option.
Close MobileFirst Platform (MFP) Studio if you have it open by choosing File-Exit.
5. IBM Software
MobileFirst Platform Proof of Technology – “Offers” Lab Page 5
1. Start MobileFirst Studio by navigating to the MobileFirst Platform folder on your desktop and
double-clicking on MobileFirst Platform Studio icon. When asked to select a workspace,
enter
C:MobileFirstLabsworkspacesoffers and click OK.
2. In the upper right corner of the Studio screen verify that you are in the Design Perspective.
If not, click on the Workbench icon at upper right then click the Perspective icon at upper right to
switch to the Design perspective and click OK.
The starting point IBMBank projects should already be imported into the workspace.
6. IBM Software
Page 6 MobileFirst Platform Proof of Technology – “Offers” Lab
If not, do step 3, otherwise skip to the next section, 1.2.
3. If you are using a workspace that does not already contain the solution for the Intro lab, for
example if you are doing this without using the prebuilt lab VMWare images, you’ll need to do the
following to import the Intro lab solution.
__a. Select Import from the File menu and choose General-Existing Projects into Workspace.
Click Next.
__b. Click Select archive file and Browse to
C:MobileFirstLabsimportsoffersIBMBank_offers_import.zip and click Open.
7. IBM Software
MobileFirst Platform Proof of Technology – “Offers” Lab Page 7
Click Finish to import the MobileFirstPlatform project.
1.2 Starting the Application and Adapters
Next you will need to deploy and start both of the adapters created in the Intro lab. This is because each
workspace gets its own development server by default, so the apps and adapters have to be deployed
on the server in this workspace. Note that shared servers are another option, which is covered in a later
lab.
Start the MobileFirst Development Server if it is not running.
The console should display messages indicating that “The server worklight is ready to run a smarter
planet”.
8. IBM Software
Page 8 MobileFirst Platform Proof of Technology – “Offers” Lab
Right click each adapter folder and select Run As > Deploy MobileFirst Adapter. Be sure to do both
adapters.
Look for the “Adapter build and deploy finished.” message in the console window.
Next deploy and run the IBMBankApp application on the MobileFirst Development Server. Select the
IBMBankApp folder under apps, then right click and select Run As > Run on MobileFirst Development
Server.
9. IBM Software
MobileFirst Platform Proof of Technology – “Offers” Lab Page 9
Look for the “BUILD SUCCESSFUL” message in the console window. Switch to the Servers window and
you should see the app started.
Note: You may have to right click on the server entry and select Refresh to see both the adapters. Now
you’re ready to add new capability.
1.3 Using the Service Discovery Wizard
Start the MockService
This lab also requires a SOAP based web service. If you are using the supplied VMWare image
(typical), you can start and stop the MockService web service from the MobileFirst folder on the desktop
using the shortcuts Start MockService.bat and Stop MockService.bat (or MockServer, depending on
your image). Start the service now by double clicking the Start MockService.bat file. You should see
the following window.
10. IBM Software
Page 10 MobileFirst Platform Proof of Technology – “Offers” Lab
If using in a different environment (non-typical), you will need to provide or locate a copy of the
MockService project. Your instructor should provide guidance, and you can find self-help instructions in
the imports/setup folder of the imports package associated with this suite of labs at
(C:MobileFirstLabsimportssetup on the VMWare image).
Note that the steps below assume that MockService is running on localhost and using port 9081. If you
are using a different MockService configuration (unusual), you will need to alter the URLs for the
adapters and back-end service test steps.
Discover the MockService
You will now create an adapter that consumes the Offers Service from the MockService project. The
service discovery wizard allows you to quickly create adapters for leveraging SOAP services and SAP
NetWeaver Gateway endpoints.
__1. Right click on the “services” folder of the IBMBankProject project, select Discover Back-end
Services.
11. IBM Software
MobileFirst Platform Proof of Technology – “Offers” Lab Page 11
__2. In the “Add Back-end Service” wizard, select Web Service Definition Language (WSDL) from
the Service type drop-down and click Next.
__3. In the URL field, copy/paste the following endpoint and click the Go button on the right.
http://localhost:9081/MockService/mockservices/offersService/offersService.WSDL
__4. Under Select Service, expand the BankServiceSoap service and highlight getOffers then click
Finish.
12. IBM Software
Page 12 MobileFirst Platform Proof of Technology – “Offers” Lab
Test the Soap Adapter for the MockService
After pressing Finish, a new adapter named SoapAdapter1 is created under the adapters folder of the
IBMBankProject Project and deployed. Now we can test the new adapter.
__1. To test that the adapter is working properly, right click the SoapAdapter1 folder and select Run
As > Call MobileFirst Adapter. Ensure that the “Call MobileFirst Adapter” dialog looks like the
figure below. Click Run.
13. IBM Software
MobileFirst Platform Proof of Technology – “Offers” Lab Page 13
__2. The results of the adapter invocation should look similar to the JSON output below. If not, you
may need to double check that the MockService project is deployed and the MobileFirst
Development Server is running and that the adapter was created successfully in the previous
steps.
1.4 Extending the IBMBank App
Now that you have successfully created and tested the SOAP based adapter, you can continue
implementing your application to call the web service through the newly created adapter and retrieve a
list of offers available.
Then, you will add HTML and JavaScript content to view and manage the list of offers returned from the
service, and implement a local storage pattern to download selected offers into a local JSONstore
database on the device.
You will begin by adding changes to your application to support the use of the on-device JSON Store
database. The JSON Store is a capability of MobileFirst Platform Foundation that allows secure, on-
device, offline storage of data retrieved from backend services through adapters, and synchronization of
data modified while offline with various systems of record that the adapters pull data from. We’ll use a
JSON store to store our data.
After you use the MobileFirst Studio to modify the code and run the updated IBMBank application in the
Mobile Browser Simulator, you will review the changes to the source code and explain how the Offers
feature was built.
Add the JSONStore Feature to the IBMBank Application
MobileFirst Platform Foundation allows you to specify optional features to include as part of an
application, which can be added or removed to tailor the final contents of your app depending on the
apps requirements. This is helpful as files included for features that are not being utilized will increase
the size of your app and cause the app to take longer to download.
__1. To enable the JSON Store database, open the apps/IBMBank folder and double click the
application-descriptor.xml file to open it. Highlight “Optional Features” under the Overview
section and click the Add… button.
14. IBM Software
Page 14 MobileFirst Platform Proof of Technology – “Offers” Lab
__2. In the “Add Item” dialog, select the JSONStore feature and click OK.
You’ll now see the JSONStore listed as an Optional Feature. Close the application_descriptor file.
Modify the IBMBank Application to Leverage the JSONStore
Now that the JSONStore feature has been added to the application you will modify the application logic
to utilize the JSONStore.
First you import two script files that have been written to support the Offers integration with the adapter
and the JSONStore.
15. IBM Software
MobileFirst Platform Proof of Technology – “Offers” Lab Page 15
1. Select the js folder located under “IBMBank/apps/IBMBankApp/common”. From the Eclipse
menu, File > Import… Select “File System” in the Import dialog and click Next.
In the next section Browse to: “C:MobileFirstLabsimportsoffers” and click OK. Then select
offersCollection.js and offersFunctions.js from the available options. Do not select any files
that begin with a dot and underscore, for example ._offersCollections.js, which may or may not
be present.
offersFunctions.js is a high-level set of data storage functions that sits between your IBMBank
application and the JSONstore implementation-specific functions in offersCollections.js. The
IBMBank app’s main.js will interface with the functions in offersFunctions.js, and
offersFunctions.js will interface with the lower level, JSONstore-specific logic in
offersCollection.js. Think of offersFunctions as providing a layer of abstraction between your app
and the JSONStore. That layer of abstraction means that you could later change the backing
data store from a local JSONstore to another solution, such as a local JavaScript data structure,
a remote database or a remote cloud data service with minimal changes to your app.
Click Finish to complete the import.
16. IBM Software
Page 16 MobileFirst Platform Proof of Technology – “Offers” Lab
2. The one function in offersCollection.js that you will interface with directly is initOffers().
initOffers() initializes the local JSON store collection used by the IBMBank app. You need that to
be executed once, on entry into the application.
Open main.js under “IBMBank/apps/IBMBankApp/common/js”. Locate the
WL.App.hideSplashScreen();
function, and copy & paste the initOffers(); function from Snippet
#1 in the offers.snippets.txt file (found in the C:MobileFirstLabsimportsoffers dir) into main.js,
immediately below the WL.App.hideSplashScreen();
function as follows:
Save and close main.js.
3. You will next need to add two pages to the index.html file to handle the Offers. Index.html is
located under the “IBMBank/apps/IBMBankApp/common” folder. Open the file and click on the
Source tab if it is not already selected.
Page down to just above the line reading <!-‐-‐
javascript
libraries
-‐-‐>
comment.
Copy & paste the code from Snippet #2 in the offers.snippets.txt file into index.html immediately
above the <!-‐-‐
javascript
libraries
-‐-‐>
comment. This code is the offers list and offers
details pages for displaying the offers that are retrieved from the MockService web service and
stored in the JSONStore.
17. IBM Software
MobileFirst Platform Proof of Technology – “Offers” Lab Page 17
4. The next modification to be made is to include the offersCollection.js and offersFunctions.js
files (imported as part of step 2 of this section) in the javascript library references in index.html.
At the bottom of the page, again find the following comment: <!-‐-‐
javascript
libraries
-‐-‐>
and copy & paste Snippet #3 from the offers.snippets.txt file immediately below the included
initOptions.js file. The included javascript libraries should now look like the following.
Save and close index.html.
5. Next we’ll add an onclick handler for the My Offers button on the Main Page. Open mainPage.js
and scroll to the bottom. Copy & paste Snippet #4 from the offers.snippets.txt file into the bottom
of this script file.
This handler does the transition to the myOffers page, and it also calls the doGetOffers function
that calls the SoapAdapter1 you created to retrieve offers from the MockService.
Save all edited files (Ctrl+s). You’re done with the first set of modifications and ready to test your work.
1.5 Test the Newly Modified IBMBank Application
Now that the modifications have been made to the IBMBank application you are ready to test the
enhancements that were added.
18. IBM Software
Page 18 MobileFirst Platform Proof of Technology – “Offers” Lab
__1. Right click the IBMBank app, under apps, not the IBMBank project, and select Run As > Run on
MobileFirst Development Server.
Wait for the “Application ‘IBMBank’ deployed successfully with with all environments” message in
the console.
__2. Right click on the android environment under the IBMBankApp folder, Run As > Preview.
b
__3. This will open the Mobile Browser Simulator and allow you to preview the application for the
android environment. If you encounter the following Java Security Warning click Allow.
19. IBM Software
MobileFirst Platform Proof of Technology – “Offers” Lab Page 19
__4. When the application initializes it will wait 2 seconds and then present a login screen. Enter
demo/demo as the username and password and click “Log In” to proceed to the main application
screen.
__5. On the Home screen, click the My Offers button. This will transition to the My Offers page
which invokes the MockService’s “OffersService” using the SOAP-based adapter created in the
beginning of this section.
20. IBM Software
Page 20 MobileFirst Platform Proof of Technology – “Offers” Lab
__6. On the My Offers page, you may notice that each individual offer contains a line item indicating
if an offer coupon is available while offline or online. Select the second offer in the list titled
“Two-for-Tuesday Pizza Special Campus Pies”. This will take you to the offer details page. On
that page select Add to Device from the bottom of the page. This will store the retrieved
contents in the JSONStore on the device for offline viewing.
__7. After the offer is stored you’ll transition back to the My Offers page and see that the icon for the
coupon indicator has changed to “Coupon available on device”. This informs the end user that
when the device is offline, they will be able to retrieve and leverage coupons downloaded to the
JSONStore directly from the device.
1.6 Review Code for the IBMBank Application
Now that you’ve seen it work let’s review how it works.
First let’s review the changes that you made to the IBMBank application to add the My Offers capability.
The first thing you did was add the JSONStore Feature to the IBMBank Application. This added the code
for JSONStore to the app when it was built.
21. IBM Software
MobileFirst Platform Proof of Technology – “Offers” Lab Page 21
Next you imported two script files that have been written to support the Offers integration with the
adapter you built and the JSONStore. Feel free to review that code now if interested.
Then you added the initOffers() function to the main.js file. This makes the calls to open the JSONStore
when the app starts.
Now lets look at the html changes.
Open index.html inside “IBMBankappsIBMBankAppcommon” folder switch to the Design tab and click
on the Eye icon next to mainPage inside the Mobile Navigation window in the bottom left corner of
Eclipse. Then click on the Split tab under the window displaying the code to show both the source and
display the rendered html. Then click the Vertical split button just above and to the left of the display
pane. (If you don’t see any items under mobile navigation pane be sure to display index.html using the
design tab).
22. IBM Software
Page 22 MobileFirst Platform Proof of Technology – “Offers” Lab
Turn on line numbering in the editor via the top menu bar in Eclipse and clicking Windows / Preferences /
General / Editors / Text Editors and check Show Line Numbers. Click OK.
Inside Index.html, scroll down in the Source view of the page to the line <!-‐-‐
offers
page
-‐-‐>. This
will be about line 193.
You added the Offers Page and the Offers Details page below it.
23. IBM Software
MobileFirst Platform Proof of Technology – “Offers” Lab Page 23
Finally click on the My Offers button in the display.
This will highlight the code for that button in the source pane. This is this button that triggers the
transition to the My Offers page, which you tested when running the app in preview mode. You did not
add or change this, but it’s useful to see it now.
The last thing you did was add the click handler for the My Offers button on the Main Page in
mainPage.js.
24. IBM Software
Page 24 MobileFirst Platform Proof of Technology – “Offers” Lab
This handler does the transition to the myOffers page, and it also calls the doGetOffers function that calls
the SoapAdapter1 you created to retrieve offers from the MockService.
Now let’s review how the application works. In mainPane (inside mainPage.js) double click the call to the
doGetOffers (do not include the open and closing parentheses of the function call)function to highlight it
in blue. Then from the menu bar select Search / Text / Workspace.
The Search pane will update to show you all the references to that function. Minimize the android branch
of the tree and expand the common branch.
The doGetOffers function is defined in the offersFunctions.js file. In the Search window double click
the “function doGetOffers(){“ entry to open the offersFunctions.js file to that definition. Within the
function you will find a call to the SOAP adapter created earlier in this section.
25. IBM Software
MobileFirst Platform Proof of Technology – “Offers” Lab Page 25
Note the callback which is invoked after a response is received for success or failure conditions called
doGetOffersFinish.
Scroll down to the start of the definition of the doGetOffersFinish
callback function, line 59 approx.
This callback function parses the results returned from invoking the SOAP adapter and stores the offers
in an array called offerArray. At the bottom of the function, it does a check on the offerArray to see
if it has any items in it, if so it will build a list of the offers to present as part of the user interface by calling
buildOffersList. And it checks to see if any of the offers returned are already stored in the local
JSONStore and flags them as such.
After building a list of the offers the app changes pages to offersPage and shows a list item populated
with each individual offer and details on whether or not it has been stored locally in the JSONStore
database for offline viewing.
Clicking on an individual offer shown in the offers list will let you view details about the offer on the
offerDetailsPage. The showOffer(idx) function (line 202 approx) builds the contents displayed on
the offerDetailsPage, and defines the click handler for the button that allows the end user to either
store the coupon associated with an offer locally in the JSONStore database for offline viewing or delete
it from the store.
For example, the click handler invokes importOffer.
26. IBM Software
Page 26 MobileFirst Platform Proof of Technology – “Offers” Lab
And importOffer calls the addOffer function in the offersCollection.js file that you imported into the
project, which actually adds an offer to the JSONStore.
Using importOffer to call addOffer in the offersCollection.js file provides a layer of encapsulation that
“future proofs” your app. If in the future the JSONStore interface changes or you decide to use a
different local storage technique then all the necessary changes are isolated to the functions like
addOffer in the offersCollection file. The rest of your app does not have to be modified.
Feel free to review the remaining functions in offersCollection.js to understand how items are added,
removed and retrieved using the JSONStore in this example exercise.
1.7 Adding the Capability to View Locally Stored Offers Without
Logging On
What happens if you want to redeem a coupon (an offer) stored on your device but you don’t have good
connectivity so you can’t log on to the app, which needs to access the back end server to authenticate
you? As extra credit let’s explore adding a page to allow you to display the locally stored coupons
without a log on.
1. The first thing to do is add a new button to the Log In page that will take you to the Offers page,
which will display the offers stored locally when you are not logged on to the server.
Open the index.html file in the editor by double-clicking the file index.html in the Project Explorer
view. Then, navigate to the loginPage by clicking on the ellipse next to loginPage in the Mobile
Navigation view.
27. IBM Software
MobileFirst Platform Proof of Technology – “Offers” Lab Page 27
In the main editor of the index.html, make sure that the Design view is selected. On the right
palette pane expand the jQuery Mobile Widgets tools entry. Select the Button widget and drag it
from the palette onto the page immediately below the Log In button.
Double click the new button in the Design view and change the label to My Stored Offers.
In the Properties view change the ID to myStoredOffersBtn.
28. IBM Software
Page 28 MobileFirst Platform Proof of Technology – “Offers” Lab
Also in the Properties view, click the styles tab and change the background color to teal to make it stand
out.
Your button should now look something like this.
Switch to the source view to see the code created, which will look like this.
<a
href="#"
data-‐role="button"
id="myStoredOffersBtn"
style="background-color:
green">My
Stored
Offers</a>
Save and close index.html
2. Next you’ll add a click handler for that button. From the Project Explorer, navigate to the common/js folder
and open loginPage.js, scroll to the bottom, and copy & paste Snippet #5 from the offers.snippets.txt
file into the bottom of this script file.
Verify that the button name registered, myStoredOffersBtn, matches the ID you gave your button above.
Save and close loginPage.js.
29. IBM Software
MobileFirst Platform Proof of Technology – “Offers” Lab Page 29
3. This button calls a new function called doDisplayStoredOffers. Next you’ll add that function to
offersFunctions.js. This function will only attempt to retrieve the locally stored offers. The function is
defined in snippet 6.
• Open offersFunctions.js and scroll down to line that reads function
buildOffersList()
{,
line
155
approx.
• Copy
and
paste
Snippet #6 from the offers.snippets.txt file immediately
above
that
line.
Save and close offersFunctions.js. You’re now ready to test the app and display stored offers without
logging on to the app and server.
1.8 Test the Capability to View Locally Stored Offers Without
Logging On
Now that the modifications have been made to the IBMBank application you are ready to test the
enhancements that were added.
1. Right click on the android environment under the IBMBankApp folder, Run As > Preview.
2. This will open the Mobile Browser Simulator and allow you to preview the application for the
android environment. If you encounter the following Java Security Warning click Allow.
30. IBM Software
Page 30 MobileFirst Platform Proof of Technology – “Offers” Lab
3. When the application initializes it will wait 2 seconds and then present a login screen. On the
login screen click My Stored Offers. The app will display the locally stored offers. If none display
it’s probably because you did not leave any in the local store when you last ran the app. To
remedy this, return to the login screen, log in, go to My Offers and store one or both offer locally.
Then return to the login screen and click My Stored Offers.
Congratulations. You have completed the Offers Lab!