You finished creating the front-end for your application, and it has mobile support. You would now like to provide native client applications that your users can download from an application store. After reading this tutorial, you will understand how to reuse the existing HTML5 code for create native mobile clients for each target platform with Apache Cordova.

You will learn how to:

Hybrid mobile applications are developed in HTML5 - unlike native applications that are compiled to platform-specific binaries. The client code - which consists exclusively of HTML, CSS, and JavaScript - is packaged and installed on the client device just as any native application, and executes in a browser process created by a surrounding native shell.

Besides wrapping the browser process, the native shell also allows access to native device capabilities, such as the accelerometer, GPS, contact list, etc., made available to the application through JavaScript libraries.

In this example, we use Apache Cordova to implement a hybrid application using the existing HTML5 mobile front-end for TicketMonster, interacting with the RESTful services of a TicketMonster deployment running on JBoss A7 or JBoss EAP.

Before we make the application hybrid, we need to make some changes in the way in which it accesses remote services. Note that the changes have already been implemented in the user front end, here we show you the code that we needed to modify.

In the web version of the application the client code is deployed together with the server-side code, so the models and collections (and generally any piece of code that will perform REST service invocations) can use URLs relative to the root of the application: all resources are serviced from the same server, so the browser will do the correct invocation. This also respects the same origin policy enforced by default by browsers, to prevent cross-site scripting attacks.

If the client code is deployed separately from the services, the REST invocations must use absolute URLs (we will cover the impact on the same-origin policy later). Furthermore, since we want to be able to deploy the application to different hosts without rebuilding the source, it must be configurable.

You already caught a glimpse of this in the user front end chapter, where we defined the configuration module for the mobile version of the application.

This module has a baseURL property that is either set to an empty string for relative URLs or to a prefix, such as a domain name, depending on whether a global variable named TicketMonster has already been defined, and it has a baseRESTUrl property.

All our code that performs REST services invocations depends on this module, thus the base REST URL can be configured in a single place and injected throughout the code, as in the following code example:

The prefix is used in a similar fashion by all the other modules that perform REST service invocations. You don’t need to do anything right now, because the code we created in the user front end tutorial was written like this originally. Be warned, if you have a mobile web application that uses any relative URLs, you will need to refactor them to include some form of URL configuration.

Hybrid Mobile Tools and CordovaSim are not installed as part of JBoss Developer Studio yet. They can be installed from JBoss Central as shown below:

Once installed, you must inform Hybrid Mobile Tools of the Android SDK location before you can use Hybrid Mobile Tools actions involving Android.

To set the Android SDK location, click Window → Preferences and select Hybrid Mobile. In the Android SDK Directory field, type the path of the installed SDK or click Browse to navigate to the location. Click Apply and click OK to close the Preferences window.

The Hybrid Mobile tooling requires that the cordova.js file be loaded in the application’s start page. Since we do not want to load this file in the existing index.html file, we shall create a new start page to be used only by the Cordova app.

Let’s now modify the Hybrid Mobile project configuration to use this page as the application start page. Additionally, we will add our REST service URL to the domain whitelist in the config.xml file (you can use "*" too, for simplicity, during development) :

Next, we need to load the library in the application. We will create a separate module, that will load the rest of the mobile application, as well as the Apache Cordova JavaScript library for Android. We also need to configure a base URL for the application. For this example, we will use the URL of the cloud deployment of TicketMonster.

The above snippet of code contains a device-specific check for iOS 7.

Finally, we’ll configure the loader module launched from mobileapp.html to use the above defined hybrid module:

In the above code snippet, we detect if the URL of the page contains mobileapp.html or not, and then proceed to activate the hybrid module if so. Since Apache Cordova is configured to use mobileapp.html as the application start page, the desired objective is achieved. This way, we avoid loading the mobile or desktop modules that do not have any logic in them to detect the deviceready event of Cordova.

The final step will involve adjusting src/main/webapp/resources/js/configurations/loader.js to load this module when running on Android, using the query string we have already configured in the project. We’ll also tweak src/main/webapp/resources/js/app/utilities.js to use the Notification plugin to display alerts in the context of a Hybrid Mobile app.

We’ll now examine the displayAlert function in the utilities object. It is set to use the Notification plugin when available:

The function automatically works in non-mobile environments due to the absence of the navigator.notification object in such environments.

You are now ready to run the application. The hybrid mobile application can be run on devices and simulators using the Hybrid Mobile Tools.

This concludes our tutorial for building a hybrid application with Apache Cordova. You have seen how we have turned a working HTML5 web application into one that can run natively on Android and iOS.