Sencha Touch 2 and PhoneGap (aka Apache Callback) - getting started

Hello there! If you are new here, you might want to subscribe to the RSS feed for updates on this topic.

What are Sencha Touch and PhoneGap?

The combination of Sencha Touch and PhoneGap is alluring for someone wanting to rapidly prototype mobile applications:

Sencha Touch provides a framework for developing HTML5/CSS apps targeted at mobile devices, providing classes for common UI elements, database functions and the like, all of which can be accessed using object-oriented JavaScript
PhoneGap packages those apps (trees of html/css/js files) into native app wrappers (which can then be submitted to app stores for iPhone etc.). It also provides APIs to allow your JavaScript to access native device features (e.g. Camera) which are otherwise not available to ‘web’ apps.

Both of these frameworks are free：

Sencha Touch can be licensed either commercially (free as in ‘free beer’) or open source (free as in ‘freedom’)
PhoneGap is in the process of becoming an Apache Project

Before I started to write a sample application, I thought I could just write a Sencha Touch app, drag it into a PhoneGap project, and let it run. However, I came across a few humps along the way. I’m writing this post in part as a reminder to myself, but I hope it will be useful to anyone at a similar stage in their ST2/PhoneGap journey.

Smoothing the path

Below is a list of suggestions/information I with I’d had when I started. I’m writing this post in part as a reminder to myself, but I hope it will be useful to anyone at a similar stage in their ST2/PhoneGap journey.

Sencha Touch 2 is new

It has significant differences from Sencha Touch 1.1 (not least dynamic loading of classes, and more ‘convention’). At the time of writing (November 2011), there are very few great documents about Sencha Touch 2. However, there is a 3-part article series on Sencha’s web site which, whilst targeted at ExtJS, is mostly applicable to Sencha Touch 2. Parts 2 and 3 in particular are good for reference.

You will want to pay particular attention to:

Class naming: you need to pay attention to how you namespace your classes and design your folder structure. Your app’s top-level folder structure should match your app’s namespace. To keep things simple, I called my app App. So, inside my PhoneGap project, I have folders like App/model, App/controller etc. The App folder name matches my App name defined in app.js:

 Ext.application
    name:'App', // The folder name should match this
    controllers: ['Main'], //Small app, so all functions in one controller
    models: [], //If your app has models, reference them here
    stores: [], //If your app has stores, reference them here
    launch: function() {
        Ext.create('App.view.Viewport');
    }
});

Architect your app as MVC from the start. You may regret it if you don’t.
Use auto-loading of classes only during development. Put in the relevant ‘Ext.require’ statements when you deploy. Auto-loading of classes works fine when you’re accessing a Sencha Touch 2 app via a web browser on a server, but it breaks when you’re accessing it from a local filesystem (which is the situation when you deploy with PhoneGap). Whilst knowing when to use ‘Ext.require’ may seem a pain, it’s actually easy. Assuming you are using the ‘debug-with-comments’ version of the sencha-touch.js file, you will see messages in your JavaScript debugger (e.g. Safari’s Web Inspector) giving you recommendations for adding Ext.require statements. Just follow these recommendations until you don’t see any more of them. Once that’s done, you know your app is ready to try off a local filesystem.

PhoneGap isn’t a browser

It might be tempting to think of PhoneGap as ‘just another WebKit browser’. Whilst this is sort of true, you need to be aware that:

Unlike most browsers, there’s no JS debugger built-in. Therefore, once your app works fine on your desktop browser, plug it into the weinre debugger so that you can see what’s happening. If you don’t do this, your app might show just a blank screen, and you’ll have no way to figure out what went wrong.
Unlike most browsers, you can’t just access any web site you want. PhoneGap has a whitelist of web sites to which requests will be allowed. You will want to add localhost to that (otherwise weinre won’t work), as well as any places from which you’re loading images, scripts or JSON/XML.
Like most browsers, you can’t just load JSON files from the local filesystem. Therefore, an app which relies on a local JSON database might work fine when you access it via a local web server, but the JSON will fail to load if you run it from the local filesystem (using your desktop browser) or using PhoneGap. There are workarounds, but they are outside the scope of this post. You can Google ‘sencha touch scripttag jsonp’ to see some info.

Share/Bookmark