Create Your First Mobile App with PhoneGap Build – Connecting to an API

by Brian Rinaldi on March 29, 2013

The modern web is always changing, and this article is more than two years old.

by Brian Rinaldi

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

At this point, we’ve simply taken some pre-existing code and uploaded it to PhoneGap Build to create various device-specific builds for us. The application, simply responds to PhoneGap’s onDeviceReady() event and changes the image. This isn’t terribly exciting.

In this step, we’ll start the process of building a real mobile application. This application will load data containing a list of open source JavaScript applications from the GitHub API. The sample code comes from my CORS tutorial that is available here.

Loading External API Data

I chose the GitHub API specifically for this example because it supports CORS, which stands for Cross-Origin Resource Sharing. As you can read in my prior blog post, CORS is a new standard that can overcome the cross-browser restrictions that you might encounter previously when loading external data via JSON, for instance. While that restriction doesn’t apply to installed mobile apps, I chose to use it to make it easier for those readers who do not have a device ready to test on, so that they can test in the browser.

It is important to note however, that due to to browser restrictions, you must run CORS calls inside a web server not using the file:/// protocol. OSX already comes with Apache pre-installed if you choose to use that for your web server. For Windows, you can use Mongoose to turn any folder into a web server. Alternatively, you can use Node-based applications like HTTPster or node-static to create local static web servers on the fly.

Building the App

We’ll start building our application using straight HTML/JS code without any frameworks. Later on we’ll add jQuery Mobile.

Assuming you are working from the sample starter application, we’ll need to clean up the HTML a bit in index.html. Truth be told, we won’t keep much of the pre-existing code in the long run but for now, we’ll just remove everything but the scripts from inside the <body> tags. In it’s place, we will just add a <div> with the id of allrepos.

<div id="allRepos"></div>

We should also replace the viewport meta tag so that the content doesn’t show up incredibly tiny.

<meta name="viewport" content="width=device-width, initial-scale=1">

Next we are going to add the XHR request for the GitHub to the deviceready method in js/index.js. This will request the data we need from the GitHub API and return the result in a JSON format.

About the deviceready Function

PhoneGap has a number of lifecycle events that fire during the course of your app running. These include events to notify you that certain hardware buttons have been clicked or your app has moved to the background. The deviceready event is one that nearly every PhoneGap application will use as it notifies your application that PhoneGap has fully loaded.

Adding any code that needs to run when your application starts within the deviceready function will prevent errors from trying to make PhoneGap API calls before PhoneGap is loaded. It is important to note, however, that the DOM may not have loaded when deviceready is called, meaning that attempts to access or modify elements within the HTML of your page may still fail.

For a full list of PhoneGap events, see the PhoneGap documentation.

First, be sure to clear out any existing JavaScript code within the deviceready method. Next, add the following code within the deviceready function. I’ll explain what the code is doing in a moment.

var xhr = new XMLHttpRequest();
 xhr.open('GET', 'https://api.github.com/legacy/repos/search/javascript', true);
  // Response handlers.
  xhr.onload = function () {
     var repos = JSON.parse(xhr.response), i, reposHTML = "";
     for (i = 0; i < repos.repositories.length; i++) {
       reposHTML += "<p><a href='https://github.com/" + repos.repositories[i].username + "/" + repos.repositories[i].name + "'>" + repos.repositories[i].name + "</a><br>" + repos.repositories[i].description + "</p>";
     }
     document.getElementById("allRepos").innerHTML = reposHTML;
  };

  xhr.onerror = function () {
     alert('error making the request.');
  };

xhr.send();

Let’s briefly walk through what this code is doing. Once the request is loaded, we are looping through all of the results contained in the JSON response. The JSON response contains a collection of JavaScript objects that include the details about the GitHub repositories returned by our search for repositories matching the search team “javascript.” During the loop, we are assembling a string containing HTML to display the results and, when the loop is complete, we inject this HTML into the <div> we created earlier using the innerHTML property.

See Also:  Why you should limit JavaScript — and how to do it

Feel free to customize the output if you choose. To see the data being returned, you can go to  https://api.github.com/legacy/repos/search/javascript. You can also modify the search term in the GitHub API call if you like simply by changing the URL. For example, this URL searches CSS instead of JavaScript, https://api.github.com/legacy/repos/search/css.

To test the app before uploading it to PhoneGap Build, simply load it in your browser via your localhost (see the discussion earlier about setting up a local server). Since this is not running on a device, nothing will actually appear on the screen unless we manually trigger app.deviceready() method via Chrome Dev Tools (or the developer tools of whatever browser you are using). In Chrome, you’d go to Tools > Developer Tools and select the Console tab if it isn’t already selected. You may notice an error for a missing resource of phonegap.js. This is the file that allows you to access the PhoneGap API, however, for now, don’t worry about that as this gets added when the app is run on the device and we aren’t yet using the API. Now simply type app.deviceready() into the console and you should see a result similar to the screenshot below. Keep in mind it may take a few seconds for the data to load.

step1

You may notice that in the screenshot above our console is giving us an error noting that the included script, phonegap.js, was not found. You can ignore this error for now. The phonegap.js file is automatically injected by PhoneGap Build at build time, so while testing in the browser, we can expect this error. The phonegap.js file is necessary for accessing the PhoneGap API, which we aren’t actually using just yet (but we will).

Now, before we upload this application to PhoneGap Build, let’s also modify the config.xml to have our correct information. Feel free to change the app name, author details and description as you see fit. The config.xml file allows you to specify things like your applications title, the icons that it will use on various platforms, the splash screen that will show while it is loading and many other important properties. It is also where you assign your applications unique app id and manage version numbers. In addition, you can specify a number of platform-specific options and specify which features (ex. camera, geolocation, contacts) that are required by your application.

As our sample application is purposefully simple, we won’t need to specify any platform-specific properties or enable any features, but as you build more complex applications you’ll need to understand how config.xml works. For a full reference on the config.xml go to https://build.phonegap.com/docs/config-xml. There are also tools, like Chris Griffith’s ConfiGAP, that can assist you in building your config.xml file. As noted before, with PhoneGap Build, you are not required to use config.xml but if you do certain app settings cannot be modified via the web site.

See Also:  Why you should limit JavaScript — and how to do it

Once you are done, you can simply zip up the results and upload it to your PhoneGap Build project. Since we enabled Hydration earlier, we should be notified that a new build is available when we reopen the app on our device (note: sometimes it may be necessary to force stop the app before reopening it in order to see the update screen). Install the update and you should see the app running on your device (again, it may take a moment for the data to load, especially if it is over your mobile network).

Unfortunately, our app looks and behaves like a web page and not an app. This is an important thing to consider. Not only will your users be confused and disappointed if they download an app that doesn’t look and feel like a native app, but you’ll likely never get this accepted into the iOS App Store. In the next steps, we’ll start to make this app look like a real mobile app using jQuery Mobile and then start to add functionality to make it behave more like a native app.

However, let me just note here that it is important to consider why you are creating an app versus a web page. If you are simply packaging the functionality of your web page into an app, your customers won’t be pleased. However, if you intend to take advantage of device features that aren’t available consistently in the browser, then it may be worth building an app.

Debugging

Since PhoneGap apps are built with web technologies, much of your initial debugging can occur in the browser. Of course, you will need to test on devices and it might initially seem that debugging the app on your devices might be a complex. Thankfully, PhoneGap has an invaluable solution to that problem with its online device debugging features built with weinre. Let’s take a quick look at how it works.

As you may recall, earlier when we created our project on PhoneGap Build, we checked the “enable debugging” option. Since we have enabled debugging, you will see the debug button when viewing the project details on PhoneGap Build as in the screenshot below.

debug-button

First, open the application on your device and then click the button, which will open up debug.phonegap.com in a new tab. You should now see something similar to below, where it displays an active device connection to the app running on your test device.

debug-connection

If you’ve used some of the browser debugging tools such as Chrome Dev Tools, this interface should feel familiar. You can inspect and even modify the HTML and CSS styles as seen in the screenshot below, and as you choose selections in the HTML, you will even see those highlighted in the app running on your device.

debug-elements

You can also see anything logged to the console or use the console to enter statements and test scripts as you would in the browser console. For example, in the screenshot below I have selected the main div in our simple sample application via the console. I should note that responses can take a few seconds to return, especially when you are returning a large amount of data, so be patient.

debug-console

 

Next Step

In the next step, we’ll make our PhoneGap app look and feel more like a real mobile app using jQuery Mobile. Go to step 4.