Christophe Coenraets

Sample Mobile App with Backbone.js and PhoneGap

Christophe — Mon, 06 Feb 2012 17:27:53 +0000

I recently blogged a tutorial (part 1, part 2, part 3, and postface) that takes you through the process of building a CRUD application using HTML and the Backbone.js framework. The application used in this tutorial is a Wine Cellar management app, and I thought it would be fun to create a Mobile version using PhoneGap.

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:

Package an HTML application as a native app on all the key mobile platforms (iOS, Android, BlackBerry, Windows Phone, WebOS, Symbian, Bada).
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 www directory 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.

Retweet this Share on Facebook Follow @ccoenraets !function(d,s,id){var js,fjs=d.getElementsByTagName(s)[0];if(!d.getElementById(id)){js=d.createElement(s);js.id=id;js.src="//platform.twitter.com/widgets.js";fjs.parentNode.insertBefore(js,fjs);}}(document,"script","twitter-wjs");

Sample Application with Angular.js

Christophe — Thu, 02 Feb 2012 20:33:32 +0000

After I blogged a three-part Backbone.js tutorial (part 1, part 2, part 3), a number of people asked me to try Angular.js. So I decided to take it for a test drive. I thought it would be interesting to rebuild with Angular.js the Wine Cellar application I had built with Backbone.

If you are new to my Wine Cellar application, it is a simple CRUD app that allows you to manage (create, update, delete) wines in a Wine Cellar. The data is stored in a MySQL database that the client application accesses through a simple RESTful API. This seemed to be a good fit since CRUD applications are often positioned as the sweet spot for Angular.js.

You can run the application here. The UI is intentionally plain to keep the focus on the key learning points. For obvious reasons, this online version is “read-only”. You can download the fully enabled version here.

Application Walkthrough

The best way to get started with Angular.js is to go through the excellent tutorial that is part of the documentation, so I’ll only provide a high level overview of my code here.

Like the Backbone.js implementation, the Angular.js version is a deep-linkable single page application. index.html is defined as follows:




Angular Cellar






    Angular Cellar

The application is driven by a set of Controllers that I defined in controllers.js as follows:

function RouteCtrl($route) {

    var self = this;

    $route.when('/wines', {template:'tpl/welcome.html'});

    $route.when('/wines/:wineId', {template:'tpl/wine-details.html', controller:WineDetailCtrl});

    $route.otherwise({redirectTo:'/wines'});

    $route.onChange(function () {
        self.params = $route.current.params;
    });

    $route.parent(this);

    this.addWine = function () {
        window.location = "#/wines/add";
    };

}

function WineListCtrl(Wine) {

    this.wines = Wine.query();

}

function WineDetailCtrl(Wine) {

    this.wine = Wine.get({wineId:this.params.wineId});

    this.saveWine = function () {
        if (this.wine.id > 0)
            this.wine.$update({wineId:this.wine.id});
        else
            this.wine.$save();
        window.location = "#/wines";
    }

    this.deleteWine = function () {
        this.wine.$delete({wineId:this.wine.id}, function() {
            alert('Wine ' + wine.name + ' deleted')
            window.location = "#/wines";
        });
    }

}

RouteCtrl defines the routes of the application. Each route is defined by a template that is rendered in inside index.html. There can only be one in a document (more on that later). For example, here is the wine-list.html template:


    
        {{ wine.name }}

The WineListCtrl and WineDetailCtrl controllers provide access to the data using a service defined in services.js as follows:

angular.service('Wine', function ($resource) {
    return $resource('api/wines/:wineId', {}, {
        update: {method:'PUT'}
    });
});

Services provide a great way to abstract your data access logic, and to easily change it without impacting the rest of the application. For example, you could easily change the Wine service to use a Mock service instead of a RESTful service.

Impressions

I was able to build this application in a very limited amount of time with no prior knowledge of the framework. The data-binding implementation is nice, and, in general, the amount of boilerplate code you have to write is very limited. Frameworks are often a matter of style and personal preferences. Angular.js takes a more declarative approach than other frameworks. Based on this initial experience, I would also describe it as more prescriptive: I didn’t have to spend a lot of time wondering what was the best way to do things as Angular.js tends to have clear utilization patterns. I haven’t spend enough time with the framework to determine if that comes at the cost of less control, and I’d love to hear what other people are thinking.

The only problem I ran into while building the application is the “one route / one view” coupling I alluded to above. As suggested in this thread, you can use to bind partials in the page. The same thread also indicates that multiple per route definition will be supported in the future. I was able to handle the simple UI requirements of this app using one and one . For more complex applications, I’d love the routing infrastructure to allow me to easily and arbitrarily add, remove, change, or animate different elements of the DOM when the route changes in order to support deeper UI transformations. I’m sure there are ways to do this. If Angular.js folks are reading this post, I’d love to hear what they think and what’s coming.

Download

The application is available on GitHub here.

You will need the RESTful services to run this application. A PHP version (using the Slim framework) is available as part of the download. If you want to test the application with a Java back-end, you can download the Backbone version here, and reuse its JAX-RS back-end.

Backbone.js Lessons Learned and Improved Sample App

Christophe — Mon, 30 Jan 2012 16:06:42 +0000

A few weeks ago, I posted a three-part Backbone.js tutorial (part 1, part 2, part 3). Since then, I spent more time building a real-life application with Backbone. I ran into a number of interesting problems, spent time thinking about solutions, and decided to write them down in this post. These are not definitive answers, just my current thoughts… and as always, I value your input.

Based on this new experience, I revisited the Wine Cellar application used in my tutorial. You can find the improved version here (PHP back-end) or here (Java back-end).

Externalizing Templates

In the initial implementation of my wine cellar app, I “inlined” my templates in a succession of

This approach works fine for a simple application with a limited number of templates. In a larger project, it makes templates hard to maintain. It also makes it difficult for multiple developers to work on different templates at the same time. Removing the script body and adding a src attribute to point to an external file didn’t seem to work to load HTML templates.

In this StackOverflow thread, Brian Genisio suggests loading external templates as string variables in a .js file. Using this approach, a template definition looks like this:

app.templates.view = " \
    something code \
";

That’s certainly a valid approach, but depending on your circumstances, it may still not be the ideal solution: long string concatenation is painful (especially for larger templates). In addition, if you define HTML in string variables, you will probably not be able to benefit from the HTML capabilities of your editor.

Other people load external templates using Require.js and the text plugin, which is definitely an approach worth considering for larger projects. In my case, I didn’t feel that the size of my project mandated it.

In the end, I decided to write my own simple template loader. It is implemented as follows:

tpl = {

    // Hash of preloaded templates for the app
    templates: {},

    // Recursively pre-load all the templates for the app.
    // This implementation should be changed in a production environment:
    // All the template files should be concatenated in a single file.
    loadTemplates: function(names, callback) {

        var that = this;

        var loadTemplate = function(index) {
            var name = names[index];
            console.log('Loading template: ' + name);
            $.get('tpl/' + name + '.html', function(data) {
                that.templates[name] = data;
                index++;
                if (index < names.length) {
                    loadTemplate(index);
                } else {
                    callback();
                }
            });
        }

        loadTemplate(0);
    },

    // Get template by name from hash of preloaded templates
    get: function(name) {
        return this.templates[name];
    }

};

I use it to preload all my templates before bootstrapping Backbone:

tpl.loadTemplates(['header', 'wine-details', 'wine-list-item'], function() {
    app = new AppRouter();
    Backbone.history.start();
});

Loading templates separately is great during development: you can modify and test individual templates without requiring a “build” or the concatenation of multiple template files. In production however, loading dozens of templates as separate HTTP requests can be a serious bottleneck. So when you are ready to move to production, it’s a good idea to somehow combine all your templates in a single file so that you can load them all with a single HTTP request.

 Decouple Views from other DOM elements

In the initial version of my application, I didn’t pay much attention to the way I chose the “el” or “tagName” of my Views. I often assigned the View’s “el” to an existing element of the document.

“Before” code:

window.WineView = Backbone.View.extend({

    el: $('#content'),

    render: function(eventName) {
		$(this.el).html(this.template(this.model.toJSON()));
		return this;
    }

});

… and here is the Router’s code that instantiated and displayed a WineView:

new WineView().render();

After more careful consideration, I realized that this approach wasn’t very good. The View is not fully encapsulated: it “reaches out” to an attribute (element) of the containing document (‘#mainArea’), creating an undesirable dependency. A better approach is to make sure a View doesn’t know about its hosting document. It should not know about (or assume the presence) of other elements in the document. The knowledge of the View should be limited to the elements in its own template. That will make the view reusable in many different contexts. The corollary of this rule is that a View shouldn’t attach itself to a DOM element in its render() method. The render() method should be limited to populating its own “detached” el attribute. The code that invokes the View’s render() method can then decide what to do with the View’s HTML fragment: attach it, append it, etc. The View is therefore more reusable and more versatile.

“After” code:

window.WineView = Backbone.View.extend({

    tagName: "div", // Not required since 'div' is the default if no el or tagName specified

    render: function(eventName) {
		$(this.el).html(this.template(this.model.toJSON()));
		return this;
    }

});

… and here is the Router’s code that instantiates and displays a WineView defined as above:

$('#content').html( new WineView().render().el );

Cleaning Up: Avoiding Memory Leaks and Ghost Views

Before getting rid of a view, you need to clean up, which mainly consists of removing the bindings that could prevent the View from being properly destroyed. A View that is not properly destroyed becomes a “Ghost View”: you don’t see it, you think it’s gone, but it still manifests itself in some unpleasant ways: its events are still firing and it still uses memory (memory leaks). Ghost Views often first manifest themselves in the form of events firing multiple times.

In my initial implementation, I provided views with a close() method that took care of cleaning up. There was nothing wrong with that approach except that you had to remember to call the close() method!

Derick Bailey has a great post on this topic and provides a more generalized approach: It consists of adding a generic close() method to the Backbone View prototype. I borrowed Derick’s approach and implemented my generic close() method as follows:

Backbone.View.prototype.close = function () {
    if (this.beforeClose) {
        this.beforeClose();
    }
    this.remove();
    this.unbind();
};

The call to beforeClose() (if it exists in the view) is a hook to add some view-specific cleanup code if required.

In your Router, you then create new Views by invoking a custom showView() method that invokes close() on the currentView before replacing it with the new View.

showView: function(selector, view) {
    if (this.currentView)
        this.currentView.close();
    $(selector).html(view.render().el);
    this.currentView = view;
    return view;
}

Note that this is only part of the solution. For example, if you have composite views (views containing other views), you still have to make sure you close the “child” views when the parent view is closed. A good approach here is for the parent view to keep track of its child views so that it can call their respective close() methods when its own close() method is invoked. The beforeClose() method (explained above) of the parent View is a good place to close the child Views.

Route pre-processing (aka Filters)

Backbone’s Router is great at routing requests to the important/stateful/bookmarkable locations in your application.

When defining the routes in my application, I sometimes find myself in a situation where a pre-condition has to be met before a route can be taken.

For example:

Some routes may require the user to be authenticated.
Some routes may require some data to be loaded.

It’s easy to verify the pre-condition in the method that implements a specific route. That’s what I did in the initial version of my application. But in a larger application, this approach will quickly start cluttering your route methods.

My instinct was to look for a “Filter” feature in the Backbone Router API, but it doesn’t currently exist out-of-the-box, and in this thread, Jeremy makes the case that the same result can be achieved using underscore’s _.wrap() method.

_.wrap() didn’t work for me because my pre-condition involved asynchronous processing and I can only pass control back to the routing method after the successful completion of my async code.

In the end, I implemented a simple/low-tech before() method that is somewhat similar to wrap() but supports async chaining.

var AppRouter = Backbone.Router.extend({

	routes: {
		"wines/:id"	: "wineDetails"
	},

	wineDetails: function(id) {
        this.before(function() {
			var wine = app.wineList.get(id);
		    app.showView( '#content', new WineView({model: wine}) );
        });
  	},

    showView: function(selector, view) {
        if (this.currentView)
            this.currentView.close();
        $(selector).html(view.render().el);
        this.currentView = view;
        return view;
    },

    before: function(callback) {
        if (this.wineList) {
            if (callback) callback();
        } else {
            this.wineList = new WineCollection();
       		this.wineList.fetch({success: function() {
               $('#sidebar').html( new WineListView({model: app.wineList}).render().el );
               if (callback) callback();
            }});
        }
    }

});

This solution is not as “decoupled” as a traditional filter implementation would be, but it allowed me to unclutter my code in a way that was suitable for my requirements. Jake Dempsey
has built a more traditional filter implementation here that you may want to take a look at.

Download

The source code for this application is hosted on GitHub. The application uses RESTful services to access the data.

For a version of this application using a PHP back-end, use this project (use the ‘final’ folder for the version of the application discussed in this article.

For a version of this application using a Java back-end (using JAX-RS), use this project.

Using Backbone.js with a RESTful Java Back-End

Christophe — Tue, 10 Jan 2012 17:39:44 +0000

In a previous post, RESTful services with jQuery and Java using JAX-RS and Jersey, I demonstrated how to build a RESTful API using JAX-RS and Jersey, and how to build a jQuery application that leverages that API. The application used as an example was a Wine Cellar management application.

In follow-up posts, “Backbone.js Wine Cellar Tutorial” (part1, part 2, part 3), I showed how to add structure to the client-side of the Wine Cellar application using Backbone.js. But that three-part tutorial was provided with a PHP back-end.

By popular demand, here is a version of the Backbone.js Wine Cellar application powered by a Java / JAX-RS back-end using Jersey. The server-side of the application provides an example of building a complete RESTful API in Java using the different HTTP methods:

GET to retrieve and search wines
POST to add a wine
PUT to update a wine
DELETE to delete a wine

As already mentioned, the client-side of the application provides an example of adding structure to your JavaScript code using the Backbone.js Model, View and Router components. To learn more about the Backbone.js implementation, refer to the three part tutorial mentioned above: it is entirely back-end agnostic.

The source code for this application is hosted on GitHub here. It consists of the Eclipse Dynamic Web Project with the source code for both the Java back-end and JavaScript/Backbone.js client.

You can run the application (Part 3) here. The create/update/delete features are disabled in this online version.

Setting Up WordPress on Amazon EC2 in 5 minutes

Christophe — Thu, 05 Jan 2012 20:45:48 +0000

Step 1: Create an AWS Account

First things first: you need to create your AWS account. You can sign up here. You’ll have to provide a credit card and a phone number where you will be called as part of the online registration process for verification purposes. Amazon offers a Free Usage Tier, which is great to explore the services and even host real apps without being charged. Check the details here.

Step 2: Create an Instance

What type of EC2 instance should you use? I started my experiments with a Micro instance because its price structure is very attractive. However, after a few minutes to a couple of hours, my blog systematically became unresponsive and I had to restart Apache and/or MySQL. I did some research, and found out that other people were reporting similar problems. It may depend on your blog traffic. My blog typically gets a few thousand page views a day. It also hosts live sample applications running with a PHP or a Java back-end running on Tomcat. It looks like that combination was too much for a Micro instance. I tried a Small instance and the problems went away. Greg Wilson has a great post on the limitations of the Micro instance.

To create a new instance, access the AWS Management Console and click the EC2 tab:

Choose an AMI in the classic instance wizard: I chose the Basic 32-bit Amazon Linux AMI.
Instance details: Select the Instance Type you want to use. I chose Small (m1.small).
Create a new key pair. Enter a name for your key pair (i.e. christophe) and download your key pair (i.e. christophe.pem).
Select the quick start security group.
Launch your instance.

Step 3: SSH into your Instance

Once your instance is running, you can ssh into it. First, you need to identify the address of your instance: Select the instance in the AWS Management Console, and look for the Public DNS in the instance description (bottom part of the screen).

Use that address (and a path to your .pem file) to ssh into your instance:
ssh ec2-user@ec2-50-17-14-16.compute-1.amazonaws.com -i ~/christophe.pem

If you get a message about your .pem file permissions being too open, chmod your .pem file as follows:
chmod 600 ~/christophe.pem

Many of the shell commands below require root access. To avoid having to prefix these commands with sudo, let’s just switch user once and for all:
sudo su

Step 4: Install the Apache Web Server

To install the Apache Web Server, type:
yum install httpd

Start the Apache Web Server:
service httpd start

To test your Web Server, open a browser and access your web site: http://ec2-50-17-14-16.compute-1.amazonaws.com (Use your actual public DNS name). You should see a standard Amazon place holder page.

Step 5: Install PHP

To install PHP, type:
yum install php php-mysql

Restart the Apache Web Server:
service httpd restart

Create a page to test your PHP installation:
cd /var/www/html
vi test.php

Type i to start the insert mode
Type
Type :wq to write the file and quit vi

Open a browser and access test.php to test your PHP installation: http://ec2-50-17-14-16.compute-1.amazonaws.com/test.php (Use your actual public DNS name).

Step 6: Install MySQL

To install MySQL, type:
yum install mysql-server

Start MySQL:
service mysqld start

Create your “blog” database:
mysqladmin -uroot create blog

Secure your database:
mysql_secure_Installation

Answer the wizard questions as follows:

Enter current password for root: Press return for none
Change Root Password: Y
New Password: Enter your new password
Remove anonymous user: Y
Disallow root login remotely: Y
Remove test database and access to it: Y
Reload privilege tables now: Y

Step 7: Install WordPress

To install WordPress, type:
cd /var/www/html
wget http://wordpress.org/latest.tar.gz
tar -xzvf latest.tar.gzcd

This will uncompress WordPress in its own “wordpress” directory. I like having WordPress in a separate directory, but would rather rename it to “blog”:
mv wordpress blog

Create the WordPress wp-config.php file:
cd blog
mv wp-config-sample.php wp-config.php
vi wp-config.php

Type i to start insert mode.
Modify the database connection parameters as follows:
define(‘DB_NAME’, ‘blog’);
define(‘DB_USER’, ‘root’);
define(‘DB_PASSWORD’, ‘YOUR_PASSWORD’);
define(‘DB_HOST’, ‘localhost’);
Type :wq to write the file and quit vi

Open a Browser and access your blog: http://ec2-50-17-14-16.compute-1.amazonaws.com/blog (Use your actual public DNS name). This should trigger the WordPress configuration process.

Step 8: Map IP Address and Domain Name

To use your blog in production, you will have to:

Associate an IP address to your instance
Map your domain name to that IP address

To associate an IP address to your instance:

In the AWS Management Console, click Elastic IPs (left navigation bar)
Click Allocate New Address, and confirm by clicking the “Yes, Allocate” button
Right-click the newly allocated IP address and select “Associate” in the popup menu. Select the instance you just created and click “Yes, Associate”

To map your domain name to your IP address, you will have to use the tools provided by your domain registrar. If you use GoDaddy, specify NS73.DOMAINCONTROL.COM and NS74.DOMAINCONTROL.COM as the name servers for your domain, and use the DNS Manager to modify the A record and point to your IP address. Documentation is available here.

Once everything is configured and mapped correctly, access the General Settings in the WordPress management console and make sure the WordPress Address and Site Address are specified correctly using your domain name as in the screenshot below.

Tutorial: HTML Templates with Mustache.js

Christophe — Tue, 20 Dec 2011 15:53:43 +0000

}

When developing modern HTML applications, you often write a lot of HTML fragments programmatically. You concatenate HTML tags and dynamic data, and insert the resulting UI markup into the DOM. Here is a random code example of this approach:

$.each(messages.reverse(), function(index, message) {
	$('#messageList').append(
		'' +
		message.userName + '' +
		'' +
		'' + message.messageText + '');
	}
});

The proliferation of this kind of code throughout your application comes with some downsides. The tight coupling of UI and data logic doesn’t promote separation of concerns and reuse. It makes your application harder to write and harder to maintain.

HTML templates address this issue by decoupling the UI definition (HTML markup) from the data. There are a number of HTML template solutions out there: jQuery Templates, Underscore.js, and Mustache.js to name a few. Mustache.js is a popular choice because of its powerful syntax and fast rendering.

Mustache is a “logic-less” template syntax. “Logic-less” means that it doesn’t rely on procedural statements (if, else, for, etc.): Mustache templates are entirely defined with tags. Mustache is implemented in different languages: Ruby, JavaScript, Python, PHP, Perl, Objective-C, Java, .NET, Android, C++, Go, Lua, Scala, etc. Mustache.js is the JavaScript implementation.

In this article, we take a quick tour of some of the capabilities of Mustache.js.

To start using Mustache.js, simply add a script tag to your html file pointing to mustache.js which is available here.

You can run all the examples below here.

Sample 1: Basic Template

This is a self-explanatory example. Note that:

Instead of being defined in a variable, the data often comes from a service call (see sample 2)
Instead of being defined in a variable, the template is often read from a file (see sample 3)

	var person = {
		firstName: "Christophe",
		lastName: "Coenraets",
		blogURL: "http://coenraets.org"
	};
	var template = "{{firstName}} {{lastName}}Blog: {{blogURL}}";
	var html = Mustache.to_html(template, person);
	$('#sampleArea').html(html);

Result:

Christophe Coenraets

Blog: http://coenraets.org

Sample 2: Basic Template using Ajax data

Same as sample 1, except that we get the data from an Ajax service call.

$.getJSON('json/data.json', function(data) {
	var template = "{{firstName}} {{lastName}}Blog: {{blogURL}}";
	var html = Mustache.to_html(template, data);
	$('#sampleArea').html(html);
});

Result:

John Smith

Blog: http://johnsmith.com

Sample 3: Externalized Template

Same as sample 2, except that we read the template from the main HTML file.

$.getJSON('json/data2.json', function(data) {
	var template = $('#personTpl').html();
	var html = Mustache.to_html(template, data);
	$('#sampleArea').html(html);
});

The template is defined as follows in index.html:

Result:

Lisa Jones

Blog URL: http://lisajones.com

NOTE: Sample 3 represents the way templates are being used in many dynamic Web applications:

You get data from an Ajax service
You read the template from an external file

In the remaining of this article, we declare the data and the template in variables to keep the examples self-contained. Remember to refer to sample 3 for a traditional setup when using templates in a dynamic Web application.

Sample 4: Enumerable Section

var data = {name: "John Smith", skills: ['JavaScript', 'PHP', 'Java']};
var tpl = "{{name}} skills:{{#skills}}{{.}}
{{/skills}}";
var html = Mustache.to_html(tpl, data);
$('#sampleArea').html(html);

Result:

John Smith skills:

JavaScript
PHP
Java

Sample 5: Enumerable Section with Objects

var data = {
	employees: [
	{	firstName: "Christophe",
		lastName: "Coenraets"},
	{	firstName: "John",
		lastName: "Smith"}
	]};
var template = "Employees:{{#employees}}" +
                            "{{firstName}} {{lastName}}" +
                            "{{/employees}}";
var html = Mustache.to_html(template, data);
$('#sampleArea').html(html);

Result:

Employees:

Christophe Coenraets
John Smith

Sample 6: Nested Objects

You can use the dot notation to access object properties.

var person = {
	firstName: "Christophe",
	lastName: "Coenraets",
	blogURL: "http://coenraets.org",
	manager : {
		firstName: "John",
		lastName: "Smith"
	}
};
var template = "{{firstName}} {{lastName}}
{{blogURL}}" +
               "Manager: {{manager.firstName}} {{manager.lastName}}";
var html = Mustache.to_html(template, person);
$('#sampleArea').html(html);

Result:

Christophe Coenraets

http://coenraets.org

Manager: John Smith

Sample 7: Dereferencing

Same as sample 6, except that we “dereference” the manager object to make it easier to access its properties (without having to use the dot notation).

var person = {
	firstName: "John",
	lastName: "Smith",
	blogURL: "http://johnsmith.com",
	manager : {
		firstName: "Lisa",
		lastName: "Jones"
	}
};
var tpl = "{{firstName}} {{lastName}}
{{blogURL}}" +
          "{{#manager}}Manager: {{firstName}} {{lastName}}{{/manager}}";
var html = Mustache.to_html(tpl, person);
$('#sampleArea').html(html);

Result:

John Smith

http://johnsmith.com

Manager: Lisa Jones

Sample 8: Function

Templates can reference functions like totalPrice in this example.

var product = {
	name: "FooBar",
	price: 100,
	salesTax: 0.05,
	totalPrice: function() {
		return this.price + this.price * this.salesTax;
	}
};
var template = "Product Name: {{name}}Price: {{totalPrice}}";
var html = Mustache.to_html(template, product);
$('#sampleArea').html(html);

Result:

Product Name: FooBar

Price: 105

Sample 9: Condition

Templates can include conditional sections. Conditional sections only render if the condition evaluates to true. A conditional section begins with {{#condition}} and ends with {{/condition}}. “condition” can be a boolean value or a function returning a boolean.

var data = {
	employees: [
	{	firstName: "Christophe",
		lastName: "Coenraets",
		fullTime: true,
		phone: "617-123-4567"
	},
	{	firstName: "John",
		lastName: "Smith",
		fullTime: false,
		phone: "617-987-6543"
	},
	{	firstName: "Lisa",
		lastName: "Jones",
		fullTime: true,
		phone: "617-111-2323"
	},
	]};
var tpl = "Employees:{{#employees}}{{firstName}} {{lastName}}" +
          "{{#fullTime}} {{phone}}{{/fullTime}}
{{/employees}}";
var html = Mustache.to_html(tpl, data);
$('#sampleArea').html(html);

Result:

Employees:

Christophe Coenraets 617-123-4567
John Smith
Lisa Jones 617-111-2323

Sample 10: Partials

var data = {
	firstName: "Christophe",
	lastName: "Coenraets",
	address: "1 Main street",
	city: "Boston",
	state: "MA",
	zip: "02106"
};

var template = "{{firstName}} {{lastName}}{{>address}}";
var partials = {address: "{{address}}{{city}}, {{state}} {{zip}}"};
var html = Mustache.to_html(template, data, partials);
$('#sampleArea').html(html);

Result:

Christophe Coenraets

1 Main street

Boston, MA 02106

Sample 11: Partials in Enumerable Section

var data = { depts: [
	{	name: "Engineering",
		employees: [
			{firstName: "Christophe", lastName: "Coenraets"},
			{firstName: "John", lastName: "Smith"}]
	},
	{	name: "Sales",
		employees: [
			{firstName: "Paula", lastName: "Taylor"},
			{firstName: "Lisa", lastName: "Jones"}]
	}]
};

var tpl = "{{#depts}}{{name}}" +
          "{{#employees}}{{>employee}}{{/employees}}{{/depts}}";
var partials = {employee: "{{firstName}} {{lastName}}"};
var html = Mustache.to_html(tpl, data, partials);
$('#sampleArea').html(html);

Result:

Engineering

Christophe Coenraets
John Smith

Sales

Paula Taylor
Lisa Jones

You can run all the examples here.

Fact Check Michele Bachmann with Politifact and Flex

Christophe — Fri, 16 Dec 2011 18:02:03 +0000

During the GOP presidential debate last night, Michelle Bachmann said this:

After the debate that we had last week, Politifact came out and said that everything I said was true.

Did Politifact really give her a “True” rating across the board for a performance in the previous debate?

The best way to check if you are on the go, is to use Politifact’s mobile application which was built with Flex and runs on the iPhone, the iPad, the BlackBerry PlayBook, the Kindle Fire, the Barnes and Noble Nook, and other Android devices… using the exact same code. 100% code reusability.

100% Code Reusability
I’ll let you check Michelle Bachmann statements in Politifact’s Mobile app, but since I helped build it, I can tell you that the 100% Flex code reusability across devices statement is absolutely “True”!

The Politifact Mobile application is available in the following app stores:

Apple App Store
Android Market
Amazon App Store
BlackBerry App World
Barnes and Noble Nook Store

Mobile Development with Flex 4.6 and Spring

Christophe — Fri, 09 Dec 2011 17:27:13 +0000

My Mobile Development with Flex 4.6 and Spring video (using the Spring BlazeDS Integration project) is available on Adobe TV. You can watch it here.

The Flex Spring Mobile Test Drive is hosted on GitHub and documented here.

Backbone.js Wine Cellar Tutorial — Part 3: Deep Linking and Application States

Christophe — Thu, 08 Dec 2011 21:04:53 +0000

UPDATE: I posted a “Postface” to this series with some lessons learned and an improved version of the app. Make sure you read it here.

In Part 1 of this tutorial, we set up the basic infrastructure for the Wine Cellar application. In Part 2, we added the ability to create, update, and delete (CRUD) wines.

There are a few remaining issues in the application. They are all related to “deep linking”. The application needs to continuously keep its URL in sync with its current state. This allows you to grab the URL from the address bar at any point in time during the course of the application, and re-use or share it to go back to the exact same state.

In this last installment of the tutorial, we add support for deep linking in the Wine Cellar application.

Problem 1: Linking to a specific wine

The problem: Select a specific wine from the list. The URL looks like this: http://www.coenraets.org/backbone-cellar/part2/#wines/[id]. Now do one of these two things:

Grab that URL from the address bar and try to access it from another browser window or tab
Simply click your browser’s Refresh button

You get an empty screen with no data. If you look at a debug console (for example, in Chrome’s Developer Tools), you’ll get this message:

Let’s take a look at what’s going on here:

var AppRouter = Backbone.Router.extend({

	routes: {
		""			: "list",
		"wines/:id"	: "wineDetails"
	},

	list: function() {
    	this.wineList = new WineCollection();
    	this.wineListView = new WineListView({model: this.wineList});
		this.wineList.fetch();
  	},

	wineDetails: function(id) {
		this.wine = this.wineList.get(id);
		if (app.wineView) app.wineView.close();
   		this.wineView = new WineView({model: this.wine});
		this.wineView.render();
  	}

});

The problem is on line 15: we are assuming that a wine collection (this.wineList) already exists, and are trying to “get” a specific item from that list. That works well when we start the application with the default (“”) route. But this.wineList won’t exist if we start the application with the “wines/:id” route. There are different ways to address the issue:

We could modify the wineDetails function to fetch the requested item directly:

	wineDetails: function(id) {
		this.wine = new Wine({id: id});
		this.wineView = new WineView({model: this.wine});
		this.wine.fetch();
  	}

That takes care of loading the wine details in the form, but the wine list remains empty when we start the application with “wines/:id” route. We could add the following line of code to load the list if it doesn’t exist:

if (!this.wineList) this.list();

But now, the wine model that is part of the collection and the wine model fetched separately are two different objects, which means that data binding and View synchronization will not work as expected.

Another approach is to check if the collection exists in the wineDetails function. If it does, we simply “get” the requested item and render it as we did before. If it doesn’t, we store the requested id in a variable, and then invoke the existing list() function to populate the list. We then modify the list function: When we get the list from the server (on success), we check if there was a requested id. If there was, we invoke the wineDetails function to render the corresponding item.

var AppRouter = Backbone.Router.extend({

	routes: {
		""			: "list",
		"wines/:id"	: "wineDetails"
	},

	list: function() {
    	this.wineList = new WineCollection();
		var self = this;
		this.wineList.fetch({
			success: function() {
		    	self.wineListView = new WineListView({model: self.wineList});
				self.wineListView.render();
				if (self.requestedId) self.wineDetails(self.requestedId);
			}
		});
  	},

	wineDetails: function(id) {
		if (this.wineList)
		{
			this.wine = this.wineList.get(id);
			if (this.wineView) this.wineView.close();
		    		this.wineView = new WineView({model: this.wine});
			this.wineView.render();
		} else {
			this.requestedId = id;
			this.list();
		}
  	}
});

Problem 2: Updating the URL after a wine is created

The problem: Add a new Wine, and click Save. The id that has been assigned to the newly created wine appears in the form field. However the URL is still:
http://localhost/backbone-cellar/part2/ when it should really be: http://localhost/backbone-cellar/part2/#wines/[id].

You can easily fix that issue by using the router’s navigate function to change the URL. The second argument (false), indicates that we actually don’t want to “execute” that route: we just want to change the URL.

if (this.model.isNew()) {
	var self = this;
	app.wineList.create(this.model, {
		success: function() {
			app.navigate('wines/'+self.model.id, false);
		}
	});
} else {
	this.model.save();
}

Problem 3: Updating the URL while creating a new wine

The problem: Select a wine in the list. The URL looks like this: http://localhost/backbone-cellar/part2/#wines/[id]

Now, click the “Add Wine” button. You get an empty form to enter a new wine, but notice that the URL is still unchanged (http://localhost/backbone-cellar/part2/#wines/[id]). In other words, it doesn’t reflect the current state of the application.

In this case, we are going to add a new “route”:

	routes: {
		""			: "list",
		"wines/new"	: "newWine",
		"wines/:id"	: "wineDetails"
	},

The router’s newWine method is implemented as follows:

	newWine: function() {
		console.log('MyRouter newWine');
		if (app.wineView) app.wineView.close();
		app.wineView = new WineView({model: new Wine()});
		app.wineView.render();
	}

And we can change the HeaderView newWine() method as follows:

newWine: function(event) {
	app.navigate("wines/new", true);
	return false;
}

Putting it all together

You can run the application (Part 3) here. The create/update/delete features are disabled in this online version. Use the link at the bottom of this post to download a fully enabled version.

Here is the final version of the code:

window.Wine = Backbone.Model.extend({
	urlRoot: "api/wines",
	defaults: {
		"id": null,
	    "name":  "",
	    "grapes":  "",
	    "country":  "USA",
	    "region":  "California",
	    "year":  "",
	    "description":  "",
	    "picture":  ""
	  }
});

window.WineCollection = Backbone.Collection.extend({
	model: Wine,
	url: "api/wines"
});

window.WineListView = Backbone.View.extend({

	el: $('#wineList'),

    initialize: function() {
		this.model.bind("reset", this.render, this);
		this.model.bind("add", function(wine) {
			$('#wineList').append(new WineListItemView({model: wine}).render().el);
		});
    },

    render: function(eventName) {
		_.each(this.model.models, function(wine) {
            $(this.el).append(new WineListItemView({model: wine}).render().el);
		}, this);
		return this;
    }
});

window.WineListItemView = Backbone.View.extend({

	tagName: "li",

	template: _.template($('#wine-list-item').html()),

    initialize: function() {
		this.model.bind("change", this.render, this);
		this.model.bind("destroy", this.close, this);
    },

    render: function(eventName) {
		$(this.el).html(this.template(this.model.toJSON()));
		return this;
    },

	close: function() {
		$(this.el).unbind();
		$(this.el).remove();
	}
});

window.WineView = Backbone.View.extend({

    el: $('#mainArea'),

	template: _.template($('#wine-details').html()),

    initialize: function() {
		this.model.bind("change", this.render, this);
    },

    render: function(eventName) {
		$(this.el).html(this.template(this.model.toJSON()));
		return this;
    },

    events: {
        "change input": "change",
		"click .save": "saveWine",
		"click .delete": "deleteWine"
    },

    change: function(event) {
        var target = event.target;
        console.log('changing ' + target.id + ' from: ' + target.defaultValue + ' to: ' + target.value);
		// You could change your model on the spot, like this:
        // var change = {};
        // change[target.name] = target.value;
        // this.model.set(change);
    },

	saveWine: function() {
		this.model.set({
			name: $('#name').val(),
			grapes: $('#grapes').val(),
			country: $('#country').val(),
			region: $('#region').val(),
			year: $('#year').val(),
			description: $('#description').val()
		});
		if (this.model.isNew()) {
			var self = this;
			app.wineList.create(this.model, {
				success: function() {
					app.navigate('wines/'+self.model.id, false);
				}
			});
		} else {
			this.model.save();
		}

		return false;
	},

	deleteWine: function() {
		this.model.destroy({
			success: function() {
				alert('Wine deleted successfully');
				window.history.back();
			}
		});
		return false;
	},

	close: function() {
		$(this.el).unbind();
		$(this.el).empty();
	}
});

window.HeaderView = Backbone.View.extend({

	el: $('.header'),

	template: _.template($('#header').html()),

    initialize: function() {
		this.render();
    },

    render: function(eventName) {
		$(this.el).html(this.template());
		return this;
    },

    events: {
		"click .new": "newWine"
    },

	newWine: function(event) {
		app.navigate("wines/new", true);
		return false;
	}
});

var AppRouter = Backbone.Router.extend({

	routes: {
		""			: "list",
		"wines/new"	: "newWine",
		"wines/:id"	: "wineDetails"
	},

	list: function() {
    	this.wineList = new WineCollection();
		var self = this;
		this.wineList.fetch({
			success: function() {
		    	self.wineListView = new WineListView({model: self.wineList});
				self.wineListView.render();
				if (self.requestedId) self.wineDetails(self.requestedId);
			}
		});
  	},

	wineDetails: function(id) {
		if (this.wineList)
		{
			this.wine = this.wineList.get(id);
			if (this.wineView) this.wineView.close();
		    		this.wineView = new WineView({model: this.wine});
			this.wineView.render();
		} else {
			this.requestedId = id;
			this.list();
		}
  	},

	newWine: function() {
		if (app.wineView) app.wineView.close();
		app.wineView = new WineView({model: new Wine()});
		app.wineView.render();
	}

});

var app = new AppRouter();
Backbone.history.start();
var header = new HeaderView();

Download

The source code for this application is hosted on GitHub here (see part3). And here is a quick link to the download.

You will need the RESTful services to run this application. A PHP version (using the Slim framework) is available as part of the download.

UPDATE (1/11/2012): A version of this application with a Java back-end (using JAX-RS and Jersey) is also available on GitHub here. You can find more information on the Java version of this application here.

Backbone.js Wine Cellar Tutorial — Part 2: CRUD

Christophe — Wed, 07 Dec 2011 16:52:01 +0000

In Part 1 of this tutorial, we set up the basic infrastructure for the Wine Cellar application. The application so far is read-only: it allows you to retrieve a list of wines, and display the details of the wine you select.

In this second installment, we will add the ability to create, update, and delete (CRUD) wines.

RESTful Services

As mentioned in Part 1, Backbone.js provides a natural and elegant integration with RESTful services. If your back-end data is exposed through a pure RESTful API, retrieving (GET), creating (POST), updating (PUT), and deleting (DELETE) models is incredibly easy using the Backbone.js simple Model API.

This tutorial uses pure RESTful services. The services are implemented as follows:

HTTP Method	URL	Action
GET	/api/wines	Retrieve all wines
GET	/api/wines/10	Retrieve wine with id == 10
POST	/api/wines	Add a new wine
PUT	/api/wines/10	Update wine with id == 10
DELETE	/api/wines/10	Delete wine with id == 10

A PHP version of these services (using the Slim framework) is available as part of the download. A similar Java version of the API (using JAX-RS) is available as part of this post.

Using Backbone.js with non-RESTful Services

If your persistence layer is not available through RESTful services, you can override Backbone.sync. From the 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.”

Using non-RESTful services is not discussed in this tutorial. See the documentation for more information.

Part 2: Adding Create, Update, Delete

You can run the application (Part 2) here. The create/update/delete features are disabled in this online version. Use the link at the bottom of this post to download a fully enabled version.

Here is the code for the improved version of the applications. Key changes are discussed below.

window.Wine = Backbone.Model.extend({
	urlRoot: "api/wines",
	defaults: {
		"id": null,
	    "name":  "",
	    "grapes":  "",
	    "country":  "USA",
	    "region":  "California",
	    "year":  "",
	    "description":  "",
	    "picture":  ""
	  }
});

window.WineCollection = Backbone.Collection.extend({
	model: Wine,
	url: "api/wines"
});

window.WineListView = Backbone.View.extend({

	el: $('#wineList'),

    initialize: function() {
		this.model.bind("reset", this.render, this);
		this.model.bind("add", function(wine) {
			$('#wineList').append(new WineListItemView({model: wine}).render().el);
		});
    },

    render: function(eventName) {
		_.each(this.model.models, function(wine) {
            $(this.el).append(new WineListItemView({model: wine}).render().el);
		}, this);
		return this;
    }
});

window.WineListItemView = Backbone.View.extend({

	tagName: "li",

	template: _.template($('#wine-list-item').html()),

    initialize: function() {
		this.model.bind("change", this.render, this);
		this.model.bind("destroy", this.close, this);
    },

    render: function(eventName) {
		$(this.el).html(this.template(this.model.toJSON()));
		return this;
    },

	close: function() {
		$(this.el).unbind();
		$(this.el).remove();
	}
});

window.WineView = Backbone.View.extend({

    el: $('#mainArea'),

	template: _.template($('#wine-details').html()),

    initialize: function() {
		this.model.bind("change", this.render, this);
    },

    render: function(eventName) {
		$(this.el).html(this.template(this.model.toJSON()));
		return this;
    },

    events: {
        "change input": "change",
		"click .save": "saveWine",
		"click .delete": "deleteWine"
    },

    change: function(event) {
        var target = event.target;
        console.log('changing ' + target.id + ' from: ' + target.defaultValue + ' to: ' + target.value);
		// You could change your model on the spot, like this:
        // var change = {};
        // change[target.name] = target.value;
        // this.model.set(change);
    },

	saveWine: function() {
		this.model.set({
			name: $('#name').val(),
			grapes: $('#grapes').val(),
			country: $('#country').val(),
			region: $('#region').val(),
			year: $('#year').val(),
			description: $('#description').val()
		});
		if (this.model.isNew()) {
			app.wineList.create(this.model);
		} else {
			this.model.save();
		}
		return false;
	},

	deleteWine: function() {
		this.model.destroy({
			success: function() {
				alert('Wine deleted successfully');
				window.history.back();
			}
		});
		return false;
	},

	close: function() {
		$(this.el).unbind();
		$(this.el).empty();
	}
});

window.HeaderView = Backbone.View.extend({

	el: $('.header'),

	template: _.template($('#header').html()),

    initialize: function() {
		this.render();
    },

    render: function(eventName) {
		$(this.el).html(this.template());
		return this;
    },

    events: {
		"click .new": "newWine"
    },

    newWine: function(event) {
		if (app.wineView) app.wineView.close();
		app.wineView = new WineView({model: new Wine()});
		app.wineView.render();
		return false;
	}
});

var AppRouter = Backbone.Router.extend({

	routes: {
		""			: "list",
		"wines/:id"	: "wineDetails"
	},

	list: function() {
    	this.wineList = new WineCollection();
    	this.wineListView = new WineListView({model: this.wineList});
		this.wineList.fetch();
  	},

	wineDetails: function(id) {
		this.wine = this.wineList.get(id);
		if (app.wineView) app.wineView.close();
   		this.wineView = new WineView({model: this.wine});
		this.wineView.render();
  	}

});

var app = new AppRouter();
Backbone.history.start();
var header = new HeaderView();

Wine

Two attributes were added to the Wine Model:

urlRoot: RESTful service endpoint to retrieve or persist Model data. Note that this attribute is only needed when retrieving/persisting Models that are not part of a Collection. If the Model is part of a Collection, the url attribute defined in the Collection is enough for Backbone.js to know how to retrieve, update, or delete data using your RESTful API.
defaults: Default values used when a new instance of the model is created. This attribute is optional. However, it was required in this application for the wine-details template to render an ‘empty’ wine model object (which happens when adding a new wine).

WineListView

When a new wine is added, you want it to automatically appear in the list. To make that happen, you bind the View to the add event of the WineListView model (which is the collection of wines). When that event is fired, a new instance of WineListItemView is created and added to the list.

WineListItemView

When a wine is changed, you want the corresponding WineListItemView to re-render automatically to reflect the change. To make that happen, you bind the View to the change event of its model, and execute the render function when the event is fired.

Similarly, when a wine is deleted, you want the list item to be removed automatically. To make that happen, you bind the view to the destroy event of its model and execute our custom close function when the event is fired. To avoid memory leaks and events firing multiple times, it is important to unbind the event listeners before removing the list item from the DOM.

Note that in either case we don’t have the overhead of re-rendering the entire list: we only re-render or remove the list item affected by the change.

WineView

In the spirit of encapsulation, the event handlers for the Save and Delete buttons are defined inside WineView, as opposed to defining them as free-hanging code blocks outside the “class” definitions. You use the Backbone.js Events syntax which uses jQuery delegate mechanism behind the scenes.

There are always different approaches to update the model based on user input in a form:

“Real time” approach: you use the change handler to update the model as changes are made in the form. This is in essence bi-directional data binding: the model and the UI controls are always in sync. Using this approach, you can then choose between sending changes to the server in real time (implicit save), or wait until the user clicks a Save button (explicit save). The first option can be chatty and unpractical when there are cross-field validation rules. The second option may require you to undo model changes if the user navigates to another item without clicking Save.
“Delayed” approach: You wait until the user clicks Save to update the model based on the new values in UI controls, and then send the changes to the server.

This discussion is not specific to Backbone.js and is therefore beyond the scope of this post. For simplicity, I used the delayed approach here. However I still wired the change event, and use it to log changes to the console. I found this very useful when debugging the application, and particularly to make sure I had cleaned up my bindings (see close function): I you see the change event firing multiple times, you probably didn’t clean up as appropriate.

HeaderView

Backbone.js Views are typically used to render domain models (as done in WineListView, WineListItemView, and Wine View). But they can also be used to create composite UI components. For example, in this application, we define a Header View (a toolbar) that could be made of different components and that encapsulates its own logic.

Download

The source code for this application is hosted on GitHub here (see part2). And here is a quick link to the download.

You will need the RESTful services to run this application. A PHP version (using the Slim framework) is available as part of the download.

What’s Next?

The application so far doesn’t support deep-linking. For example, select a wine in the list, grab the URL in the address bar and paste it in another browser window: it doesn’t work. In Part 3, we will add complete support for deep linking.