Looking at the JavaScript API in Hybrid MobileFirst Apps

I've been blogging lately about hybrid apps and MobileFirst, and today I thought I'd start investigating the JavaScript client-side API portion of the product. These are API methods you have available to you in your hybrid application. For today, I'm going to focus on the WL.App namespace.

Here are the (non-deprecated) methods of WL.App, along with some thoughts and suggestions on how you could possibly use them in your application.

getDeviceLanguage/getDeviceLocale

The first returns the language code, not the name, so for me it would be en, not English. Locale will also be the code, so en_US for example. So how does this compare to the Globalization API? The biggest difference is that these are synchronous, which to me seems to make a bit more sense.

getServerUrl/setServerUrl

These get and set the MobileFirst server url. I don't imagine there are often times when you would want to set the URL, but perhaps for testing purposes you may want to switch the URL being used on the fly. I could see the getter then being used to provide feedback about which server is currently being used. Make note that the API here uses Url in the method names. Later on you will see a method using URL.

hideSplashscreen/showSplashscreen

I've already talked a bit about this in regards to bootstrapping an Ionic application under MobileFirst.

overrideBackButton/resetBackButton

Only applicable to Android and Windows Phone 8, this lets you change the behavior of the device back button. Having a reset there is handy to quickly go back to the system default.

openURL

So yes - this is URL not Url! This opens up a new browser to a particular URL. There's options you can pass in (see full docs here) but they don't apply to Android and iOS. Note that this does not work like the InAppBrowser. This opens the system browser as a new activity. On Android you can hit Back to return to the app, but on iOS you would need to return to the app using the double click/select behavior. (That I don't think many users really know about.) I think in most cases you will probably want InAppBrowser instead, but this is another option.

BackgroundHandler.setOnAppEnteringBackground / BackgroundHandler.setOnAppEnteringForeground

Note that these methods are on the BackgroundHandler object (so the full API is WL.App.BackgroundHandler.etc). These two methods are iOS only but are really freaking neat. When an app is put in the background, iOS takes a snapshot of the current view. This could be a security issue since sensitive information may be on the screen. By using these events, you can hide/show sensitive information so it doesn't show up when the user is viewing running apps in the background. You can either specify a custom function (to hide specific items) or tell the handler to just blank it out.

Here is a screenshot. Note that the scratch app is blanked out.

addActionReceiver/removeActionReceiver/sendActionToNative

Now - this is cool one. Typically when you want to use native code, you have to build a plugin. Plugins are necessarily difficult to write, but you may not necessarily want to go that far for everything you do. MobileFirst's client-side API provides a simpler solution. You can use sendActionToNative to send a message to your native code. Your native code can then do... whatever. There's a reverse to this as well. You can tell your hybrid app to listen in for actions sent from the native side and react appropriately. As an example, imagine this within your JavaScript:

var data = {someproperty:1234};
WL.App.sendActionToNative("doSomething", data);

Then on the native side - you can listen for it and do something:


-(void) onActionReceived:(NSString *)action withData:(NSDictionary *) data {
    NSLog(@"The action receiver");
    if ([action isEqualToString:@"doSomething"]){
        NSLog(@"Yes, doing it");
        
        UIAlertView *alert = [[UIAlertView alloc] initWithTitle:@"Wait" message:@"Are you sure you want to delete this.  This action cannot be undone" delegate:self cancelButtonTitle:@"Delete" otherButtonTitles:@"Cancel", nil];
        [alert show];        
        
    }
}

As you can see, you can listen for the action string and do something with it. You could also handle the args sent to it. In my example I just open an alert (which, to be clear, you do not need to do this way, just use the Dialogs plugin) but I could do pretty much anything here. And again - I could broadcast back to the JavaScript code as well. For times when you don't want a full plugin and just need to quickly talk to the native side, this is a pretty cool option.

Raymond Camden