Packaging web apps using PhoneGap

What is PhoneGap?

I guess not that many remember it anymore, but Apple started the new era of mobile computing with web apps only. You can do quite a lot with just plain web technologies and make mobile websites appear like normal apps on your homescreen. In many cases this is the best way to distribute mobile software. You have full control of your application, you are not tied to any special terms of the distributor and you don’t need to share your revenues with the distributor.

Since distributing native apps via “apps stores” became a huge business, various mobile platforms have kept web applications as kind of second-class citizens and even not letting plain web apps to app stores at all. As a workaround, web developers have been using a product called PhoneGap, or its open source sister Cordova, as a method to package web apps as “native apps”. Using it, web apps are “framed” using a chromeless browser and then distributed as native apps via apps stores.

By packaging web apps as native app bundles, it is also possible to do certain tricks that are not possible for web apps. Most of these boundaries, like accessing cameras, are fading away slowly, but there are still some features that just aren’t available for web apps - unless wrapped into a native app bundle.

We have already covered PhoneGap and using the PhoneGap Build service to package Vaadin apps as installable bundles a couple of years ago. Since then the build service has been improved and Vaadin has moved on to version 7, so it is definitely time for a recap.

Embedding a Vaadin application

Normally, Vaadin applications run on an html page generated by the Vaadin servlet. But they can easily be embedded on a different “host page” as well to create mashups). In this approach we embed the Vaadin application directly in the index.html of the PhoneGap bundle.

There are instructions in the Book of Vaadin on how to embed Vaadin applications and they apply well to this case as well. To the top of the page, one should also include javascript for PhoneGap and the possible plugins which are used in the application.

    <script type="text/javascript" src="phonegap.js"></script>

TouchKit apps by default implement “strong caching” using HTML5 cache manifest, but you can also add the VAADIN-folder into your PhoneGap project. This folder contains static files like the widgetset compiled by GWT, themes and the bootsrap.js file. This way all static files are downloaded to the end user during the installation of the app. As a downside, you have to update the application bundle every time you make changes to the client side, for example, when you add a new Vaadin add-on to your project.

When you embed a Vaadin application in the html file of your PhoneGap project, you are able to use the Adobe PhoneGap build service. This way you don’t need to set up a development environment for each and every platform you are going to support. Also adding new plugins is straightforward. You just need to configure them to config.xml and index.html files as you normally do with PhoneGap projects. On top of that, you can create client side components or extensions to integrate with them from Vaadin applications.

The downside with this approach is that when you make modifications to your PhoneGap project, for example add a camera plugin, you also need to update the native application. If your user has not yet updated the native app, your Vaadin application should be able to support also the old wrapper without the camera plugin or ask the user to update.

To overcome this, another approach can also be tried. The host page and various PhoneGap helpers can also be served from the server. To do this you can move the index.html to the server and reference that with the tag in config.xml. The folder /platforms/android/assets/www/ in your PhoneGap project can also be moved to the server. This works to some extent, but it also has its drawbacks. First of all, there should be separate www-folders for each device in the server. Second, offline mode does not work at all. Instead, you will get an error that the file referenced with the tag is not available.

During this integration example, PhoneGap Build’s PushPlugin was also prototyped. Using it, the server can send push notifications to an Android and iOS application, even though the target app in the devices is not running. Setting it up is pretty easy, but we’ll discuss that later in a another blog post.

Check out the example sources


Install example app from PhoneGap Build

PS. Only Android build is relevant for testing as other platforms require signed packages.

Trackback URL:

Add Comment
You should always include cordova.js. phonegap.js is just there for backward compatibility.
Posted on 6/12/14 5:50 PM.
More information on integrating with PhoneGap in the Wiki.
Posted on 6/12/14 6:48 PM.
As an additional info, TouchKit 3.0.2 and 4.0.0.beta1 includes hacks for interacting with phonegap events so as we can notify easily whether the Vaadin app is offline/online/paused/resumed. That fixes android issues. More info at:
Posted on 6/13/14 8:35 AM.
Nice work with the offline mode Adam and Manuel. I have updated my example to use Touchkit 4.0.0.beta1 so you can try out the offline mode with it. I already did and it works like a charm.
Posted on 6/17/14 7:59 AM in reply to Manuel Carrasco.
PhoneGap Build supports native application packaging for the ios, Android, Blackberry and windows 8 .Dreamweaver CS5.5 now includes integration with PhoneGap. The integration between the two is flawless, and you need not to know anything about PhoneGap to take benefit of its functionality.
Posted on 7/7/14 9:36 AM.