A year ago, I blogged Employee Directory, a sample application that demonstrates how to build modern web apps with Backbone.js and Twitter Bootstrap. With 1200+ stars and 300+ forks on GitHub, it has been my most popular sample application to date.

Because of the continued interest in the application as a starting point and a reference for Backbone.js and Twitter Bootstrap, I decided to give it a well deserved update.

New in this version:

• Latest version of Backbone.js (1.0)
• Latest version of Twitter Bootstrap (2.3.1)
• Layout is now responsive
• Data persistence layer is now abstracted (see below)
• Additional data persistence options: In-memory datastore, Node.js/MongoDB, Parse.com (In addition to PHP and Java)
• New GitHub repository organization (see below)
• Bug fixes and cleaner code

Running the Application

You can test the hosted version of the application here, or you can download the code (see GitHub repository information below) and test the application locally.

Data Persistence Abstraction

Among the great feedback I received, a number of you mentioned you wanted a self-contained version of the app with no dependency on a specific back end to be able to “download and run” without having to set up a server and a database. So I rearchitected the persistence layer with simple and pluggable data adapters. By default the application now uses an in-memory data store, but other adapters are available. To change the data persistence strategy, just comment out model-in-memory.js in index.html and uncomment one of the other data adapters using the table below as a reference.

I initially published the application with two implementations of a RESTful back end: A Java version using Jersey, and a PHP version using Slim. A year later, I’m adding the long overdue Node.js/MongoDB back end.

The Node.js, Java, and PHP RESTful back ends work with both JSON and JSONP. If the request includes a query parameter named “callback”, a JSONP response is returned, otherwise, a regular JSON response is returned.

New GitHub Repositories

The original repository (backbone-directory) grew somewhat chaotically as I kept adding different versions and different data persistence options. So I decided to start fresh with new repositories.

The client code for the application is available in the new directory-backbone-bootstrap repository. In the future, this new repository naming scheme will allow me to add different versions of the app (for example, directory-backbone-foundation or directory-angular-bootstrap) while keeping each repository clean and focused.

If you want to go beyond the in-memory datastore, you can download the REST services in the following repositories:

directory-rest-nodejs (Node.js/MongoDB implementation)
directory-rest-php (PHP implementation)
directory-rest-java (Java implementation coming soon)

In my previous post, I shared my recent experience building a RESTful API with Node.js, MongoDB, and Express.

In this post, I’m sharing the client application that uses that RESTful API. The Node Cellar application allows you to manage (retrieve, create, update, delete) the wines in a wine cellar database.

The client application is built with Backbone.js and Twitter Bootstrap.

Run the Application

You can run the application here. For obvious reasons, the create, update, delete features have been disabled in this hosted version.

NOTE: Node.js is running on port 3000 on my EC2 Instance. My friend James Ward convinced me to host the application on their service over at Heroku. It’s now running on port 80 at http://nodecellar.coenraets.org. Thanks James!

Server-Side

The details of the Node.js, MongoDB, and Express implementation are documented in my previous post.

Client-Side

In this application, Node.js is used to provide the RESTful services that the client application needs to manipulate the data. Node.js is not used to generate HTML/Views at the server-side. Instead, the Views are created dynamically at the client-side using Backbone.js and Underscore.js templates. They are injected into- and removed from the DOM as needed as you navigate through the application. Node Cellar is a “single page application”.

This is a Node.js and MongoDB powered version of an application I initially posted here with PHP and Java backends. The original post provides some additional Backbone.js context. This Node.js version also provides an improved user experience with the latest version of Twitter Bootstrap (2.1.1), and a responsive layout. It also uses Adobe Edge Web Fonts.

Source Code

The source code is available in this repository on GitHub.

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.

To demonstrate these features, I decided to revisit my wine cellar application, which was in need of a serious UI makeover.

You can run the application here.

This online version uses an in-memory datastore: all your changes will be lost the next time you start the application or hit your browser’s refresh button. The image upload feature is also disabled, but you can still drag an image from your file system and drop it in the Wine Form, which is pretty cool (see the note about browser support below). The source code available on GitHub includes a persistent back-end (in addition to the in-memory datastore), and a fully functional implementation of the file upload feature.

Code Highlights

Template Loader

This application features a template loader that now uses jQuery “deferreds” to load the HTML templates more efficiently.

Drag-and-Drop File Upload and HTML 5 File API

To upload an image file for a Wine, drag a file from your file system and drop it in the image box inside the Wine Form: The image is automatically displayed inside the img tag. This is done using the HTML 5 File API and doesn’t require a server roundtrip.

NOTE: This feature only works in Chrome at this time. I will implement an alternative implementation in a future version of the application to provide a consistent behavior across browsers.

The image is uploaded to the server using Ajax (XHR) when you save the form: no page refresh or iframe hack.

Paging

Twitter Bootstrap provides easy markup and styles to create paginated lists. In this application, the Bootstrap markup and styles are “componentized” or “widgetized” into a Backbone View (Paginator), which adds the appropriate pagination behavior.

NOTE: In the current implementation of this application, the entire data set is always retrieved from the server and paging is provided for a cosmetic/layout reason. You could easily replace this implementation with a true paging strategy where pages are lazy-loaded from the server as needed.

Forms

Backbone Cellar also uses Twitter Bootstrap’s forms, which greatly help with form layouts (see WineView).

Validation

Twitter Bootstrap also provides simple markup and styles to highlight validation errors in forms. In Backbone Cellar, Bootstrap’s validation markup and styles are wired with validation rules defined in the Backbone model. Note that at this time, the application doesn’t use the Backbone model’s default validate() method, but custom validateItem() and validateAll() methods instead.

The application also uses other Twitter Bootstrap features including thumbnails, dropdowns, alerts, etc.

Source Code

The source code is available in the bootstrap folder of the backbone-cellar repository on GitHub.

Disclaimer

This is a sample application, not a production application. Some trade-offs were made to keep the code generic, simple and readable. In a real-life application, you should consider implementing a namespacing scheme to keep the global namespace clean, and other optimization techniques such as view and/or data caching.

Twitter Bootstrap is a UI toolkit that provides simple and flexible HTML, CSS, and Javascript to implement popular user interface components and interactions.

In other words, Backbone.js and Twitter Bootstrap focus on different areas of your application: core architecture and user interface respectively. Because of their well-defined and non-overlapping scope, Backbone.js and Twitter Bootstrap work well together. In general, I find a lightweight architectural framework and a UI toolkit to be a powerful combination, and an interesting alternative to full-stack frameworks: it gives you the flexibility to choose the library you like (if any) in the respective areas of your application.

The Sample Application

To give this combination a try, I put together a new sample application that uses Backbone.js to organize the code, and Twitter Bootstrap to organize the UI. The application is an Employee Directory that allows you to look for employees by name, view the details of an employee, and navigate up and down the Org Chart by clicking the employee’s manager or any of his/her direct reports.

You can run the application here.

Backbone Directory is a single page application: index.html is essentially empty. Views are injected into and removed from the DOM as needed. Even though it is a single page application, the Backbone.js Router makes it easy to keep the different states of the app “bookmarkable” and “deep-linkable”.

Twitter Bootstrap highlights

“Backbone Directory” uses a number of the Twitter Bootstrap styles, components, and interactions: the 12-column grid with nested columns, a “Navbar”, a “Search Form” with dropdown, the dropdown plugin, the Glyphicons icons, Info and Warning alerts, a “Well”, etc.

Backbone.js highlights

If you are new to Backbone.js, you may want to start with the tutorial (part 1, part 2, part 3, and postface) I blogged recently. “Backbone Directory” includes some interesting elements not covered in the tutorial:

• One-to-Many association. A one-to-many (Manager-to-Employees) association is defined in the Employee model (model/employeemodel.js) as a collection of employees (the direct reports). That collection is lazily fetched in the render() function of EmployeeFullView (view/employeedetails.js).
• Composite View. EmployeeFullView (views/employeedetails.js) is an example of a composite view. Its render() function instantiates two subviews: EmployeeView and EmployeeListView (to display the employee’s direct reports).

Source Code

The source code is available in this repository on GitHub.

Your feedback and comments are appreciated.