Surviving the Mobile Data Offline Blues

Use Oracle Mobile Cloud Service Sync Express offline data capabilities in your JavaScript mobile applications.

By Chris Muir

September/October 2017

Experiencing zero connectivity when you use mobile applications is exceedingly annoying, but a more frustrating experience might be connectivity that keeps dropping in and out, causing mobile apps to stutter and fail without an always-on data connection. Adding the ability for apps to cache data when connected, and rely on the cache when disconnected, allows for a much smoother user experience.

Fetching and maintaining data in the local cache is a significantly different coding challenge from just fetching remote data. Building code to store and maintain data in a cache can be a time-consuming and complex task. Ideally, mobile developers would flip a switch and this caching would happen automatically.

With its JavaScript and Apache Cordova SDKs, Oracle Mobile Cloud Service provides mobile developers with this exact switch, known as Sync Express. Sync Express is an extension to the JavaScript and Cordova SDKs that—when turned on (“flipped”) and configured for a remote REST API—will cache the data on the mobile client, without requiring extra coding.

In this article, you will use an example application to explore how to configure an existing Oracle JavaScript Extension Toolkit (Oracle JET) application to make use of the Oracle Mobile Cloud Service Sync Express feature. The example application is one you’ve used in previous Oracle Magazine articles: a simple employees’ phone book application that gets its data from a remote API hosted by Oracle Mobile Cloud Service.

Setup

For the article, you will first need to install Oracle JET. The Oracle JET documentation covers this task in detail; follow the instructions for installing both the web and mobile tooling components.

Note for this article that the steps assume you are developing on a Microsoft Windows PC and deploying to the Android Emulator on a PC.

After installing Oracle JET, you need to configure Oracle Mobile Cloud Service. This article is based on exactly the same setup instructions from the January/February 2017 Oracle Magazine article “Too Much of a Good Thing.” Perform Step 1 through Step 8 under the “Deploying a Running Demo Application” section of that article; however, use the demo download file for this article instead of the download file provided in Step 1 of the earlier article. These steps will configure the required Oracle Mobile Cloud Service remote APIs for the mobile application you will see in a moment, supplying the employee details for the employees’ phonebook app.

You must also enable cross-origin resource sharing (CORS) for the Oracle Mobile Cloud Service server:

From the hamburger menu, select Administrator.
In the Policies section, click the Export button. This will download a policies .properties file to your desktop.
Open this file in your favorite text editor.

Locate the following line:

*.*.Security_AllowOrigin=disallow

Replace the line with the following:

*.*.Security_AllowOrigin=http://10.0.2.2:8000, http://localhost:8000

Save the file, and in the Oracle Mobile Cloud Service user interface, click the Import button to import the modified file.

With Oracle Mobile Cloud Service artifacts set up, let’s create the basic Oracle JET application scaffold.
Via the command line, type the following:
```
cd
cd Desktop
mkdir test
cd test
yo oraclejet:hybrid OraMagDemo --template=navbar --platform=android
cd OraMagDemo
rd /s src
```
This creates the application scaffold. Note that you just deleted the src directory of the application, leaving the raw scaffold for adding new code.
Now download the prebuilt application source code zip file and unzip it. Copy the unzipped src directory into the OraMagDemo directory using Windows Explorer.
Within the unzipped src directory, locate and open the src/js/mcsconfig.js file in a text editor, and from the “Too Much of a Good Thing” article’s steps, copy the values from Step 5 to Step 8 into the mcsconfig.js file’s annotated locations. Then save the file.

Testing the Vanilla App

With the previous steps completed, you are now ready to test the vanilla application before you include Sync Express.

Issue the following command in the command-line window:
```
grunt serve --platform=android
```

The application runs and displays the employees’ data extracted from the remote Oracle Mobile Cloud Service API.

One feature of the app is the pull-to-refresh-the-list view. Data on the screen is updated via another remote call to the Oracle Mobile Cloud Service custom API. Because the employees’ details don’t change frequently, refreshing the data won’t often result in a visible change to the list. But in a moment, when you start to refresh the data when the app is online and offline, you will need a way to see when fresh data is coming down from the server.

To present this fresh data, I’ve “hacked” the Oracle Mobile Cloud Service remote API that I provided and mapped the phone numbers to the current time in milliseconds and incremented each number by the record ID value. As such, each time you refresh the list view, the server updates all the phone numbers of all the employees, and this proves the data is getting updated via the server at each refresh, in turn proving your mobile device is currently online.

Now let’s watch what happens when you switch from online to airplane mode, and the app can no longer access the remote API provided by Oracle Mobile Cloud Service.

In the Android Emulator, turn on airplane mode. Do this by swiping down the menu bar of the Android Emulator and selecting the airplane icon. Then swipe the menu back up and return to the app.
Pull to refresh the list view again, and note that now when the app attempts to refresh the list view, unsurprisingly, the app can no longer fetch fresh data. Depending on the operating system version, this attempt might eventually time out and crash or continue indefinitely. Obviously this isn’t what you want. You want the application to continue to run during offline use and, preferably, default back to showing the previously fetched data rather than getting stuck.

This is where Sync Express comes in. It will provide these offline capabilities with minimal effort.
Before you proceed, switch the Android Emulator airplane mode off, terminate the Android Emulator, and in the command window press the Ctrl and C keys simultaneously to kill the running process.

Adding Sync Express

There are three steps you must complete to utilize Sync Express in this app.

First, add a script element to the HTML file to load the associated mcs.sync.js library that contains the Sync Express functionality. This file must be the first script the app fetches and loads. Typically, in an Oracle JET app, you would use RequireJS to load the other JavaScript libraries, but the Sync Express library needs to work at a lower level than that so it can capture all remote HTTP calls. That’s why you need to add it to the main index.html page as the first script to run.

Open the src/index.html file in your favorite text editor.
Within the HTML head tag, where annotated, add the following script tag at the end of the <head> tag:
```
<script type="text/javascript" src="js/mcs.sync.js">
</script>
```

The tag refers to the js/mcs.sync.js library, and for this article, I’ve taken a shortcut and provided the library for you in the src directory you copied over earlier from the downloaded zip file. Typically, this JavaScript library is downloaded from Oracle Mobile Cloud Service as part of the JavaScript or Cordova SDK.

Now add the Cordova Network Information plugin to give the sync library the ability to know if the app and device are online or not.

In the same command window, execute the following commands:

cd hybrid
cordova plugin add cordova-plugin-network-information

Now configure the Cordova SDK to specify which remote APIs to cache data from when fetched. You do this through the mcsconfig options you pass to the Cordova SDK when you first initialize it. In the mcsconfig options of the src/mcsconfig.js file you modified earlier, add a new element—syncExpress—at the end, including a policies element and a path element with every path you want Sync Express to cache data from.

For this specific use case, add the following to the end of the mcsconfig object definition (including the opening comma):

 ,"syncExpress": {
      "policies": [
        {
          "path": '/mobile/custom/hr/employees/:employeeId(\\d+)?'
        }
      ]
    }

You’ve added a path from the Oracle Mobile Cloud Service custom API URL for fetching phone book data from /mobile/custom/hr/employees/:employeeId.

Note the syntax in the path example: a colon followed by “employeeId.” This implies “employeeId” is a variable part of the URL path and does change. In addition, the question mark indicates the employeeId is optional, implying sometimes it will just fetch all the employees, as it is doing for this app. Finally, the odd syntax inside the parentheses—two backslashes, “d,” and a plus mark—says the employeeId is a decimal rather than a string (the default). If it is a string, you can drop this notation.

Having configured Sync Express, what do you have to do with the code to make it work with Sync Express?

Nothing. As long as you include in the mcsconfig.js file the paths you want to cache, under the covers Sync Express intercepts HTTP calls and will automatically cache the data for you when it is first returned from the server.

Let’s look at the outcome.

Execute the following in the command-line window to redeploy the app to the Android Emulator:
```
cd ..
grunt serve --platform=android
```

Once the app has been redeployed and started, it initially fetches data from the server because the device is online. Now switch to airplane mode to move the device and the app offline, and refresh the data again by performing a pull. Rather than getting stuck at the refresh screen, the app’s call to fetch the remote data returns the previously cached data instead. Now switch out of airplane mode and again pull to refresh the data. The data—pulled from the server—starts updating because the device is online again.

Summary

Oracle Mobile Cloud Service Sync Express allows you to quickly add offline capabilities to your mobile applications. As you’ve seen in this article, the name “Sync Express” fits the feature well, because adding it to your mobile apps is a relatively painless and turnkey-like process that doesn’t require you to extensively modify your source code.

Next Steps

WATCH Oracle Mobile Cloud Service YouTube training.

TRY Oracle Mobile Cloud Service.

Photograph by iStock.com/ottawa