Wednesday, 27 February 2013

Launch a website as a mobile app using PhoneGap/Apache Cordova


How to launch a website as a mobile app using PhoneGap/Apache Cordova


I spent some time recently trying to find out how to launch my website as a mobile app.  The information was available around the internet but since it took me a while, I thought I'd collate it here in one simple post for anyone who wants to do the same

I decided to use Apache Cordova since it gave me the framework for developing an HTML5 site as a mobile app already, meaning all I really needed to do was plug my website into it.  Their getting started guide has good information on how to create a Cordova project - I used Android but you can use whatever means you wish

A basic Cordova app gives you a way to launch the app with an HTML page that you use to display your app contents.  The trick then is make the page load your website which you can do in one of 3 ways:

1. Package your site inside the app. This means it loads fast and without an internet connection.  The downside is you have to update and re-release the app whenever your website changes. It also needs to use relative paths since the root directory will be the mobile device's root directly, not the root of your site
2. Point the page at your remote website, which means changes are picked up immediately.  The downside is that it won't work if the phone has no internet connection
3. Do both and fall back to the local site if there is no network connection

Option 1 - Package your website inside the app

If you want to do option 1 (package your site with the app) you simply copy your entire site into the assets > www directory which will load your homepage as a local page (I think PhoneGap Build insists this is index.html, but if you're loading from code you just launch Cordova with that page name). Simple. You need not read on unless you're interested in option 2 or 3

Option 2 - launch your external website inside the app

To load a remote site, you need to load your homepage (or any page) using javascript from the html page that Cordova will open in your app.  This is relatively simple using basic javascript
window.location="http://your.website";

The recommended way to run javascript in a Cordova environment is to use Cordova's ondeviceready event which ensures it is loaded, which can be hooked into your page

document.addEventListener("deviceready", onDeviceReady, false); 
function onDeviceReady() {
    // Now safe to use the Codova API
window.location="http://your.website"; }

This is probably not strictly necessary for this javascript call, which is not using the Cordova API.  However I am using because it is needed for option 3

You also need to tell Cordova that it is safe to load your website in the cordova.xml properties (you can remove the subdomains part if you don't have any)
<access origin="http://your.website" subdomains="true"/>

At this point you are good to go!

Option 3 - launch your external website but fail back to local version

This option requires a little more work but gives you the advantage of displaying a set of files packaged with the app if there is no internet connection

Since you need the html page given by Cordova in assets > www you will need to copy your local site to a subdirectory (I've called it local), and do everything in option 2 to load the remote site

All you need then is to add some logic to decide whether there is an internet connection and act accordingly.  Fortunately Cordova gives us a solution to this

Firstly, add a javascript function to check the connection type

   function checkConnection() {
         var networkState = navigator.network.connection.type;
         var states = {};
         states[Connection.UNKNOWN]  = 'Unknown connection';
         states[Connection.ETHERNET] = 'Ethernet connection';
         states[Connection.WIFI]     = 'WiFi connection';
         states[Connection.CELL_2G]  = 'Cell 2G connection';
         states[Connection.CELL_3G]  = 'Cell 3G connection';
         states[Connection.CELL_4G]  = 'Cell 4G connection';
         states[Connection.NONE]     = 'No network connection';
       
         return networkState;
       
     }

Then add some logic around the window.location call to load the appropriate site

   function onDeviceReady() {
   var networkState = checkConnection();
 /* load local files if there is not network connection */
                  if (networkState == Connection.NONE) {
                      window.location="local/index.html";
                  } else {
              window.location="http://your.website";
                  }
   }

Again, you're good to go!

As an alternative to option 2 or 3 (I'll call it option 2a) you could use the connection type logic to display an error message so you don't attempt to load the external site when there is no connection eg:

   function onDeviceReady() {
   var networkState = checkConnection();
 /* load local files if there is not network connection */
                  if (networkState == Connection.NONE) {
                  navigator.notification.alert('This app requires an internet connection');
                  } else {
               window.location="http://your.website";
                  }
   }
I'm going to wrap a framework around this and release some instructions for non-developers to produce site launchers for mobile devices using PhoneGap build.  Watch this space

Tuesday, 26 February 2013

Android Daydream with Processing.js

How to create an Android Daydream with processing.js

I've spent some time working out how to get processing.js (a nice javascript graphics library ported from Processing) to display an Android Daydream (basically a screensaver that activates when the device is docked or charging)

I previously wrote about how to display an HTML page as a Daydream which forms the basis for this post.  Please see my earlier post for full details but to summarise you can load an HTML page in a webview like this
webView.loadUrl("file:///android_asset/www/index.html");

Processing.js allows you to display Processing code as javascript in a page, so all you need to do is either embed the processing.js code or load the Processing PDE file containing the code as explained on the processing.js site

I only had a couple of issues with it which were:

1. The js code seemed to run at a much higher frame rate than my native Processing code such that my animation looked insane. In the end I just reduced the frame rate to 8
 void setup() {
    frameRate(8);
 }

You might need to play with the rate for your particular animation

2. screen.width and screen.height didn't seem to work correctly and displayed my animation off the bottom of the screen.  Using window.innerWidth and window.innerHeight had the desired effect
    size(window.innerWidth, window.innerHeight);

You can test it in a local browser simply by loading the HTML page into Firefox/Chrome/whatever.  Once it's working, just follow the instructions from my earlier post to set it up as a Daydream and you're good to go :)


I've added this and released it with my Android app and will see what people think

As always, if you have any questions just let me know


Daydream running on my phone
Daydream installed