Developing modern web and mobile apps: using gwt-phonegap

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>
<html>
  <head>
    <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">
  </head>

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

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() {

 @Override
    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() {

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

phoneGap.initializePhoneGap();

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.