public interface PhonegapIntegration
PhoneGap documentation, quick start information, and programming guides are available at http://phonegap.com.
PhoneGap exposes a Contacts API which allows one to find, create and remove contacts from the device's contacts database. Unlike Titanium, which provides many native UI components, PhoneGap relies on 3rd party frameworks for UI components. Additionally, PhoneGap provides no transitions or other animation effects normally accessible in native applications.
In the following guide, the name "MyMobileApp" refers to a Smart GWT mobile application. The instructions are intended to be general, and applicable to other apps by simply substituting the application name and the few other app-specific details.
brew install node)
Once Node.js is installed, see http://phonegap.com/install/ for instructions on installing PhoneGap.
phonegap command line utility
to create a new folder containing the project files:
phonegap create --id com.mycompany.apps.MyMobileApp --name "MyMobileApp" path/to/project_folder
The project ID and name should be changed for your app.
www/ folder which contains
the application JavaScript code and other assets. Within this folder, only
config.xml
is needed. All other files of the default "Hello PhoneGap" app can be deleted.
You will need to open the application's main HTML file in a text editor to make a few changes:
<!DOCTYPE html><script> tag to the <head> element to load
cordova.js:
<script type="text/javascript" charset="UTF-8" src="cordova.js"></script>
NOTE: The www/ folder should not contain cordova.js.
In other words, don't try to copy cordova.js into the www/ folder.
PhoneGap automatically adds the appropriate version of this script, which is different for
each platform.
<meta> tags are used, also in the
<head> element:
<meta http-equiv="Content-Type" content="text/html;charset=UTF-8"> <meta name="format-detection" content="telephone=no"> <meta name="viewport" content="initial-scale=1, width=device-width, user-scalable=no, minimum-scale=1, maximum-scale=1">
After making those changes, you will need to defer starting the application until the
deviceready event has fired,
particularly if your application invokes any PhoneGap API function.
To accomplish this in Smart GWT, it is helpful to use a utility class together with a bit
of JavaScript.
The following utility class can be used to defer the onModuleLoad code until
PhoneGap is ready:
package com.mycompany.client;
import com.google.gwt.core.client.EntryPoint;
public abstract class CordovaEntryPoint implements EntryPoint {
@Override
public final native void onModuleLoad() /*-{
var self = this;
if ($wnd.isDeviceReady) self.@com.mycompany.client.CordovaEntryPoint::onDeviceReady()();
else {
var listener = $entry(function () {
$doc.removeEventListener("deviceready", listener, false);
self.@com.mycompany.client.CordovaEntryPoint::onDeviceReady()();
});
$doc.addEventListener("deviceready", listener, false);
}
}-*/;
protected abstract void onDeviceReady();
}
The CordovaEntryPoint class is used in conjunction with the following
JavaScript,
which should be added before the closing </body> tag:
<script type="text/javascript">
document.addEventListener("deviceready", function onDeviceReady() {
window.isDeviceReady = true;
document.removeEventListener("deviceready", onDeviceReady, false);
}, false);
</script>
After compiling your application with PhoneGap/Cordova support, copy the compiled
Smart GWT
application to the www/ folder.
cd into the project folder, and run:
phonegap build ios
platforms/ios/ folder, open the Xcode project
MyMobileApp.xcodeproj.It is helpful to pay attention to the output window when testing the app within iOS
Simulator.
The output window contains all logs to window.console and messages from the Cordova
framework itself. One common issue is ERROR whitelist rejection: url='SOMEURL',
which means that SOMEURL has not been added to <access origin="..."/> in
config.xml.
Refer to the Domain Whitelist Guide
for more information.
Once you have completely tested the application within the simulator, you should test the app on real hardware. Refer to Apple's App Distribution Guide for complete instructions on provisioning the app for testing devices, in particular, the section titled Beta Testing Your iOS App.
It is helpful to monitor the LogCat view in Eclipse to verify that your application is working correctly. Common errors include:
Application Error The protocol is not supported. (gap://ready)
This means that the incorrect cordova.js script is being used. You
must use the cordova.js for Android.
Try updating the 'android' platform to fix the problem:
phonegap platform update android
Data exceeds UNCOMPRESS_DATA_MAX
In older versions of Android (pre-2.3.3), there is a 1 Megabyte limit on the size of individual Android app assets. This error message means that one asset file exceeds this limit. You should see a popup alert dialog containing the name of the problematic file, and then the app will crash.
The "Data exceeds UNCOMPRESS_DATA_MAX" error can be seen if, for example, the SmartGWT.mobile application was compiled in DETAILED or PRETTY mode.
The Smart GWT Google Code project has a sample application called
MyContacts
which demonstrates how to work with the PhoneGap API in a Smart GWT app. The main
Smart GWT code is located at
trunk/samples/phonegap/MyContacts.
An Xcode project used to package the app for iOS devices is located at
trunk/samples/phonegap/MyContacts-iOS.
An Eclipse project used to package the app for Android devices is located at
trunk/samples/phonegap/MyContacts-Android.
This sample application utilizes the script changer technique to load the correct
cordova.js.
Additionally, GWT's JavaScript overlay types
feature is used to easily wrap the PhoneGap Contacts API for use by the Smart GWT app.