After I published the iOS version on the Apple App Store, a number of people asked for an Android version. I just published it on Google Play.




PhoneGap API Explorer is an API reference application for PhoneGap device integration capabilities. The application clearly presents the syntax for each function, and allows you to provide values for the function’s arguments, invoke the function from within the application, and see immediate results. PhoneGap API Explorer provides a unique and interactive learning experience.

You can read more about the application and watch a video in my initial post about the iOS release.

Source Code

The iOS and the Android versions share the exact same code. Some platform specific CSS styles are dynamically applied through device detection to provide a natural experience on each platform. I will make the source code available on GitHub soon, ready for you to build on PhoneGap Build.

Here are a few more screenshots:

In this article, I describe a simple data synchronization strategy that uses the device’s (or browser’s) SQLite database. The implementation currently leverages the Web SQL API (even though the W3C is no longer actively maintaining the spec) because both iOS and Android support it, but they don’t support IndexedDB, the official alternative. However, the API described below — getLastSync(), getChanges(), applyChanges() — defines a generic synchronization contract, and the solution can be expanded and made “pluggable”: You could create different synchronization objects, each providing a different implementation of these methods. You could then choose which object to plug in based on the context and the platform your application is running on.

Try it in the Playground

Before looking at the code, you can try some offline syncing in this a hosted playground:

1. Open the Offline Client Playground in Chrome or Safari (they both support Web SQL).
2. Click the Synchronize button.
3. Look at the log (the textarea in the middle of the screen): Because it’s the first time you use the application, all the employees have been downloaded from the server and inserted in your local SQLite database.
4. Clear the log, click the Synchronize button, and look at the log again: because you now have an up-to-date local version of the data, the server didn’t return any change and your local database remains unchanged.
5. In another tab, open the Server Admin PlayGround.
6. Modify an existing employee and click Save. (Don’t worry, it’s using your own session-based data set).
7. Go back to the Offline Client tab, click Synchronize, and notice that the server returned one change, and that it was applied to your local database.
8. Go back to the Server Admin tab and modify (create, update, delete) other employees. Switch back to the Offline Client tab, click Synchronize, and see how these changes are applied to your local database.
9. You can also use the Resources Tab in the Chrome Developer Tools to inspect your local database.

Server API

The only piece of infrastructure you need at the server side is an API that returns the items that have changed (created, updated, or deleted) since a specific moment in time expressed as a timestamp.

Here is the RESTful API call used in my application:

http://coenraets.org/offline-sync/api/employees?modifiedSince=2012-03-01 10:20:56

The format of the data returned by the server is up to you and is part of the contract between the client and the server. In this application, the server returns the changes as an array of JSON objects. The server-side technology (RoR, PHP, Java, .NET, …) and database system (SQL, NoSQL, …) you use to generate the list of changes is also totally up to you. I provide a simple PHP implementation as part of the source code. That implementation manages a session-based data set that provides an isolated and transient playground. In a real-life application, you’d obviously get the data from some sort of database.

Client API

At the client side, our synchronization API consists of three methods.

getLastSync()

A method that returns a timestamp to be used as the query parameter for the next synchronization request. A common practice is to persist a timestamp after each synchronization request. But things can go wrong and the timestamp itself can get out-of-sync. I prefer to “recalculate” the lastSync timestamp before each synchronization request.

getLastSync: function(callback) {
    this.db.transaction(
        function(tx) {
            var sql = "SELECT MAX(lastModified) as lastSync FROM employee";
            tx.executeSql(sql, this.txErrorHandler,
                function(tx, results) {
                    var lastSync = results.rows.item(0).lastSync;
                    callback(lastSync);
                }
            );
        }
    );
}

getChanges()

This is a wrapper around an Ajax call to the server-side API that returns the items that have changed (created, updated, or deleted) since a specific moment in time defined in the modifiedSince parameter.

getChanges: function(syncURL, modifiedSince, callback) {

    $.ajax({
        url: syncURL,
        data: {modifiedSince: modifiedSince},
        dataType:"json",
        success:function (changes) {
            callback(changes);
        },
        error: function(model, response) {
            alert(response.responseText);
        }
    });

}

applyChanges()

A method that persists the changes in your local data store. Notice that SQLite supports a convenient “INSERT OR REPLACE” statement so that you don’t have to determine if you are dealing with a new or existing employee before persisting it.

applyChanges: function(employees, callback) {
    this.db.transaction(
        function(tx) {
            var l = employees.length;
            var sql =
                "INSERT OR REPLACE INTO employee (id, firstName, lastName, title, officePhone, deleted, lastModified) " +
                "VALUES (?, ?, ?, ?, ?, ?, ?)";
            var e;
            for (var i = 0; i < l; i++) {
                e = employees[i];
                var params = [e.id, e.firstName, e.lastName, e.title, e.officePhone, e.deleted, e.lastModified];
                tx.executeSql(sql, params);
            }
        },
        this.txErrorHandler,
        function(tx) {
            callback();
        }
    );
}

Synchronization Logic

With these server and client APIs in place, you can choreograph a data synchronization process as follows:

sync: function(syncURL, callback) {

    var self = this;
    this.getLastSync(function(lastSync){
        self.getChanges(syncURL, lastSync,
            function (changes) {
                self.applyChanges(changes, callback);
            }
        );
    });

}

Final Notes

• This solution currently supports unidirectional (server to client) data synchronization. It could easily be expanded to support bidirectional synchronization.
• This solution currently implements “logical deletes”: items are not physically deleted from the table, but the value of their “deleted” column is set to true.
• As mentioned above, you could replace the Web SQL implementation with another data access strategy. For example, take a look at Brian Leroux’ Lawnchair for another local persistence solution.

Source Code

The source code is available in this GitHub repository.

In this post, we explore an offline version of the same application: this new version gets its data from your device’s local database using the PhoneGap SQL database API.

By default, Backbone.js Models access their data using RESTful services defined by the Models “url” and “urlRoot” attributes. But Backbone.js also makes it easy and elegant to change your Models data access mechanism: All you have to do is override the Backbone.sync method. From the Backbone.js documentation:

Backbone.sync is the function that Backbone calls every time it attempts to read or save a model to the server. By default, it uses (jQuery/Zepto).ajax to make a RESTful JSON request. You can override it in order to use a different persistence strategy, such as WebSockets, XML transport, or Local Storage.

The documentation includes a useful example that shows how to replace the default Backbone.sync implementation with localStorage-based persistence where models are saved into JSON objects.

In our application, we will replace the default Backbone.sync implementation with SQL-based persistence using the device’s local database.

First, we create a data access object that encapsulates the logic to read (find), create, update, and delete wines. This simple application is read-only and only needs to retrieve collections. So, I only implemented the findAll() method and stubbed the other methods (find, create, update, destroy). WineDAO also has a “populate” function to populate the wine table with sample data.

window.WineDAO = function (db) {
    this.db = db;
};

_.extend(window.WineDAO.prototype, {

    findAll:function (callback) {
        this.db.transaction(
            function (tx) {
                var sql = "SELECT * FROM wine ORDER BY name";
                tx.executeSql(sql, [], function (tx, results) {
                    var len = results.rows.length;
                    var wines = [];
                    for (var i = 0; i < len; i++) {
                        wines[i] = results.rows.item(i);
                    }
                    callback(wines);
                });
            },
            function (tx, error) {
                alert("Transaction Error: " + error);
            }
        );
    },

    create:function (model, callback) {
//        TODO: Implement
    },

    update:function (model, callback) {
//        TODO: Implement
    },

    destroy:function (model, callback) {
//        TODO: Implement
    },

    find:function (model, callback) {
//        TODO: Implement
    },

//  Populate Wine table with sample data
    populate:function (callback) {
        this.db.transaction(
            function (tx) {
                console.log('Dropping WINE table');
                tx.executeSql('DROP TABLE IF EXISTS wine');
                var sql =
                    "CREATE TABLE IF NOT EXISTS wine ( " +
                        "id INTEGER PRIMARY KEY AUTOINCREMENT, " +
                        "name VARCHAR(50), " +
                        "year VARCHAR(50), " +
                        "grapes VARCHAR(50), " +
                        "country VARCHAR(50), " +
                        "region VARCHAR(50), " +
                        "description TEXT, " +
                        "picture VARCHAR(200))";
                console.log('Creating WINE table');
                tx.executeSql(sql);
                console.log('Inserting wines');
                tx.executeSql("INSERT INTO wine VALUES (1,'CHATEAU DE SAINT COSME','2009','Grenache / Syrah','France','Southern Rhone / Gigondas','The aromas of fruit and spice give one a hint of the light drinkability of this lovely wine, which makes an excellent complement to fish dishes.','saint_cosme.jpg')");
                tx.executeSql("INSERT INTO wine VALUES (2,'LAN RIOJA CRIANZA','2006','Tempranillo','Spain','Rioja','A resurgence of interest in boutique vineyards has opened the door for this excellent foray into the dessert wine market. Light and bouncy, with a hint of black truffle, this wine will not fail to tickle the taste buds.','lan_rioja.jpg')");
                tx.executeSql("INSERT INTO wine VALUES (3,'MARGERUM SYBARITE','2010','Sauvignon Blanc','USA','California Central Cosat','The cache of a fine Cabernet in ones wine cellar can now be replaced with a childishly playful wine bubbling over with tempting tastes of black cherry and licorice. This is a taste sure to transport you back in time.','margerum.jpg')");
                tx.executeSql("INSERT INTO wine VALUES (4,'OWEN ROE \"EX UMBRIS\"','2009','Syrah','USA','Washington','A one-two punch of black pepper and jalapeno will send your senses reeling, as the orange essence snaps you back to reality. Do not miss this award-winning taste sensation.','ex_umbris.jpg')");
                tx.executeSql("INSERT INTO wine VALUES (5,'REX HILL','2009','Pinot Noir','USA','Oregon','One cannot doubt that this will be the wine served at the Hollywood award shows, because it has undeniable star power. Be the first to catch the debut that everyone will be talking about tomorrow.','rex_hill.jpg')");
                tx.executeSql("INSERT INTO wine VALUES (6,'VITICCIO CLASSICO RISERVA','2007','Sangiovese Merlot','Italy','Tuscany','Though soft and rounded in texture, the body of this wine is full and rich and oh-so-appealing. This delivery is even more impressive when one takes note of the tender tannins that leave the taste buds wholly satisfied.','viticcio.jpg')");
                tx.executeSql("INSERT INTO wine VALUES (7,'CHATEAU LE DOYENNE','2005','Merlot','France','Bordeaux','Though dense and chewy, this wine does not overpower with its finely balanced depth and structure. It is a truly luxurious experience for the senses.','le_doyenne.jpg')");
                tx.executeSql("INSERT INTO wine VALUES (8,'DOMAINE DU BOUSCAT','2009','Merlot','France','Bordeaux','The light golden color of this wine belies the bright flavor it holds. A true summer wine, it begs for a picnic lunch in a sun-soaked vineyard.','bouscat.jpg')");
                tx.executeSql("INSERT INTO wine VALUES (9,'BLOCK NINE','2009','Pinot Noir','USA','California','With hints of ginger and spice, this wine makes an excellent complement to light appetizer and dessert fare for a holiday gathering.','block_nine.jpg')");
                tx.executeSql("INSERT INTO wine VALUES (10,'DOMAINE SERENE','2007','Pinot Noir','USA','Oregon','Though subtle in its complexities, this wine is sure to please a wide range of enthusiasts. Notes of pomegranate will delight as the nutty finish completes the picture of a fine sipping experience.','domaine_serene.jpg')");
                tx.executeSql("INSERT INTO wine VALUES (11,'BODEGA LURTON','2011','Pinot Gris','Argentina','Mendoza','Solid notes of black currant blended with a light citrus make this wine an easy pour for varied palates.','bodega_lurton.jpg')");
                tx.executeSql("INSERT INTO wine VALUES (12,'LES MORIZOTTES','2009','Chardonnay','France','Burgundy','Breaking the mold of the classics, this offering will surprise and undoubtedly get tongues wagging with the hints of coffee and tobacco in perfect alignment with more traditional notes. Breaking the mold of the classics, this offering will surprise and undoubtedly get tongues wagging with the hints of coffee and tobacco in perfect alignment with more traditional notes. Sure to please the late-night crowd with the slight jolt of adrenaline it brings.','morizottes.jpg')");
            },
            function (tx, error) {
                alert('Transaction error ' + error);
            },
            function (tx) {
                callback();
            }
        );
    }
});

I then added a “dao” attribute to the Models to specify which data object should be used to access their underlying data.

window.Wine = Backbone.Model.extend({
	urlRoot: "http://coenraets.org/backbone-cellar/part1/api/wines",
    dao: WineDAO
});

window.WineCollection = Backbone.Collection.extend({
	model: Wine,
	url: "http://coenraets.org/backbone-cellar/part1/api/wines",
    dao: WineDAO
});

NOTE: The application doesn’t need the url and urlRoot attributes anymore, but you can imagine a more sophisticated version of the app that would work with the RESTful services while online and fall back to the local database while offline.

With that infrastructure in place, we can now override Backbone.sync as follows:

Backbone.sync = function (method, model, options) {

    var dao = new model.dao(window.db);

    switch (method) {
        case "read":
            if (model.id)
                dao.find(model, function (data) {
                    options.success(data);
                });
            else
                dao.findAll(function (data) {
                    options.success(data);
                });
            break;
        case "create":
            dao.create(model, function (data) {
                options.success(data);
            });
            break;
        case "update":
            dao.update(model, function (data) {
                options.success(data);
            });
            break;
        case "delete":
            dao.destroy(model, function (data) {
                options.success(data);
            });
            break;
    }

};

And finally, we need to open the database (and populate it with sample data) at startup:

window.startApp = function () {
    var self = this;
    window.db = window.openDatabase("WineCellar", "1.0", "WineCellar Demo DB", 200000);
    var wineDAO = new WineDAO(self.db);
    wineDAO.populate(function () {
        this.templateLoader.load(['wine-list', 'wine-details', 'wine-list-item'], function () {
            self.app = new AppRouter();
            Backbone.history.start();
        });
    })
}

Download

I added this version of the application to the backbone-cellar GitHub repository here.

NOTE: You will have to create a PhoneGap project (see documentation here) or use the hosted build service to package the code as a native app for different mobile platforms.

PhoneGap — if you are not familiar with it — is an open source platform that allows you develop cross-platform Mobile applications using HTML and JavaScript. Specifically, it allows you to:

1. Package an HTML application as a native app on all the key mobile platforms (iOS, Android, BlackBerry, Windows Phone, WebOS, Symbian, Bada).
2. Access your device capabilities (Camera, GPS, database, accelerometer, etc) using a cross-platform JavaScript API.

Backbone.js is a great framework to give structure to your web application regardless of where it is running: in a traditional Web Browser, or as an app packaged with PhoneGap.

So, here is the app…

The UI is intentionally plain to keep the focus on the architectural framework. This is a simple ‘consumer’ version of the application: It allows you to look for wines in your Wine Cellar. The tutorial application mentioned above is an ‘admin’ version: You can create, update, delete wines in your Wine Cellar. Most of the code is shared between the Mobile ‘consumer’ version and the browser-based ‘admin’ version.

In this version, the application gets the data from RESTful services hosted on my server. In my next post, I will provide another version of the application that gets the data using a local database on your device.

Download

I added the source code for the mobile application to the backbone-cellar GitHub repository. You can download the zip file here. For your convenience, I created an iOS directory with the Xcode project and an Android directory with the Eclipse project. The core application is in the www directory (iOS and android) and it is the same code for both iOS and Android.

If you want to run the application on your Android device without installing the project, you can also download the apk file available in the bin directory.

A number of people have asked for a similar example using a “classic” (non-Ajax) implementation where pages (markup + data) are entirely built at the server-side before being delivered to the client.

So, here is simpler version of the same application built “sans Ajax”. I used PHP in this version, but you can of course use your favorite server-side technology (Java, .NET, CF, RoR, etc).

Run the application

Click here to run the application.

Download the source code

Click here to download the source code. Edit config.php to make sure it matches your database configuration.

Running the Application with PhoneGap

With this implementation, the application files can’t be installed locally on the device since pages are created dynamically on the server side. So, in the PhoneGap application, instead of loading a local HTML file, you point to a file hosted on your web server. Here is the code for my main Android activity. Greg has a great post on this topic (I haven’t tried it on iOS myself yet).

package org.coenraets.directory;

import com.phonegap.DroidGap;

import android.os.Bundle;

public class EmployeeDirectoryJQMPHPActivity extends DroidGap {
    /** Called when the activity is first created. */
    @Override
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        super.setBooleanProperty("loadInWebView", true);
        super.loadUrl(
            "http://coenraets.org/apps/directory/jqmphp/index.php");
    }
}

Summary

To recap the difference between the two versions: In the original (Ajax) version, the server side code exposes a set of services consumed by an HTML/JS client. In this new (non-Ajax) version, the server-side code returns fully assembled HTML pages (markup + data).

The original (Ajax) version has many benefits:

1. Your UI code doesn’t have a dependency on a specific server-side technology.
2. Your data access logic doesn’t have a dependency on a specific UI technology.
3. You can manipulate the data on the client side (i.e. sort using different criteria) without requiring a server roundtrip.
4. That decoupled architecture also works offline when working with a local database.

When none of the items above is a requirement of your application, the “non-Ajax” approach may work too and may even have some benefits. In particular, it makes the jQuery Mobile page navigation model easier to handle.

Flex is a powerful application framework for building first-class mobile applications for iOS, Android, and the BlackBerry PlayBook using a single programming model, a single tool, and a single code base.

If you are a Java developer, the Flex programming model is also easy to master because it is syntactically very close to Java. The Flex IDE (Flash Builder) is a plugin on top of Eclipse, which means that you can write, debug, and profile your client and server code in the same development environment.

You can also easily integrate Flex applications with a Java back end using the Remoting and Messaging services provided by BlazeDS (open source) or LCDS (commercial license). For Spring developers, the integration is even easier and more powerful using the Spring/BlazeDS integration project, which makes the Flex and Spring combination the best way to build cross-platform iOS, Android, and PlayBook applications with a Java back end.

I put together a new “Flex / Spring Mobile Test Drive” to help developers get started building these applications. The Test Drive consists of a web application with BlazeDS and the “Spring/BlazeDS integration” preconfigured and ready to use. It also includes two sample mobile applications running “out-of-the-box”: An Employee Directory and a Trader Desktop. The Employee directory demonstrates how to use Remoting to access Spring services. The Mobile Trader focuses on the Messaging integration: It shows a Spring component pushing real-time market data updates to a Flex applications.

The project is hosted on GitHub: https://github.com/ccoenraets/flex-spring-mobile-testdrive

Installation

1. Deploy flex-spring-mobile.war to your app server.
2. Import the projects into Flash Builder: (If you don’t have Flash Builder, you can download it here)
   • File > Import > General > Existing Projects into Workspace
   • Select ccoenraets-flex-spring-mobile-testdrive as the Root directory
   • Select all the projects (EmployeeDirectoryJ, flex-spring-mobile, and MobileTraderJ)
   • Click Finish
3. Running the EmployeeDirectory
   • Open config.xml in the src folder and modify the endpoint to match the hostname and port number of your app server
   • Right-click EmployeeDirectoryJ and select Run As > Mobile Application
   • Select a target platform (iOS, Android, or BlackBerry Tablet OS), select On desktop as the launch method and select a device to simulate
   • Click Run
4. Running the MobileTrader Application
   • Right-click MobileTraderJ and select Run As > Mobile Application
   • Select a target platform (iOS, Android, or BlackBerry Tablet OS), select On desktop as the launch method and select a device to simulate
   • Click Run
   • The Settings view is automatically activated the first time you run the application. Enter the MessageBroker base URL, for example: http://localhost:8080/flex-spring-mobile/messagebroker (modify the endpoint to match the hostname and port number of your app server), select a Channel type, click Save Settings, and click Start Server Feed.
   • Access the Watch tab: The list should be automatically updated with the (simulated) real time updates pushed from the Spring web app.

This version was built with the shipping version of Flex and Flash Builder 4.5.1 which has built-in support for iOS, Android and the BlackBerry PlayBook.

The most notable change in this version is that I enabled the real time collaboration feature (with your financial advisor). This includes video conference, user interface synchronization, etc. You will need a LiveCycle Collaboration Service room URL to enable this feature. You can sign up for a developer version here: https://afcs.acrobat.com. You can still use the application without enabling the real time collaboration feature.

Usual disclaimer about the source code: This is a sample application, I intentionally cut some corners, etc.

If you haven’t seen the application before, watch it here:

NOTE: The shipping version of Flash Builder 4.5 provides full support for Flex projects on Android. Support for Flex projects on iOS and the PlayBook will be available in a June update. More information here.

Usual disclaimer about the source code: This is a sample application, I intentionally cut some corners, etc.

For more data-visualization applications built with Flex, check out the Mobile Trader and the Sales Pipeline applications.

Usual disclaimer: I’m not a designer, so this is mostly developer artwork. You can of course polish, customize and style the out-of-the-box-experience.

Over the past couple of weeks, I’ve visited many enterprise customers to spread the exciting news and discuss their mobile strategy. I found it interesting that most of them were focusing primarily on tablets (instead of phones), and that the application they were focusing on was almost always a dashboard or at least involved a lot of charting components. It is true that tablets such as the iPad, the Xoom, and the BlackBerry PlayBook are amazing devices for data visualization.

Multi-touch is revolutionizing the way we interact with applications. The idea of user interfaces behaving like real life objects has been kicked around for a long time, and touch screens remove an important barrier. In the area of data visualization, multi-touch can have a particularly transformative effect: there are definitely a lot of opportunities for more “natural” data manipulation and exploration.

So, as an exercise, I built an interactive sales dashboard using Flex to explore the possibilities.

Check out the video (running on an iPad). Of course, the same application can run on Android, on the BlackBerry PlayBook, and in the browser or as a desktop application on traditional computers.

This is just a small example of thinking about data visualization differently. Charts don’t have to be read-only: If the data isn’t right, change it right there (“in place editing”).

I’m looking forward to seeing what people will come up with in this exciting field.

Disclaimer: I’m not a designer. This is still mostly developer artwork. The goal of this demo is to experiment with new ways to visualize and modify data, and not to recommend this specific implementation.