public interface PhonegapIntegration

Integration with PhoneGap

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.

Installing PhoneGap

Beginning with PhoneGap 2.9.0, PhoneGap is an NPM (Node.js Packager Manager) package. You will need to install Node.js first in order to install PhoneGap. (Tip for Mac users: Homebrew is a simple and easy way to install the latest version of Node.js and npm: brew install node)

Once Node.js is installed, see http://phonegap.com/install/ for instructions on installing PhoneGap.

Creating the PhoneGap Project

Use the 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.

General Instructions

Within the project folder, PhoneGap creates a special 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:

Change the DOCTYPE to the HTML5 DOCTYPE: <!DOCTYPE html>
Add a <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.

Ensure that the following <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 &lt/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.

iOS Platform (iPhone & iPad)

Open Terminal, cd into the project folder, and run:
```
phonegap build ios
```
Within the newly-created platforms/ios/ folder, open the Xcode project MyMobileApp.xcodeproj.
In Xcode, set the active scheme to MyMobileApp > iPhone Retina (4-inch) > iOS 7.0 or some other simulator destination. Then click the Run button. Xcode will start the iPhone Simulator and run the app.
When you are finished testing the application in the simulator, click the Stop button.

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.

Apple has deprecated UIWebView and we recommend switching to the officially supported WKWebView plugin to resolve momentum scrolling issues and obtain more Safari-like behavior.

Android Platform

To begin targeting Android devices, follow the instructions on the Android Platform Guide.

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.

Samples

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.