For up-to-date product documentation, see the IBM MobileFirst Foundation Developer Center.


Customizing the Direct Update user interface and process

We can change the default user interface for the Direct Update dialog boxes and the messages that are displayed to the user.

We can control the direct update process without presenting a user interface to the user and control what happens when the direct update process fails.

Override the handleDirectUpdate function of the Direct Update challenge handler to customize the direct update process and interface in iOS and Android applications. The handleDirectUpdate function is defined inside worklights.js. It has the following format:

wl_directUpdateChallengeHandler.handleDirectUpdate = function (directUpdateData,directUpdateContext){...}

The function accepts the following arguments:

directUpdateData
A JSON object that contains the downloadSize property that represents the files size in bytes of the update package to be downloaded from server.
directUpdateContext
A JavaScript object that exposes a .start() and .stop() function that start and stop the Direct Update flow.

If the web resources are newer on the MobileFirst Server than in the application, Direct Update challenge data is added to the server response. Whenever the MobileFirst client-side framework detects this direct update challenge, it invokes the wl_directUpdateChallengeHandler.handleDirectUpdate function.

The function provides a default Direct Update design: a default message dialog that is displayed when a Direct Update is available and a default progress screen that is displayed when the direct update process is initiated. For examples of default screens, see Default Direct Update user interface. We can implement custom Direct Update user interface behavior or customize the Direct Update dialog box by overriding this function and implementing your own logic.

The following example handleDirectUpdate function implements a custom message in the Direct Update dialog. Add this code into the www/js/index.js file of the Cordova project .

wl_directUpdateChallengeHandler.handleDirectUpdate = function(directUpdateData, directUpdateContext) { navigator.notification.confirm( // Creates a dialog. 'Custom dialog body text', // Handle dialog buttons. directUpdateContext.start(); }, 'Custom dialog title text', ['Update'] ); };

The result is shown in Figure 1.

Figure 1. Custom update notice

Custom UI for Direct Update.

We can start the direct update process by running the directUpdateContext.start() method whenever the user clicks the dialog button. The default progress screen, which resembles the one in previous versions of MobileFirst Server is shown.

This method supports the following types of invocation:

The listener methods are started during the direct update process according to following rules:

If you implement a custom direct update listener, we must ensure that the app is reloaded when the direct update process is complete and the onFinish() method has been called. You must also call wl_directUpdateChalengeHandler.submitFailure() if the direct update process fails to complete successfully.

The following example shows an implementation of a custom direct update listener:

var directUpdateCustomListener = { onStart: function(totalSize){ //show custom progress dialog }, onProgress: function(status,totalSize,completedSize){ //update custom progress dialog }, onFinish: function(status){ if (status == 'SUCCESS'){ //show success message WL.Client.reloadApp(); } else { //show custom error message //submitFailure must be called is case of error wl_directUpdateChallengeHandler.submitFailure(); } } }; wl_directUpdateChallengeHandler.handleDirectUpdate = function(directUpdateData, directUpdateContext){ WL.SimpleDialog.show('Update Avalible', 'Press update button to download version 2.0', [{ text : 'update', handler : function() { directUpdateContext.start(directUpdateCustomListener); } }]); };


Scenario: Running UI-less direct updates

IBM MobileFirst Platform Foundation supports UI-less direct update when the application is in the foreground.

To run UI-less direct updates, implement directUpdateCustomListener. Provide empty function implementations to the onStart and onProgress methods. Empty implementations cause the direct update process to run in the background.

To complete the direct update process, the application must be reloaded. The following options are available:

Here is an example implementation of directUpdateCustomListener:

var directUpdateCustomListener = { onStart: function(totalSize){ }, onProgress: function(status,totalSize,completeSize){ }, onFinish: function(status){ WL.SimpleDialog.show('New Update Available', 'Press reload button to update to new version', [ { text : WL.ClientMessages.reload, handler : WL.Client.reloadApp }]); } };

Implement the wl_directUpdateChallengeHandler.handleDirectUpdate function. Pass the directUpdateCustomListener implementation that you have created as a parameter to the function. Make sure directUpdateContext.start(directUpdateCustomListener) is called. Here is an example wl_directUpdateChallengeHandler.handleDirectUpdate implementation:

wl_directUpdateChallengeHandler.handleDirectUpdate = function(directUpdateData, directUpdateContext){ directUpdateContext.start(directUpdateCustomListener); };

Note: When the application is sent to the background, the direct-update process is suspended.


Scenario: Handling a direct update failure

This scenario shows how to handle a direct update failure that might be caused, for example, by loss of connectivity. In this scenario, the user is prevented from using the app even in offline mode. A dialog is displayed offering the user the option to try again.

Create a global variable to store the direct update context so that we can use it subsequently when the direct update process fails. For example:

var savedDirectUpdateContext;

Implement a direct update challenge handler. Save the direct update context here. For example:

wl_directUpdateChallengeHandler.handleDirectUpdate = function(directUpdateData, directUpdateContext){ savedDirectUpdateContext = directUpdateContext; // save direct update context var downloadSizeInMB = (directUpdateData.downloadSize / 1048576).toFixed(1).replace(".", WL.App.getDecimalSeparator()); var directUpdateMsg = WL.Utils.formatString(WL.ClientMessages.directUpdateNotificationMessage, downloadSizeInMB); WL.SimpleDialog.show(WL.ClientMessages.directUpdateNotificationTitle, directUpdateMsg, [{ text : WL.ClientMessages.update, handler : function() { directUpdateContext.start(directUpdateCustomListener); } }]); };

Create a function that starts the direct update process by using the direct update context. For example:

restartDirectUpdate = function () { savedDirectUpdateContext.start(directUpdateCustomListener); // use saved direct update context to restart direct update };

Implement directUpdateCustomListener. Add status checking in the onFinish method. If the status starts with "FAILURE", open a modal only dialog with the option "Try Again". For example:

var directUpdateCustomListener = { onStart: function(totalSize){ alert('onStart: totalSize = ' + totalSize + 'Byte'); }, onProgress: function(status,totalSize,completeSize){ alert('onProgress: status = ' + status + ' completeSize = ' + completeSize + 'Byte'); }, onFinish: function(status){ alert('onFinish: status = ' + status); var pos = status.indexOf("FAILURE"); if (pos > -1) { WL.SimpleDialog.show('Update Failed', 'Press try again button', [ { text : "Try Again", handler : restartDirectUpdate // restart direct update }]); } } };

When the user clicks the Try Again button, the application restarts the direct update process.

Parent topic: Updating Cordova client apps directly