PhoneGap Tips

Installing Plugins with PhoneGap's Command-Line Interface

Tue, 23 Jul 2013 00:00:00 -0400

A few weeks ago I wrote about PhoneGap's Node.js command-line interface. A reader stopped by to check out the article and asked how to use the command-line interface to install plugins, which of course I had conveniently glossed over.

Well, PhoneGap 3.0 was released, and one of the big changes in version 3.0 was that a lot of the device functionality that used to ship with PhoneGap has been extracted to individual plugins. Having recently written about using InAppBrowser to build an OAuth login I figured I would update my OAuth example project for PhoneGap 3.0 and see how plugins work with the command-line interface.

First, I updated my package.json to use the latest cordova node module:

{
  "name": "google-api-oauth-phonegap",
  "version": "0.0.3",
  "dependencies": {
    "cordova": "~3.0.0"
  }
}

Then I ran npm update to update my project’s node modules.

At this point, I was all set up to develop with PhoneGap 3.0. However, since InAppBrowser is a plugin now, and I had not installed it yet, I wanted to see what would happen if I just ran the project without installing the plugin.

> cordova build ios
> cordova emulate ios

When I tested the app, the consent page opened just fine, but sure enough, when I got to the last step and tapped the Accept button, the button became disabled and the consent page did not disappear, which left me staring at this:

So, as advertised, I had to install the InAppBrowser plugin to get my app working again:

> cordova plugin add https://git-wip-us.apache.org/repos/asf/cordova-plugin-inappbrowser.git

I built the project and ran the emulator again, and this time the OAuth login worked!

As you can see, installing plugins with the command-line interface about as easy as it gets. You simply provide a URL (or path) to the plugin you want and the command-line interface takes care of the rest.

The only somewhat difficult part is discovering the correct plugin URL.

The plugin URLs for functionality like InAppBrowser that used to ship with PhoneGap can be found here. Most of the other community plugins are slowly being migrated out of the phonegap plugins GitHub repository, so it can sometimes be helpful to check there first to see if you can find a link to the 3.0-compatible plugin you want to use.

OAuth with PhoneGap's InAppBrowser: Expiration and Revocation

Fri, 12 Jul 2013 00:00:00 -0400

A few weeks ago I wrote about how to implement an OAuth login with PhoneGap's InAppBrowser. Well, it seems like a lot of people are looking for information about PhoneGap and OAuth, so I figured I’d write a follow up article.

At the end of the last article we had a way to launch the consent page in PhoneGap’s InAppBrowser, retrieve the authorization code, and exchange it for an access token. That’s great, but for a release-quality application we need to take things a bit further.

There are two more conditions we need to consider: access tokens can expire and access tokens can be revoked.

Refreshing Expired Access Tokens

Access tokens are valid for a finite period of time, then they expire. This means that after we receive an access token we can cache it and continue to use it until it expires. When an access token expires, we need to go get a new one.

An OAuth 2.0 provider will typically issue an access token with a refresh token. We can use the refresh token to retrieve a new access token without showing the consent page again.

At first the solution seems simple. Use setTimeout to refresh the token a few seconds before it expires. However, this could lead to hard-to-debug race conditions if the token refresh takes a long time to complete, but that’s not the worst problem.

Our PhoneGap app is running on a mobile device. What if we do not have a network connection when the refresh timer fires? What if the app is suspended in the background when the refresh timer fires? We could subscribe to PhoneGap’s online or resume events and refresh the token or reset the timer in each of those event handlers… but that will quickly become a mess.

The best way I’ve found to handle this is to check the status of the access token before each API request is sent. If the token is still valid, we’ll just pass it on to the original request. If the token is expired, we’ll refresh the token, cache the new token, and then pass it on to the original request.

Building on the OAuth example from the last article, we’re going to add two new methods. First, we need a setToken method to cache some information about the token:

googleapi.setToken = function(data) {
  localStorage.access_token = data.access_token;
  localStorage.refresh_token = data.refresh_token || localStorage.refresh_token;

  //Calculate exactly when the token will expire, then subtract
  //one minute to give ourselves a small buffer.
  var now = new Date().getTime();
  var expiresAt = now + parseInt(data.expires_in, 10) * 1000 - 60000;
  localStorage.expires_at = expiresAt;
};

I’m storing the token information in localStorage in this example, but you could also store it in a cookie, or in a file by using PhoneGap’s file system API if you want. Anywhere we retrieve an access token we’ll need to call this method to update the cache.

Next we need a getToken method that will transparently validate a cached access token or update an expired access token with a refresh token.

googleapi.getToken = function(options) {
  var deferred = $.Deferred();
  var now = new Date().getTime();

  if (now < localStorage.expires_at) {
    //The token is still valid, so immediately return it from the cache
    deferred.resolve({
      access_token: localStorage.access_token
    });
  } else if (localStorage.refresh_token) {
    //The token is expired, but we can get a new one with a refresh token
    $.post('https://accounts.google.com/o/oauth2/token', {
      refresh_token: localStorage.refresh_token,
      client_id: options.client_id,
      client_secret: options.client_secret,
      grant_type: 'refresh_token'
    }).done(function(data) {
      googleapi.setToken(data); //Remember I said we need to call this to cache the token?
      deferred.resolve(data);
    }).fail(function(response) {
      deferred.reject(response.responseJSON);
    });
  } else {
    //We do not have any cached token information yet
    deferred.reject();
  }

  return deferred.promise();
};

Here is how we can use the getToken method to ensure we have a valid access token before making an API request:

googleapi.getToken({
  client_id: 'YOUR_CLIENT_ID',
  client_secret: 'YOUR_CLIENT_SECRET'
}).then(function(data) {
  //Call an API method and return a new promise
  return googleapi.userInfo({ access_token: data.access_token });
}).done(function(user) {
  alert('Hello ' + user.name + '!');
});

Naturally, if the application involves many different API calls that all require access tokens, we’ll want to figure out some way to do this in one place. How to accomplish that will depend on the specific application, so I’ll leave it as an exercise for you!

Revoked Access Tokens

Now we’re handling expired tokens, but there is one more problem. Tokens can be revoked, and not necessarily only from within your app. Most OAuth providers have some sort of console where you can manage all of your OAuth grants. One of your app’s users might go to this screen and clean things up, and now that access token you cached doesn’t work anymore. Even if it was not yet expired!

If this happens, the only way to get a new access token is to ask the user for one by showing the consent page again.

The best way to handle this is to add an error handler for API requests that fail authorization. If authorization fails, there is likely some problem with the access token we used, so we need to throw it out and ask for a new one. Fortunately, we can accomplish this easily:

googleapi.getToken({
  client_id: 'YOUR_CLIENT_ID',
  client_secret: 'YOUR_CLIENT_SECRET'
}).then(function(data) {
  //Call an API method and return a new promise
  return googleapi.userInfo({ access_token: data.access_token });
}).done(function(user) {
  alert('Hello ' + user.name + '!');
}).fail(function() {
  //The token was revoked, prompt the user to login again
  app.showLoginView();
});

Just like in the last post, the full source code for this example is available on github. If you want to try out what happens when you revoke an access token, head to your Google Accounts page, click on the manage security link, then click on the review permissions link under connected applications and sites to manage your active OAuth grants.

Conditional Dependency Injection with AngularJS

Tue, 02 Jul 2013 00:00:00 -0400

The excitement level around AngularJS got high enough that I thought I should give it a shot, so I took it for a spin in a PhoneGap application I am working on.

My application defines an OAuth service that handles authentication and authorization. I want to inject different implementations of the OAuth service depending on the environment the application is running in. In a web browser the OAuth service simply wraps the Google API JavaScript client. In the PhoneGap web view the OAuth service uses a custom implementation that relies on InAppBrowser.

I think conditional dependency injection will be a common need for most PhoneGap developers, especially developers that hope to reuse some, or all, of their code in a web application.

Unfortunately, it is not immediately obvious how to do this…

Here was my first attempt:

var app = angular.module('app', []);
if (window.cordova) {
  app.service('oauth', function(phonegapDependencies) {
    this.authorize = function() {};
  });
} else {
  app.service('oauth', function(webDependencies) {
    this.authorize = function() {};
  });
}
app.controller('LoginController', function($window, oauth) {
  oauth.authorize();
});

This is simple, but the problem with this approach becomes apparent when you need to make a decision about which service to use after bootstrapping. It also hurts testability. You can’t test both implementations in the same test run.

My next attempt was to define two services, declare a dependency on both, and choose which to use at runtime:

var app = angular.module('app', []);
app.service('webOauthImpl', function() {
  this.authorize = function() {};
});
app.service('phonegapOauthImpl', function() {
  this.authorize = function() {};
});
app.controller('LoginController', function($window, webOauthImpl, phonegapOauthImpl) {
  if ($window.cordova) {
  	phonegapOauthImpl.authorize();
  } else {
  	webOauthImpl.authorize();
  }
});

This is somewhat better from a testability standpoint, but I still don’t like the thought of having these checks littered throughout my code. I want my controller to only be aware of one OAuth service. This will make it easier to use some other useful features of AngularJS, like decorators for example.

After digging around in the AngularJS documentation some more, I discovered providers, which allow more control over the dependency injection process. Here was my attempt at using providers:

var app = angular.module('app', []);
app.provider('oauth', function($window, phonegapDependencies, webDependencies) {

  function webOauthImpl(webDependencies) {
    this.authorize = function() {};
  };
  
  function phonegapOauthImpl(phonegapDependencies) {
    this.authorize = function() {};
  };
  
  this.$get = function() {
    if ($window.cordova) {
      return new phonegapOauthImpl(phonegapDependencies);
    } else {
      return new webOauthImpl(webDependencies);
    }
  };

});
app.controller('LoginController', function(oauth) {
  oauth.authorize();
});

Okay, now we’re getting somewhere. This is easy to test, I managed to keep the conditional in one place, and the controller only depends on a single OAuth service. The only thing I still don’t like is having to specify the dependencies for both implementations in the provider, and then pass the dependencies to the appropriate controller. I want AngularJS to do this for me…

Well, it can! I realized I could use the $injector service with a factory to accomplish exactly what I wanted:

var app = angular.module('app', []);
app.service('webOauthImpl', function(webDependencies) {
  this.authorize = function() {};
});
app.service('phonegapOauthImpl', function(phonegapDependencies) {
  this.authorize = function() {};
});
app.factory('oauth', function($window, $injector) {
  if ($window.cordova) {
    return $injector.get('phonegapOauthImpl');
  } else {
    return $injector.get('webOauthImpl');
  }
});
app.controller('LoginController', function(oauth) {
  oauth.authorize();
});

That’s it! First I register two different OAuth services, each with the same interface. Then I register a factory method that depends on the $window and $injector services. In the factory method I check whether or not the cordova global variable is defined and resolve the appropriate OAuth implementation using the $injector.get method. Now I can test each implementation in isolation and test that the OAuth factory gives the right implementation under the right conditions.

Debugging iOS PhoneGap Apps with Safari's Web Inspector

Wed, 26 Jun 2013 00:00:00 -0400

At some point, something will go wrong in your PhoneGap application, and you’ll want to know why. Ideally, you’ll be able to reproduce the problem in a desktop web browser, fix it, and move on. Inevitably, however, you’ll run into a problem that is only reproducible on a device. If this happens to you on iOS, and you are targetting iOS 6 or higher, you’re in luck… well, aside from that nasty defect you just found, but hey, it happens!

With Safari 6 and higher (OS X only, sorry Windows) you can use Safari’s developer tools to remotely debug web pages in mobile Safari on an iOS device.

But wait, there’s more!

Not only can you remotely debug web pages in mobile Safari, you can remotely debug any web page in any plain old UIWebView, which just happens to include that UIWebView hosting your PhoneGap application. Note that you can only inspect UIWebView content in apps that were transferred to a device from XCode. Sorry, no inspecting apps downloaded from the App Store!

Here’s how to set up for debugging PhoneGap apps with Safari’s web inspector.

Disable Private Browsing

Open your device’s Safari settings and ensure that Private Browsing is turned off. Remote debugging will not work if Private Browsing is enabled. I learned this the hard way after wasting a couple hours trying to set up remote debugging.

Enable Web Inspector

Tap the Advanced tab on your device’s Safari settings and ensure that Web Inspector is turned on.

Enable Safari’s Develop Menu

On your desktop or laptop, open Safari’s Preferences and click on the Advanced tab. Check the box to Show Develop menu in menu bar.

Start Web Inspector

Launch your app either in the iOS simulator or on a physical device. If you are using a physical device you’ll need to connect it to your desktop or laptop with the standard USB cable. Once the app has launched, switch to Safari, select the Develop menu item, then find the entry corresponding to the web page you want to debug.

Now you can use web inspector just like you would to debug a web page.

Pitfalls

One disadvantage to using web inspector like this is that you cannot attach early enough to debug issues that occur at start up. You can fake it a little by adding a delay to your start up code with setTimeout, but even that won’t help catch every issue. You’ll have to rely on the old standbys alert() and console.log() to figure out these issues, and of course, just opening your app’s main HTML page in a browser can be quite helpful for diagnosing start up problems.

Google API OAuth with PhoneGap's InAppBrowser

Mon, 17 Jun 2013 00:00:00 -0400

If your PhoneGap project requires access to one of Google’s APIs, the first challenge you’ll likely run into is how to handle the OAuth dance in a PhoneGap application.

Google’s OAuth documentation seems to indicate OAuth 2.0 for installed applications fits the bill for a mobile application.

The idea is to use an embedded web browser to show the OAuth consent page. If the user grants access, we can get the authorization code out of the embedded browser’s title property. We PhoneGap developers have InAppBrowser for embedded browsing, so this should be a piece of cake!

If you want to follow along, head on over to the API console and create a new project. Select API Access and then click the button to create a new client ID. In the dialog that pops up, select installed application, choose your platform, and fill in any other required information for your platform. Afterwards you’ll see your client ID, client secret, and redirect URIs.

Now that the application is registered with Google, go ahead and create a new PhoneGap project. I recommend the command-line interface, but use whatever you’re comfortable with. I tested this solution with PhoneGap 2.8, 2.9, and 3.0. If you are using PhoneGap 3.0 or higher, you will need to install the InAppBrowser plugin. I have heard from some readers that this solution may not work with earlier PhoneGap versions, so if you run into problems, check your PhoneGap version first.

In the examples that follow, I’ll be using jQuery since it is fairly ubiquitous and it keeps the code terse. With little effort you could make this work with your library of choice, or no library at all.

To keep things simple let’s start with a view that has a login button and a placeholder for a message:

<div id="login">
  <a>Sign In With Google!</a>
  <p></p>
</div>

When the application starts up, we need to wait for the deviceready event so we can interact with parts of the PhoneGap API like InAppBrowser. After deviceready fires, we can bind an event handler to show the OAuth consent page when the login button is tapped, and update the placeholder with the status of the OAuth dance after it completes. Here’s what that looks like in code:

var googleapi = {
    authorize: function(options) {
        var deferred = $.Deferred();
        deferred.reject({ error: 'Not Implemented' });
        return deferred.promise();
    }
};

$(document).on('deviceready', function() {
  var $loginButton = $('#login a');
  var $loginStatus = $('#login p');

  $loginButton.on('click', function() {
    googleapi.authorize({
      client_id: 'YOUR CLIENT ID HERE',
      client_secret: 'YOUR CLIENT SECRET HERE',
      redirect_uri: 'urn:ietf:wg:oauth:2.0:oob',
      scope: 'SPACE SEPARATED LIST OF SCOPES'
    }).done(function(data) {
      $loginStatus.html('Access Token: ' + data.access_token);
    }).fail(function(data) {
      $loginStatus.html(data.error);
    });
  });
});

If we run this and tap the button, we’ll see the Not Implemented message below the button. We just need to make that call to googleapi.authorize work! The first thing we need to do is show the consent page. Fortunately, using InAppBrowser in PhoneGap is the same as opening a popup from JavaScript using the window.open method. Let’s replace that deferred.reject call with some code to open the consent page:

var authUrl = 'https://accounts.google.com/o/oauth2/auth?' + $.param({
    client_id: options.client_id,
    redirect_uri: options.redirect_uri,
    response_type: 'code',
    scope: options.scope
});

var authWindow = window.open(authUrl, '_blank', 'location=no,toolbar=no');

What we’re doing here is building the URL for Google’s OAuth consent page and opening it in a new web view. Next we need to deal with retrieving the authorization code at the end of the consent process. That’s where things get interesting!

The recommendation is to retrieve the authorization code from the browser’s title. However, there are a couple of problems with that.

First, the consent window is pointing at a different origin, so according to the same origin policy, we are not allowed to access any details of its document, including the title. In PhoneGap the rules around the same origin policy are relaxed, like for AJAX requests, but I suspect we aren’t dealing with a fully specification conformant window object either. So the document title likely isn’t exposed in any way that would allow us to access it.

Second, even if we could access the document title, the authorization code isn’t set in the title until the very end of the OAuth flow, and we have no way of knowing when it is set. So we would have to poll for the change. Alternatively, we could use InAppBrowser’s executeScript method to insert some code to use window.opener.postMessage to notify us when we have the authorization code. However, again, we’re not dealing with a real popup here, so opener is not set, which rules out postMessage as a means of communicating between our two web views.

The key to this problem is the loadstart event that InAppBrowser fires. The loadstart event includes the URL that InAppBrowser is about to load whenever the InAppBrowser’s location changes. So we need a way to detect and parse the authorization code from the URL. Unfortunately, with the redirect URI we are using, the authorization code does not get set in the URL. However, there are two redirect URI options for installed applications. Let’s modify our code to try http://localhost as the redirect URI:

googleapi.authorize({
  client_id: 'YOUR CLIENT ID HERE',
  client_secret: 'YOUR CLIENT SECRET HERE',
  redirect_uri: 'http://localhost',
  scope: 'SPACE SEPARATED LIST OF SCOPES'
});

If we try the OAuth flow again with this redirect URI, we see that granting access redirects us to http://localhost?code=your_authorization_code. Denying access redirects us to http://localhost?error=access_denied. We probably don’t have an HTTP server running on our mobile device, so we will most likely end up staring at some sort of error page, but it doesn’t matter because we can detect the authorization code in the loadstart event handler and close the InAppBrowser before any errors are displayed.

Let’s handle loadstart and parse the authorization code after the line where we opened the consent page with InAppBrowser:

$(authWindow).on('loadstart', function(e) {
  var url = e.originalEvent.url;
  var code = /\?code=(.+)$/.exec(url);
  var error = /\?error=(.+)$/.exec(url);

  if (code || error) {
    authWindow.close();
  }

  //TODO - exchange code for access token...
});

Finally! We have an authorization code (or an error) and we can exchange it for an access token:

if (code) {
  $.post('https://accounts.google.com/o/oauth2/token', {
    code: code[1],
    client_id: options.client_id,
    client_secret: options.client_secret,
    redirect_uri: options.redirect_uri,
    grant_type: 'authorization_code'
  }).done(function(data) {
    deferred.resolve(data);
  }).fail(function(response) {
    deferred.reject(response.responseJSON);
  });
} else if (error) {
  deferred.reject({
    error: error[1]
  });
}

That’s it! Now we can use our access token to interact with one of the many Google APIs. We still need to think about access token expiration and revocation, but fortunately I’ve covered those topics in another article.

Finally, keep in mind that OAuth is a standard, so even though this article is written specifically for Google’s OAuth implementation, there’s a good chance it will work (perhaps with a few small changes) for most OAuth 2.0 providers that support a client-side flow. For example, one reader reported that she was able to adapt this code to work with Quizlet’s OAuth implementation.

The complete source code for this example is available on GitHub.

The Node.js Command-line Interface for PhoneGap

Tue, 11 Jun 2013 00:00:00 -0400

PhoneGap ships with a simple set of scripts that you can use to create a new project from the command-line. Newly created projects include scripts to build, emulate, and deploy your app.

There is another command-line interface for PhoneGap written in JavaScript for node.js that the PhoneGap/Cordova documentation does not mention. I don’t know why this is. Maybe it will be documented in future releases. Hopefully I am not stealing the PhoneGap team’s thunder by writing about it!

What I really like about this package is that it bundles the PhoneGap/Cordova release. So by installing the package, you have effectively installed PhoneGap. It also provides some fantastic guidance about how to structure a multi-platform PhoneGap application.

The documentation recommends installing the CLI globally by running:

> npm install -g cordova

However, if you install the CLI locally you will be able to have different PhoneGap versions for different projects. So here are the steps I follow when starting a new PhoneGap project.

Install node.js, and add ./node_modules/.bin to your PATH environment variable.

Create a directory for your new project:

> mkdir myproject && cd myproject

Create a package.json for your project:

> npm init
# Follow the (many) prompts... or just hit enter a bunch of times.

Install the PhoneGap CLI:

> npm install cordova --save

Now that the CLI is installed, let’s see what it can do for us:

> cordova
Synopsis

    cordova command [options]

Global Commands

    create [path] [id] [name] ........... creates a cordova project in the specified
                                          directory optional name and id (package
                                          name, reverse-domain style)

Project-Level Commands

    platform(s) [add|remove|ls [name]] .. adds or removes a platform, or lists all
                                          currently-added platforms
    plugin(s) [add|remove|ls [path]] .... adds or removes a plugin (from the specified
    	                                  path), or lists all currently-added plugins
    prepare [platform..] ................ copies files into the specified platforms, or
                                          all platforms it is then ready for building
                                          by Eclipse/Xcode/etc
    compile [platform..] ................ builds the app for the specified (or all)
                                          platforms
    build [platform..]................... alias for prepare and then compile
    emulate [platform..] ................ starts emulator for the specified (or all)
                                          platforms, then deploys application to
                                          emulator
    run [platform..] .................... deployes the application to the specified
                                          (or all) platform devices, which must be
                                          connected and configured for running via
                                          your machine
    serve <platform> [port] ............. runs a local web server for the www/
                                          directory of the given platform the default
                                          port is 8000
                                          note that you must edit the native code to
                                          point at the server!
    ripple <platform> [port] ............ uses the serve command as a base and then
                                          wraps the server with ripple to test your
                                          app in your desktop browser
    help ................................ shows this!

Command-line Flags/Options

    -v, --version ....................... prints out this utility's version
    -d, --verbose ....................... debug, or verbose, mode Makes this utility
                                          very chatty, logging everything it does,
                                          including redirecting output of commands
                                          it shells out to back to stdout

Example usage

    $ cordova create Baz
    $ cd Baz
    $ cordova platform add android
    $ cordova build
    $ cordova serve android

The help output shows global commands and project-level commands. The only global command is create. Let’s create a new project in the directory we created above:

> cordova create . com.myproject MyProject

This gives us a project tree like this:

> tree -I node_modules --charset ascii
.
|-- merges
|-- package.json
|-- platforms
|-- plugins
`-- www
    |-- config.xml
    |-- css
    |   `-- index.css
    |-- img
    |   `-- cordova.png
    |-- index.html
    |-- js
    |   `-- index.js
    |-- res
    |   |-- icon
    |   |   |-- cordova_128.png
    |   |   |-- cordova_16.png
    |   |   |-- cordova_24.png
    |   |   |-- cordova_256.png
    |   |   |-- cordova_32.png
    |   |   |-- cordova_48.png
    |   |   |-- cordova_512.png
    |   |   |-- cordova_64.png
    |   |   |-- cordova_android_36.png
    |   |   |-- cordova_android_48.png
    |   |   |-- cordova_android_72.png
    |   |   |-- cordova_android_96.png
    |   |   |-- cordova_bb_80.png
    |   |   |-- cordova_ios_114.png
    |   |   |-- cordova_ios_144.png
    |   |   |-- cordova_ios_57.png
    |   |   `-- cordova_ios_72.png
    |   `-- screen
    |       |-- android_hdpi_landscape.png
    |       |-- android_hdpi_portrait.png
    |       |-- android_ldpi_landscape.png
    |       |-- android_ldpi_portrait.png
    |       |-- android_mdpi_landscape.png
    |       |-- android_mdpi_portrait.png
    |       |-- android_xhdpi_landscape.png
    |       |-- android_xhdpi_portrait.png
    |       |-- blackberry_transparent_300.png
    |       |-- blackberry_transparent_400.png
    |       |-- ipad_landscape.png
    |       |-- ipad_portrait.png
    |       |-- ipad_retina_landscape.png
    |       |-- ipad_retina_portrait.png
    |       |-- iphone_landscape.png
    |       |-- iphone_portrait.png
    |       |-- iphone_retina_landscape.png
    |       |-- iphone_retina_portrait.png
    |       `-- windows_phone_portrait.jpg
    |-- spec
    |   |-- helper.js
    |   |-- index.js
    |   `-- lib
    |       `-- jasmine-1.2.0
    |           |-- MIT.LICENSE
    |           |-- jasmine-html.js
    |           |-- jasmine.css
    |           `-- jasmine.js
    `-- spec.html

13 directories, 49 files

In the www folder we get the standard PhoneGap project template, with assets for every major mobile platform. The plugins folder, naturally, is for plugins. The platforms folder is where the project files for each platform will live. The merges folder is where you keep platform-specific code that will be substituted into each platform’s build step.

Let’s wrap up by getting our project running in the iOS simulator. First, add the platform:

> cordova platform add ios

Now, build it:

> cordova build ios

Build is an alias for prepare and compile. Prepare will copy the source files into the platform-specific directory and apply any applicable merges. Compile builds the platform-specific package. Now launch the iOS simulator:

> cordova emulate ios

That’s it, we’re up and running!

There’s a lot more to this tool, and I’m something of a nerd when it comes to slick command-line interfaces, so I hope you’ll stick with me as I return to it from time to time.

Font Smoothing and CSS Transitions

Thu, 06 Jun 2013 00:00:00 -0400

Try the demo!

On iOS devices and Safari, when you combine 3D transforms with elements containing text, you may notice some strange things happening with font rendering under certain conditions.

Text will appear thinner when an element with text is 3D transformed, or an element with text is composited with another 3D transformed element. When the 3D transform is removed, the text will become thicker again.

The resulting flickering text effect is not desirable.

The font-thinning behavior is most noticeable in high contrast color schemes, like white text on a dark background, though the problem is still present in more traditional black on white color schemes. Below is a screenshot showing normal text on the left and 3D transformed text on the right, or you can see it for yourself.

To make matters interesting, you will not see this behavior in the iOS simulator. More interesting still, on iOS devices, you will only see this problem when the device orientation is horizontal! If you change the orientation of your iOS device from vertical to horizontal, and watch closely, you will notice the fonts become thicker.

When I first encountered this problem, a little research seemed to indicate setting -webkit-font-smoothing to antialiased would fix the problem. It does fix the problem in Safari, however, it does not fix the problem on iOS. After yet more research, I found some sites suggesting that sub-pixel antialiasing is not available on iOS. This makes sense since iOS devices need to work in multiple orientations, and that kind of throws a wrench in the whole sub-pixel rendering thing, but it does not explain why text still appears thicker in horizontal orientation.

Sadly, I still haven’t found a good explanation for this behavior. My working theory is that subpixel antialiasing does work on iOS devices, but only in horizontal orientation because of the pixel orientation. I also think there may be a browser bug that ignores the -webkit-font-smoothing property on iOS devices. Again, this is just a theory, please don’t take this as a statement of fact!

To further complicate things, you’ll find that disabling sub-pixel antialiasing is controversial. Pragmatically, however, if you want to use CSS 3D transforms and transitions, disabling sub-pixel antialiasing is really your best option at this point.

Since -webkit-font-smoothing has no effect on iOS, you can eliminate this behavior by forcing hardware acceleration with an identity translate3d on the text element. Remember that GPU memory is limited. If anyone has a better approach for dealing with this issue, I’d love to hear it!

Nitro JavaScript Engine in iOS PhoneGap Apps

Thu, 30 May 2013 00:00:00 -0400

One advantage to building PhoneGap applications is that you can test your application on a physical device before registering with a developer program. Just host all of your source files on a web server and and point the device’s web browser at the server.

$100 per year to enroll in a developer program isn’t the end of the world, but I’d rather keep it until I know I have something to release!

Of course, with this testing method your application will not have access to device functionality exposed through the PhoneGap API, but it is still a good way to rapidly prototype your application’s user interface.

On iOS, there is another caveat to this testing method. Mobile Safari executes JavaScript faster than PhoneGap’s UIWebView.

Mobile Safari’s JavaScript engine is called JavaScriptCore, and is also referred to as Nitro. Nitro in mobile Safari just-in-time (JIT) compiles JavaScript into native machine code, rather than interpreting it. According to some benchmarks, JIT compilation in Nitro can improve the speed of JavaScript execution by 200% to 300%.

As of iOS 6, JIT compilation is only enabled in mobile Safari. JavaScript executing in a UIWebView will not be JIT compiled.

While this may sound like a crippling issue for iOS PhoneGap applications, it usually isn’t much of a problem. JIT compilation only speeds up JavaScript execution, it has no effect on layout and rendering, including hardware accelerated rendering.

If your application performs intensive computations in JavaScript, you can use the old setTimeout trick, or possibly web workers, as a way to keep the UI thread responsive. Even with JIT compilation, using these techniques to keep the UI thread responsive is considered best practice.

You should test how (the lack of) JIT compilation affects your application’s performance. The most obvious way to do this is to deploy your application to a physical iOS device. There is another way that will let you delay enrolling in the iOS developer program a little longer. Install Google Chrome for iOS. Google Chrome for iOS uses the same UIWebView component that your PhoneGap application will use, and therefore is similarly stunted when it comes to JIT compilation.

Force Hardware Acceleration with translate3d... Sometimes

Fri, 24 May 2013 00:00:00 -0400

Try the demo!

The last PhoneGap application that I developed had a feature that allowed you to drag an image around the screen so you could drop it in a folder or a trash can… you get the idea. The images were relatively large. Each image took up most of the display area of an iPad. The dragging animation worked by dynamically updating the -webkit-transform property with a translate3d value that followed a touch around the screen.

While testing the application I noticed that the image appeared to “stick” when a drag operation started. I could drag a short distance from the starting point of the pan gesture before the image snapped to the right location. When I dropped the image and started dragging again, I experienced the same stickiness. This was most noticeable on a first generation iPad (remember, always test on old hardware).

I found that by applying an identity translate3d to the image element in CSS, there was no delay at the start of a drag operation. For example:

.draggable-image {
  -webkit-transform: translate3d(0px,0px,0px);
}

Why does this work? And what are the performance implications?

This article explains the hardware accelerated rendering path in Chrome in a lot of detail. The web view powering an iOS or Android PhoneGap application may have a slightly different approach to hardware accelerated rendering, but hopefully it is close enough!

Allow me to grossly oversimplify the hardware accelerated rendering path for a moment…

When an element is rendered in hardware, the element and all of its children are first rendered to a bitmap, and then the bitmap is uploaded to the GPU as a texture. Once the texture is uploaded to the GPU, the element can be transformed very quickly. Whenever the element or its children need to be redrawn, the element must be re-rendered to a bitmap and uploaded to the GPU again.

It stands to reason that larger or more complex elements will take longer to render to a bitmap and subsequently upload to the GPU. To avoid this performance penalty, you can either:

make elements smaller or less complex, or
force elements into hardware acceleration as early as possible, and ensure they stay hardware accelerated.

If the latter is your only option, the simplest way to do this is to put an identity translate3d on the element. The tradeoff is that the element’s texture remains in VRAM for longer, and VRAM is limited on mobile devices. In my case, a smoother dragging transition was worth the cost of some extra VRAM.

One quick way to see this in action is to exceed the maximum texture size for a mobile device. When an element larger than the maximum texture size switches to hardware acceleration, you will see an ugly flicker and a sort of “blocking in” effect as the texture tiles comprising the element make their way to the GPU. By applying an identity translate3d in CSS, this ugly flicker will only happen once, provided the element does not change later on.

With smaller, less complex elements, you will see no noticeable performance penalty when switching between software and hardware rendering, so saving VRAM may be the better option. As with any piece of application performance advice, test it for yourself before blindly applying a rule!

Image Replacement Without Flickering 3D Transforms

Tue, 21 May 2013 00:00:00 -0400

Try the demo!

Image replacement techniques improve a web page’s accessibility by allowing you to write nice semantic HTML and progressively enhance it with CSS. If you are writing a PhoneGap application, you may not care about the accessibility and “semanticness” of your HTML, but if you do, read on!

The idea behind image replacement is to use CSS to hide the text of an HTML element and instead show a background image. This improves accessibility by keeping the text available to screen readers, while also rendering pretty pictures in web browsers.

A standard technique for image replacement that is still quite prevalent works by setting a large, negative text-indent. For example suppose you have this anchor tag in your HTML:

<a class="html5logo"
  href="javascript:void(0);">HTML5</a>

Here is how you can replace the anchor’s text with a background image using CSS:

.html5logo {
  display: block;
  width: 128px;
  height: 128px;
  background: url(/img/html5-badge-128.png) no-repeat;
  text-indent: -9999px;
}

This hides the element’s text far off-screen to the left. Provided the element does not have a lot of text, causing the text to reach back into the element, this will work fine. However, when you combine this technique with hardware accelerated 3D transforms, transitions, or animations on a mobile device, you will notice an ugly flicker whenever a 3D transform on the element is initiated.

The issue is that the large indent effectively makes the entire element 10,000 pixels wide, and GPUs have a maximum texture size that is generally far less than 10,000 pixels. Fortunately, rather than unceremoniously crashing your application, WebKit will break the element up into tiles before uploading the texture to the GPU. This process is not cheap, and so you see that ugly flicker.

So clearly you need an image replacement technique that keeps texture size below the device maximum. A good solution can be found here. The approach is similar, but rather than a large indent to the left, you indent to the right by the width of the element and clip the element’s content. For example:

.html5logo {
  display: block;
  width: 128px;
  height: 128px;
  background: url(/img/html5-badge-128.png) no-repeat;
  text-indent: 100%;
  overflow: hidden;
  white-space: nowrap;
}

Now when you initiate a 3D transform on the element there will be no flicker! Try it out and see for yourself!