In this article we are going to learn the process of packaging a jQuery Mobile Application with Cordova / Phonegap. The application that we will use in the article is the Meeting Room Manager app that we’ve been building over the past months.

While we haven’t finished developing the Meeting Room Manager app (only the user registration features are completed at this point), I want to show you how to convert it from a mobile web app to a native hybrid app that you can deploy to a device.

In this article we will focus on deploying to an Android device. We will perform an iOS deployment in a follow-up article.

A Short Introduction to Cordova

Apache Cordova is an open-source mobile development framework where you use HTML, CSS and JavaScript to create mobile applications targeting multiple mobile operating systems.

The web applications that you build with Cordova run inside native applications called wrappers, that are targeted to each mobile platform. Cordova uses standard-compliant API bindings to expose different features of the mobile devices – for example, sensors, data and network status – to your application.

The main benefit of using Cordova is that it allows you to use JavaScript, HTML and CSS to develop mobile applications that can run on multiple platforms, bypassing the respective programming languages of each platform.

However, you trade this ease of development for a degraded user experience. The reason is that you are ultimately running a web application on a mobile browser, and mobile browsers have performance and other limitations in their integration with the native features of the device.

Setting Up the Cordova Development Environment

I developed this particular example on a Windows PC. I used Cordova version 4.0.0. I performed the following steps to get ready to develop with Cordova,:

If you haven’t set up your Cordova development environment yet, you should follow the detailed installation instructions found in the Command-Line Interface section of the Cordova documentation.

Creating a Cordova Project

Let’s move on to the more interesting parts of the tutorial. We are going to get started by creating a Cordova project.

The project’s directory where we created our Meeting Room Manager jQuery Mobile web application currently looks like this:

We are going to navigate to the project’s directory, open a command window and type the command that creates a Cordova project:

> cordova create cordova-project com.miamicoder.bookit BookIt

The command will create the cordova-project directory within the project’s directory:

In the cordova-project directory we will find a boilerplate web-based application with a www subdirectory that contains the application’s home page, located in the index.html file.

The www subdirectory itself contains the css, js, img and other subdirectories that hold various project assets. These resources will be stored on the device’s local file system when the application is packaged and deployed.

The config.xml file contains the project metadata that Cordova uses to generate and distribute the application. Let’s open the file and edit the description and author nodes:

Adding Target Platforms to a Cordova Project

We need to specify one or more target platforms to build a Cordova project. In this article we are targeting just the Android platform. To add it to the project, we need to open a command window in the cordova-project directory and type the following command:

c:\cordova-project>cordova platform add android

Be mindful that your computer must support and have installed the target platform’s SDK. We should not have a problem with this requirement because we installed the Android SDK earlier.

You can check the installed platform(s) by running the following command:

c:\cordova-project>cordova platforms ls

Running the Boilerplate Cordova Application

The following command builds the skeletal Cordova application that we just created:

A successfuld build will generate a message similar to the screenshot below:

We can run the boilerplate app on an emulator or a device. We will use the Genymotion Emulator in this tutorial prior to testing on an actual device.

I highly recommend Genymotion to speed up the testing phase of your applications. This emulator provides an experience that’s very close to a physical device. It’s also very fast to load, as opposed to the emulators that come with the Android SDK.

Once the Genymotion virtual device is running, use the following Cordova command to view the application in the virtual device:

cordova run android

The command will build the app and deploy it to the connected device, which in this case is Genymotion’s. On the device, the app should look like this:

Migrating a jQuery Mobile App to a Cordova Project

At this point we have our starter Cordova project set up and we can focus on migrating our jQuery Mobile application into it. The migration will consist of these steps:

Move the jQuery Mobile pages that today exist in their own separate html files over to the index.html file in the Cordova project.

Migrate the JavaScript files located under the project’s js directory over to the cordova-project/www/js directory.

Move the CSS files located the project’s CSS files from the CSS directory to the cordova-project/www/css directory.

Adding the jQuery Mobile References

We will start the jQuery Mobile pages migration by opening the cordova-project/www/index.html file and adding the references to the jQuery Mobile library’s CSS file, as well as our and our app’s CSS file, in the head section of the html page:

Then, we need to open the cordova-project/www/index.html file and replace the div element in the document’s body with the html above. After you paste the code, modify the value of the page’s id attribute so it becomes page-index. Also, add the data-position and data-tap-toggle attributes to the page’s header as shown below:

Creating the Controller Module

As a third step, we are going to refactor the code in the index.js file. What we want is to create JavaScript Classes that will implement different features of the app, starting with the user signup feature.

The features’ core logic will reside in these Classes, separate from each other and from the jQuery Mobile page lifecycle events.

This change will make the application more maintainable. It will be easier for multiple developers to work on different areas of the app, and it will be easier to create unit tests for the different features.

We will start the refactoring of the signup code by creating the the signup-controller.js file in the cordova-project/www/js directory:

The $signUpPage, $btnSubmit, $ctnErr, $txtFirstName, $txtLastName, $txtEmailAddress, $txtPassword and $txtPasswordConfirm variables will hold references to the html elements in the jQuery Mobile page that contains the signup form.

Moving on to the implementation of the Class, we first are going to add the init method:

Note how we implemented this Class so it doesn’t have any direct ties to the jQuery Mobile page lifecycle events, or to the jQuery Mobile page that contains the Sign Up form. Its only connection with the page is indirect, through the variables that hold references to the html elements of the form.

Modifying the Index.js File

Now we are going to turn our attention to the cordoba-project/www/js/index.js file, where we need to invoke the SignUpController Class that we just created. At this point, this file only contains the starter code generated when we created the Cordova project.

The first block of code in the file is part of the boilerplate code that was already there, generated when we created the Cordova project. We will leave it in place for now.

After the boilerplate code, we use the mobileinit handler to set the jQuery Mobile application’s default page transition to slide. I think that the slide transition gives the navigation a more native feel:

We use the pagecontainerbeforeshow event to reset the fields of the signup form. It’s possible for a user to visit this page multiple times. For security reasons, we want to clear any prior entries before we show the form to the user.

The second page event that we want to intercept is the beforecreate event:

We use the pagebeforecreate event to hook our tap handler for the Submit button. The handler invokes the SignUpController’s onSignupCommand method, which validates the user’s input, sends the registration request to the server and processes the server’s response.

This concludes the migration of the application’s core logic over to the Cordova project. We also moved the input validation and user registration logic into the SingUpController Class, in the signup-controller.js file. We left the logic that hooks the jQuery Mobile page events in the index.js file. This logic invokes the SignUpController’s methods as needed.

Let’s test the app to make sure the user signup process works.

Choices for Testing a Cordova App

I prefer to test my Android apps using either Ripple (double-check the link, I noticed that it changes over time), GenyMotion, or my own development devices. In this article I will show you how to test with GenyMotion and your own device.

Testing a Cordova Application with GenyMotion

To test your application with GenyMotion, follow these steps:

Install and configure GenyMotion. Then, add the virtual devices that you want to test the app on. The instructions on how to do this are available in GenyMotion’s Dev Zone.

Start the GenyMotion virtual device that you want to test on.

Start your MongoDB instance if it isn’t already running.

Open a command window in the [project root]/server directory and run the following command to start your Express Server:

node index.js

Open acommand window and run the following Cordova command to build and deploy the application to the virtual device:

cordova run android --device

When the last step finishes, the application will execute on the virtual device.

Open a terminal/command window in the [project root]/server directory and run the following command to start your Express Server:

node index.js

Open a terminal/command window and run the following Cordova command to build and deploy the application to the device:

cordova run android --device

Summary and Next Steps

In this article we transformed a jQuery Mobile web application into a jQueryMobile + Cordova native application that can be deployed to mobile devices. We went through the process of creating a Cordova project, migrating a jQuery Mobile application into it, and deploying the mobile application to a device.

In the next article of this series of mobile development tutorials, we will continue building the features of the Meeting Room Manager app that is the subject of this series. Next up is the user login feature. Make sure to sign up for my newsletter so you can be among the first to know when the next article is online.