Using PhoneGap Build with Vaadin TouchKit

Note: Vaadin Touchkit has been discontinued. A community-supported version is available on GitHub.

At first, using PhoneGap Build to point to your Vaadin TouchKit apps seems like a breeze. Just create a simple config.xml and an index.html that redirects to your web site, and you have an app! Unfortunately, simply doing this is not robust. Mobile devices lose connectivity, and when they do your app not only stops working, it may appear to freeze up and have to be killed and restarted to get working again.

With the release of TouchKit v3.0.2 though, there is a solution! This article summarizes this solution, which was worked out over months of trial and error on Vaadin ticket 13250.

First, server side you need TouchKit v3.0.2. (The needed enhancements and fixes should roll into v4.0 at some point, but as of beta1 it isn’t there.) You also need to ensure that your VAADIN directory resources are being served up by a servlet extending TouchKitServlet. If you have a main application extending VaadinServlet, this needs to be changed to TouchKitServlet.

When your PhoneGap app runs, it loads your provided index.html file into an embedded WebKit browser. Only this file has access to the PhoneGap Javascript library, so it handles things like offline-mode detection, and passes this via messages to the iframe containing your server-provided application.

HTML

  1. <!DOCTYPE html>
  2. <html>
  3.   <head>
  4.     <meta charset="utf-8" />
  5.     <meta name="format-detection" content="telephone=no" />
  6.     <meta name="viewport" content="user-scalable=no,initial-scale=1.0" />
  7.     <meta name="apple-mobile-web-app-capable" content="yes" />
  8.     <meta name="apple-mobile-web-app-status-bar-style" content="black">
  9.     <title>My Application Name</title>
  10.     <style type="text/css">
  11.       html, body {height:100%;margin:0;}
  12.       .spinner {-webkit-animation: spin 6s infinite linear;}
  13.       @-webkit-keyframes spin {
  14.         0%  {-webkit-transform: rotate(0deg);}
  15.         100% {-webkit-transform: rotate(360deg);}
  16.       }
  17.     </style>
  18.   </head>
  19.   <body style='margin: 0px'>
  20.     <script type="text/javascript" src="cordova.js"></script>
  21.     <script>
  22.       function failedIframe() {
  23.         document.getElementById('offline').style.display = 'none';
  24.         document.getElementById('spinner').className = '';
  25.         document.getElementById('retry').style.display = 'block';
  26.       }
  27.       function retryIframe() {
  28.         document.getElementById('offline').style.display = 'block';
  29.         document.getElementById('spinner').className = 'spinner';
  30.         document.getElementById('retry').style.display = 'none';
  31.         setTimeout(failedIframe, 20000);
  32.         document.getElementById('app').src = document.getElementById('app').src;
  33.       }
  34.       // Use cordova network plugin to inform the iframe about the connection
  35.       document.addEventListener('deviceready', function() {
  36.         if (!navigator.network || !navigator.network.connection || !Connection) {
  37.            console.log(">>> ERROR, it seems cordova network connection plugin has not been loaded.");
  38.            return;
  39.         }
  41.         var iframe = document.getElementById('app');
  42.         var loading = document.getElementById('loading');
  43.         var offline = document.getElementById('offline');
  45.         function sendMessage(msg) {
  46.           iframe.contentWindow.postMessage("cordova-" + msg, "*");
  47.         }
  49.         function check() {
  50.           var sts = navigator.network.connection.type == Connection.NONE ? 'offline' : 'online';
  51.           sendMessage(sts);
  52.         }
  53.         function showIframe(ev) {
  54.           if (loading.parentNode) {
  55.             loading.parentNode.removeChild(loading);
  56.             document.getElementById('app').style.width = iframe.style.height = "100%";
  57.             sendMessage('resume');
  58.           }
  59.           navigator.splashscreen.hide();
  60.         }
  61.         function showOffline() {
  62.           document.getElementById('offline').style.display = 'block';
  63.           navigator.splashscreen.hide();
  65.           // if after a while we have not received any notification we show the retry link
  66.           setTimeout(failedIframe, 20000);
  67.         }
  69.         // Listen for offline/online events
  70.         document.addEventListener('offline', check, false);
  71.         document.addEventListener('online', check, false);
  72.         document.addEventListener('resume', function(){sendMessage('resume')}, false);
  73.         document.addEventListener('pause', function(){sendMessage('pause')}, false);
  74.         // check the connection periodically
  75.         setInterval(check, 30000);
  77.         // when vaadin app is loaded, it sends to the parent window a ready message
  78.         window.addEventListener('message', showIframe, false);
  80.         // If the app takes more than 3 secs to start, proly .manifest stuff is being loaded.
  81.         setTimeout(showOffline, 3000);
  83.         // Ignore back button in android
  84.         // document.addEventListener('backbutton', function() {}, false);
  85.       }, false);
  86.     </script>
  87.     <!-- A div to show in the meanwhile the app is loaded -->
  88.     <div id='loading' style='font-size: 120%; font-weight: bold; font-family: helvetica; width: 100%; height: 100%; position: absolute; text-align: center;'>
  89.       <div id='spinner' class='spinner'><img src="spinner.png"></div>
  90.       <div id='offline' style='display: block;  padding: 15px;'>Downloading application files,<br/>Please be patient...</div>
  91.       <div id="retry" style="display: none;">
  92.         <p>Failed to contact the server.</p>
  93.         <p>
  94.           Please ensure you have a stable Internet connection, and then
  95.           <a href="javascript:void(0)" onclick="retryIframe();">touch here</a> to retry.
  96.         </p>
  97.       </div>
  98.     </div>
  99.     <!-- Load the app in an iframe so as we can pass messages, instead of using redirect -->
  100.     <iframe id='app' style='width: 0px; height: 0px; position: absolute; border: none' src='http://www.example.com/touch/'></iframe>
  101.   </body>
  102. </html>

Change the <title> and URL in the iframe at the end to match your app. This also expects a file named spinner.png along side index.html, which will be displayed and spin while loading application files from the server.

This Javascript handles detecting when the app goes offline and back online (and passes that to TouchKit), provides user feedback during a long initial load, and provides a friendly retry mechanism if the app is initially run without network access. It also hides the initial splashscreen.

PhoneGap Build requires a config.xml file to tell it how to behave. Below is a working example that works to create Android 4.0+ and iOS 6 & 7 apps.

XML

  1. <?xml version="1.0" encoding="UTF-8"?>
  2. <!DOCTYPE widget>
  3. <widget xmlns="http://www.w3.org/ns/widgets" xmlns:gap="http://phonegap.com/ns/1.0"
  4.         id="com.example.myapp" version="{VERSION}" versionCode="{RELEASE}">
  5.   <name>My App Name</name>
  6.   <description xml:lang="en"><![CDATA[
  7. Describe your app. This only shows on PhoneGap - each app store has you enter descriptions on their systems.
  8. ]]>
  9.   </description>
  10.   <author href="http://www.example.com">
  11.       Example Corp, LLC
  12.   </author>
  13.   <license>
  14.       Copyright 2014, Example Corp, LLC
  15.   </license>
  17.   <gap:platform name="android"/>
  18.   <gap:platform name="ios"/>
  20.   <gap:plugin name="com.phonegap.plugin.statusbar" />
  21.   <gap:plugin name="org.apache.cordova.network-information" />
  22.   <gap:plugin name="org.apache.cordova.splashscreen" />
  23.   <feature name="org.apache.cordova.network-information" />
  25.   <icon src="res/ios/icon-57.png"       gap:platform="ios" width="57"  height="57"  />
  26.   <icon src="res/ios/icon-57_at_2x.png" gap:platform="ios" width="114" height="114" />
  27.   <icon src="res/ios/icon-72.png"       gap:platform="ios" width="72"  height="72"  />
  28.   <icon src="res/ios/icon-72_at_2x.png" gap:platform="ios" width="144" height="144" />
  29.   <icon src="res/ios/icon-76.png"       gap:platform="ios" width="76"  height="76"  />
  30.   <icon src="res/ios/icon-76_at_2x.png" gap:platform="ios" width="152" height="152" />
  31.   <icon src="res/ios/icon-120.png"      gap:platform="ios" width="120" height="120" />
  33.   <icon src="res/android/icon-36-ldpi.png"  gap:platform="android" width="36" height="36" gap:density="ldpi"/>
  34.   <icon src="res/android/icon-48-mdpi.png"  gap:platform="android" width="48" height="48" gap:density="mdpi"/>
  35.   <icon src="res/android/icon-72-hdpi.png"  gap:platform="android" width="72" height="72" gap:density="hdpi"/>
  36.   <icon src="res/android/icon-96-xhdpi.png" gap:platform="android" width="96" height="96" gap:density="xhdpi"/>
  37.   <icon src="res/android/icon-96-xxhdpi.png" gap:platform="android" width="96" height="96" gap:density="xxhdpi"/>
  39.   <gap:splash src="res/ios/Default.png"              gap:platform="ios" width="320"  height="480" />
  40.   <gap:splash src="res/ios/Default@2x.png"           gap:platform="ios" width="640"  height="960" />
  41.   <gap:splash src="res/ios/Default_iphone5.png"      gap:platform="ios" width="640"  height="1136"/>
  42.   <gap:splash src="res/ios/Default-Landscape.png"    gap:platform="ios" width="1024" height="768" />
  43.   <gap:splash src="res/ios/Default-Portrait.png"     gap:platform="ios" width="768"  height="1004"/>
  44.   <gap:splash src="res/ios/Default-568h.png"         gap:platform="ios" width="320"  height="568" />
  45.   <gap:splash src="res/ios/Default-568@2x.png"       gap:platform="ios" width="640"  height="1136"/>
  46.   <gap:splash src="res/ios/Default-Landscape@2x.png" gap:platform="ios" width="2048" height="1496"/>
  47.   <gap:splash src="res/ios/Default-Portrait@2x.png"  gap:platform="ios" width="1536" height="2008"/>
  49.   <gap:splash src="res/android/splash-ldpi.9.png"  gap:platform="android" gap:density="ldpi" />
  50.   <gap:splash src="res/android/splash-mdpi.9.png"  gap:platform="android" gap:density="mdpi" />
  51.   <gap:splash src="res/android/splash-hdpi.9.png"  gap:platform="android" gap:density="hdpi" />
  52.   <gap:splash src="res/android/splash-xhdpi.9.png" gap:platform="android" gap:density="xhdpi"/>
  54.   <!-- PhoneGap version to use -->
  55.   <preference name="phonegap-version" value="3.4.0" />
  57.   <!-- Allow landscape and portrait orientations -->
  58.   <preference name="Orientation" value="default" />
  60.   <!-- Don't allow overscroll effects (bounce-back on iOS, glow on Android.
  61.        Not useful since app doesn't scroll. -->
  62.   <preference name="DisallowOverscroll" value="true"/>
  64.   <!-- Don't hide the O/S's status bar -->
  65.   <preference name="fullscreen" value="false" />
  67.   <!-- iOS: Obey the app's viewport meta tag -->
  68.   <preference name="EnableViewportScale" value="true"/>
  70.   <!-- iOS: if set to true, app will terminate when home button is pressed -->
  71.   <preference name="exit-on-suspend" value="false" />
  73.   <!-- iOS: If icon is prerendered, iOS will not apply it's gloss to the app's icon on the user's home screen -->
  74.   <preference name="prerendered-icon" value="false" />
  76.   <!-- iOS: if set to false, the splash screen must be hidden using a JavaScript API -->
  77.   <preference name="AutoHideSplashScreen" value="false" />
  79.   <!-- iOS: MinimumOSVersion -->
  80.   <preference name="deployment-target" value="6.0" />
  82.   <!-- Android: Keep running in the background -->
  83.   <preference name="KeepRunning" value="true"/>
  85.   <!-- Android: Web resource load timeout, ms -->
  86.   <preference name="LoadUrlTimeoutValue" value="30000"/>
  88.   <!-- Android: The amount of time the splash screen image displays (if not hidden by app) -->
  89.   <preference name="SplashScreenDelay" value="3000"/>
  91.   <!-- Android: Minimum (4.0) and target (4.4) API versions -->
  92.   <preference name="android-minSdkVersion" value="14"/>
  93.   <preference name="android-targetSdkVersion" value="19"/>
  94. </widget>

The listed plugins are all required to make the splash screen and offline-mode work properly. The slew of icons and splash screen .png file are required by the app stores, so be sure to include all of them in the source .zip that you upload to PhoneGap Build. Placing these files in a subdirectory allows you to also put an empty file named “.pgbomit” in that folder, which ensures that extra copies of each of these file are not included in the file app package produced by PhoneGap Build.

Special thanks to “manolo” from Vaadin for working with me for over a month to make all of this work by creating enhancements to TouchKit and the index.html file that the above one is based on.