Sunday, July 22, 2012

using gwt-phonegap

This post is part of a series of blogposts that show the usage of  some mgwt / gwt-phonegap components.

For quite a while I wanted to write a blog post on how to use mgwt and phonegap together to write great mobile apps.
While mgwt provides all the mobile widgets, animations and touch support you need, gwt phonegap provides access to the phonegap api.
Combining them means being able to write mobile apps with GWT that look beautiful and behave exactly like native apps.

Some background
GWT compiles Java to Javascript. With Phonegap you can write Apps in Javascript. Basically we just need to take the output of the GWT Compiler and put it on the phone.

Which files to include
In general you will have a html host page, like you have with any GWT app. With a phonegap app this will include at least the javascript for the phonegap api (cordova-x.x.x.js) and your gwt no cache file.
An example html host file would look like this:

<!doctype html>
    <meta http-equiv="content-type" content="text/html; charset=UTF-8">
    <title>name of your app
    <!-- phonegap api -->
    <script type="text/javascript" language="javascript" src="cordova-1.x.x.js"></script>
    <!-- gwt module include -->
    <script type="text/javascript" language="javascript" src="yourgwtmodule/yourgwtmodule.nocache.js">

   <!-- gwt history frame -->
    <iframe src="javascript:''" id="__gwt_historyFrame" tabIndex='-1' style="position:absolute;width:0;height:0;border:0">

You can see the include for the phonegap api. Note: It is important that phonegap is included first!

I would recommend keeping the html host file seperate from the one you are using for a web app, since with a web app you will not have a phonegap include.
Your deployment script however needs to copy the complete module folder (gwt output) as well as other needed resources to the phonegap www folder.

In Phonegap all HTML + CSS + Javascript files need to be inside the www folder of your phonegap project. If you are using phonegap plugins you might also be adding code. (Java for Android, Objective-C for iOS and so on)
If you have never used phonegap you might also be interested in a good guide on how to setup phonegap.

The gwt phonegap part gives instructions on how to setup a GWT with gwt phonegap.
The main idea behind gwt phonegap is to provide two implementations of the phonegap api: one that is using the phonegap javascript API on a device and the other is a pure emulation api that enables developers to build phonegap apps while running gwt dev mode.
To ensure that there are no runtime penalties gwt phonegap uses deferred binding and compiles different implementations for emulation and phonegap environment. This is done by the phonegap.env variable.

This means that you can use any phonegap module inside the browser and still call all phonegap api. (For specific limitations see every modules documentation )

A simple Hello World Phonegap demo would look like this:

final PhoneGap phoneGap = GWT.create(PhoneGap.class);

phoneGap.addHandler(new PhoneGapAvailableHandler() {

    public void onPhoneGapAvailable(PhoneGapAvailableEvent event) {
     // build your ui and caLet ll phonegap
        String phoneGapVersion = phoneGap.getDevice().getPhoneGapVersion();
        RootPanel.get().add(new HTML("Using phonegap version: " + phoneGapVersion));


phoneGap.addHandler(new PhoneGapTimeoutHandler() {

    public void onPhoneGapTimeout(PhoneGapTimeoutEvent event) {
        Window.alert("can not load phonegap");


Summary - Setup Projects
Let me walk you through the necessary steps to get a GWT app on a phone with phonegap.
I am assuming that you set up a phonegap project as described in the phonegap documentation for your plattform.
This is the shell for your web app to run on a phone. It has a www folder where we will store our web app.

The next step is to setup a standard GWT project.
In this project you need to at the gwtphonegap-1.x.x.x.jar to your classpath. You can do this manually or use maven to do this.
After adding the jar to your classpath you need to add the following line to your gwt xml file:

     <inherits name='com.googlecode.gwtphonegap.PhoneGap' />

This tells the GWT compiler that you want to use the gwt phonegap project. After that you can start using the phonegap object in your code (see example).

At one point you want to get your application on an actual phone. Now you have to compile the app using the GWT compiler and copy the output of the GWT project (your module folder) to your www folder of your phonegap project.

For a a release of an app you only want to copy the relevant files for the actual permutation. mgwt has a special permutation map linker for that. It outputs xml that lets you easily find the necessary files for the right devices. This will be covered in another blog post.


  1. I am getting white screen after I added all war file from GWT to www folder in phonegap. How can I fix it?

  2. there is a user group where you will find help on using gwt-phonegap and mgwt:

  3. Hi Daniel.

    Thanks for your links, really useful.

    I have a question:

    Is it possible to provide the application via Browser instead of Apps for each Platform using Gwt - PhotoGap? If so, do you know how permutations would work?

    Thank you very much

  4. If you want to run you app inside the browser you can just skip gwt-phonegap and just use mgwt.

  5. Hi Daniel,
    I have started working on mgwt and phone recently and i am facing this problem.
    I have compiled my code and added the output in the www folder, however i am not able to see the changes that i made to the code. The code compiled properly and did not show any error. The app still runs as per the old code.
    Please help !!
    Thank you :)

  6. For building cross platform mobile applications Phonegap is widely used. PhoneGap is an open source framework. The developers build use of Html rule, CSS, and JavaScript to make impressive and rich applications. This kind of blogs helps to build mobile applications in useful manners.

  7. Hi Daniel,
    I use the latest version of GWT i.e 2.8 rc1 and use gwt maven plugin to compile and copy the contents to www folder of phonegap application. I observed that when i use gwt maven plugin, i only get a blank screen and no errors in the xcode console. However this works when i compile use eclipse plugin in super dev mode. Do you know what could be the reason for this behaviour?


  8. Hi Daniel,
    This works only when I use super dev mode and it recompile the .nocache.js script to point to the super dev server. In the production mode with just gwt maven plugin, it shows only white screen. Do you know why this happens? I generated phonegap build for browser and I am able to launch the index.html file without any errors.

    Please throw some light on this issue.