Create Your First Mobile App with PhoneGap Build – Adding jQuery Mobile

by Brian Rinaldi

This is part 4 in an ongoing series. You can find part 1 here, part 2 here and part 3 here. The files for the sample app are available here.

At this point, our application works but looks like a simple web page and not like an app. In this next step, we are going to make our app look and feel more less like a web page and more like an app using jQuery Mobile.

Why jQuery Mobile?

As some of you may already know, there are a lot of mobile frameworks available, most of which would also help us accomplish our task of making our app feel like an app. We could also have accomplished this task using custom HTML, CSS and JavaScript. However, I chose jQuery Mobile for a number of reasons. The primary reasons I chose it is because you are probably already familiar with jQuery and because it works, in large part, by transforming our standard HTML.

As you’ll see, jQuery Mobile will simply take our HTML and CSS and inject in a lot of styles and additional HTML to make our page look and feel like a mobile app. This makes jQuery Mobile quite easy to learn as all you need to know to get started are a handful of attributes that tell jQuery Mobile how to perform this transformation. However, it can also be considered a drawback since it can often be difficult to dig into these automatically generated styles and HTML to accomplish specific customizations you may want. Nonetheless, the ease of getting started with jQuery Mobile makes it perfect for a beginner’s tutorial such as this. As you become more comfortable creating apps, I recommend you examine other frameworks to see what best fits your needs.

Build the App

First, we are going to add the CDN hosted scripts for jQuery and jQuery Mobile as instructed on the downloads page to our index.html page. We are using the CDN hosted version here primarily for the sake of simplicity of this tutorial. Keep in mind that if your user is offline, they won’t have access to these files and your application would fail. As such, if you are developing a real application, you would want to include local copies of the libraries instead.

You can add the following HTML directly below our existing stylesheet link within index.html.

<link rel="stylesheet" href="https://code.jquery.com/mobile/1.3.0/jquery.mobile-1.3.0.min.css" />
<script src="https://code.jquery.com/jquery-1.8.2.min.js"></script>
<script src="https://code.jquery.com/mobile/1.3.0/jquery.mobile-1.3.0.min.js"></script>

While we’re at it, if you haven’t already, we might as well add in the reference to phonegap.js as well. As mentioned earlier, this file doesn’t exist in our local files but is injected by PhoneGap Build at compile time. This file gives us access to the PhoneGap API (more on that later).

<script src="phonegap.js"></script>

Since jQuery Mobile obviously depends on jQuery, let’s take advantage of jQuery and swap the straight JavaScript XHR code for a much simpler jQuery version in index.js. The code below will replace all the existing JavaScript code in index.js as we’re using jQuery Mobile events rather than PhoneGap events to handle the call to load the GitHub data. Also, in index.html you can get rid of the script block that references app.initialize().

$.ajax("https://api.github.com/legacy/repos/search/javascript").done(function(data) {
     var i, repo;
     $.each(data.repositories, function (i, repo) {
        $("#allRepos").append("<p><a href='https://github.com/" + repo.username + "/" + repo.name + "'>" + repo.name + "</a><br>"+ repo.description + "&glt;/p>");
     });
});

If you were to load the page at this point in your browser, it wouldn’t look significantly different than it did previously. This is because we need to add jQuery Mobile specific HTML code and data-role types to tell jQuery Mobile how we want our mobile app to display. Data attributes are how jQuery Mobile identifies element types and properties when it auto-generates HTML and styles. All we have right now is a single div element, so let’s replace our div with the ID of “allRepos” with the following HTML.

<div id="reposHome" data-role="page">
    <div data-role="header" data-position="fixed">
        <h1>GitHub Search</h1>
    </div>
    <div data-role="content">
        <ul id="allRepos" data-role="listview"  data-filter="true">
        </ul>
    </div>
</div>

Right now you can run our app in the browser and it would look more like an app, but our project list is generating simple paragraphs. Let’s modify our JavaScript in index.js to use list items as opposed to paragraphs and add some additional project details to the output. In the end your index.js should look like this.

$('#reposHome').bind('pageinit', function(event) {
    loadRepos();
});

function loadRepos() {
    $.ajax("https://api.github.com/legacy/repos/search/javascript").done(function(data) {
        var i, repo;
        $.each(data.repositories, function (i, repo) {
            $("#allRepos").append("<li><a href='https://github.com/" + repo.username + "/" + repo.name + "'>"
            + "<h4>" + repo.name + "</h4>"
            + "<p>" + repo.username + "</p></a></li>");
        });
        $('#allRepos').listview('refresh');
    });
}

Our result list is quite long, so, as you may have noted earlier, we’ve added a data-filter=”true” attribute to the list to make it filterable.

You can test this in the browser and on your device. Since we enabled Hydration, the app should automatically update on your device. In the browser, the app should now look like the screenshot below.

Ripple Emulator

Now that our app is starting to look and feel like a real app, testing on the browser can be quite limiting. However, many of us are not blessed with a wide array of devices to test on. In this kind of situation, the Ripple Emulator can be incredibly useful. It will emulate how your application will look on a large variety of device screens. It also allows you to perform a number of tests, including things like accelerometer and geolocation, that would typically require a device.

Before you can use the Ripple Emulator, you first need to install the Chrome extension. Once this is installed, you can go to emulate.phonegap.com and enter the URL that you would like to emulate and test. As we are running our app locally via a local web server, we can use our localhost address (for example, mine is localhost:3333) and emulate our application.

Below is a screenshot of the app (up to this point) running inside the Ripple Emulator set for an iPhone4/4S emulation.

In the next part, we’ll look at how you can add additional pages to your app. Continue to part 5.