PhonegapIntegration (Smart GWT EE API 4.0p (2021-05-01))

```
public interface PhonegapIntegration
```
Integration with PhoneGap

PhoneGap documentation, quick start information, and programming guides are available at http://www.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.
General Instructions
For each target that PhoneGap supports, there is a special www/ folder which contains the application JavaScript code and other assets. If the www/ folder was created for you, the only file that is needed within is cordova-x.x.x.js. All other files can be deleted.
Copy your compiled Smart GWT application into the www/ folder. 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-x.x.x.js:
```
    <script type="text/javascript" charset="UTF-8" language="JavaScript"
 src="cordova-x.x.x.js"></script>
```
  NOTE: There is a cordova-x.x.x.js for each target that PhoneGap supports; they are different scripts. To set up a single codebase for multiple targets, see the section titled Multi-Target Codebase below.
- 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="user-scalable=no, initial-scale=1, minimum-scale=1,
 maximum-scale=1, width=device-width">
```
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" language="JavaScript">
 document.addEventListener("deviceready", function onDeviceReady() {
     window.isDeviceReady = true;
     document.removeEventListener("deviceready", arguments.callee, false);
 }, false);
 </script>
```
iOS Targets (iPhone & iPad)
Beginning with PhoneGap / Cordova 2.0.0, special command-line tooling has been introduced which replaces the custom Xcode project templates. To create a new project, the create program located at $PHONEGAP_SDK/lib/ios/bin/create is used:
```
$PHONEGAP_SDK/lib/ios/bin/create path/to/my_cordova_project com.MyCompany.ProjectName
 ProjectName
```
1. Open Terminal and run $PHONEGAP_SDK/lib/ios/bin/create MyMobileApp-iOS com.mycompany.MyMobileApp MyMobileApp
2. Within the newly-created MyMobileApp-iOS/ folder, open the Xcode project MyMobileApp.xcodeproj.
3. Follow the General Instructions above.
4. In Xcode, using the scheme selector toolbar, set the Scheme to MyMobileApp > iPhone 6.0 Simulator or some other simulator destination. Then click the Run button. Xcode will start the iOS Simulator and run the app.
5. 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.
You can make changes to your application and re-run it in the simulator without needing to close Xcode:
1. Stop the application if running.
2. Select Product -> Clean
3. Click the Run button.
Once you have completely tested the application within the simulator, you should test the app on real hardware. Refer to Apple's Tools Workflow Guide for iOS for complete instructions on provisioning the app for testing devices, in particular, the section titled Sending Your App to Testers. Note that you will need to set the Scheme destination to MyMobileApp > iOS Device for the Product -> Archive menu option to be available.
Android Targets
To begin targeting Android devices, follow the instructions on the Getting Started with Android guide. After creating the new Android app project, follow the General Instructions above.
It is helpful to monitor the LogCat 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-x.x.x.js script is being used. You must use the cordova-x.x.x.js for Android.
- Data exceeds UNCOMPRESS_DATA_MAX
  There is a limit to the size of individual Android app assets, typically 1 Megabyte. 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 Smart GWT application was compiled in DETAILED or PRETTY mode.
Multi-Target Codebase
There is a cordova-x.x.x.js for each target that PhoneGap supports; they are different scripts. To target multiple platforms using a single codebase, it can be useful to employ a "script changer" to load the correct cordova-x.x.x.js:
```
<script type="text/javascript" language="JavaScript">
     var scriptName;
     if (navigator.userAgent.indexOf("Android") > -1) {
         scriptName = "cordova-2.3.0-android.js";
 } else if (navigator.userAgent.indexOf("iPhone") > -1 || navigator.userAgent.indexOf("iPad")
 > -1) {
         scriptName = "cordova-2.3.0-iOS.js";
     }
     if (scriptName) document.write("<script type='text/javascript' charset='UTF-8' " +
           "language='JavaScript' src='" + encodeURI(scriptName) + "'><" + "/script>");
 </script>
```
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-x.x.x.js. Additionally, GWT's JavaScript overlay types feature is used to easily wrap the PhoneGap Contacts API for use by the Smart GWT app.

Interface PhonegapIntegration

Integration with PhoneGap

General Instructions

iOS Targets (iPhone & iPad)

Android Targets

Multi-Target Codebase

Samples