IBM MobileFirst Platform v7.0 POT Offers Lab v1.0

IBM Software WebSphere

An IBM Proof of Technology

“Offers”Lab

Adding a mobile coupons feature to the IBMBank application Lab Exercises

An IBM Proof of Technology

Catalog Number

© Copyright IBM Corporation, 2013

US Government Users Restricted Rights - Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

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

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.

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:\MobileFirstLabs\workspaces\offers 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.

IBM Software


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:\MobileFirstLabs\imports\offers\IBMBank_offers_import.zip and click Open.

IBM Software


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”.

IBM Software


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.

IBM Software


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.

IBM Software


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:\MobileFirstLabs\imports\setup 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.

IBM Software


__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.

IBM Software


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.

IBM Software


__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.

IBM Software


__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.

IBM Software


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:\MobileFirstLabs\imports\offers” 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.

IBM Software


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:\MobileFirstLabs\imports\offers 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.

IBM Software


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.

IBM Software


__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.

IBM Software


__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.

IBM Software


__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.

IBM Software


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 “IBMBank\apps\IBMBankApp\common” 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).

IBM Software


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.

IBM Software


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.

IBM Software


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.

IBM Software


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.

IBM Software


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.

IBM Software


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.

IBM Software


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.

IBM Software


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.

IBM Software


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!

Education

IBM MobileFirst Platform v7.0 POT Offers Lab v1.0