snbinder

SNBinder is a client-side template engine implemented in JavaScript. Just like server-side template engines,
it binds a view (HTML template) to a data (JavaScript object) and generate an HTML text.

0. Design Principle and Sample Application

I developed SNBinder with a belief that the client-side data-binding gives a great flexibility
to developers who want to offer a "desktop-application-like" user experience. Read the following
article if you are interested in the architecture behind this effort.

http://www.facebook.com/note.php?note_id=179569622077334

Fruence (a groupware application for Facebook users) is the showcase application that demonstrates
the user experience enabled by this architecture.

http://www.fruence.com

1. Initialization

SNBinder requires JQuery. JQuery must be loaded before SNBinder.

After loading both JQuery and SNBinder, the application should initialize SNBinder by calling it's init method like this:

$(document).ready(function() {
SNBinder.init({});
}

The init method takes an optional parameter, which is described in the "Advanced Initialization" section below.

2. Binding

To bind an HTML template to a JavaScript object, you need to call SNBinder.bind() method. For example,

var template = "

Hello $(.name)!

";
var user = { "name":"Leonardo da Vinci" };
$('.body').html(SNBinder.bind(template, user));

will replace the contents of the body tag with "

Hello Leonardo da Vinci!

".

If you want to apply the same template to multiple objects, it's more efficient to use a complied form.

var template = "

Hello $(.name)!

";
var apply_template = SNBinder.compile(template);
var user1 = { "name":"Leonardo da Vinci" };
var user2 = { "name":"Michelangelo di Lodovico Buonarroti Simoni" };
$('.div#user1').html(apply_template(user1));
$('.div#user2').html(apply_template(user2));

It is also possible to bind a template to an array of objects:

var template = "

Hello $(.name)!

";
var users = [
{ "name":"Leonardo da Vinci" },
{ "name":"Michelangelo di Lodovico Buonarroti Simoni" },
{ "name":"LDonato di Niccolò di Betto Bard" }
];
$('.ul').html(SNBinder.bind_rowset(template, users);

Following patterns in the template will be replaced.

$(.foo) will be replaced by the value of property "foo" (escaped)
$(_foo) will be replaced by the value of property "foo" (non-escaped)
$(+foo) will be replaced by the value of property "foo" (urlencode)
$(index) will be replaced by the index (in case or bind_rowset)

3. Loading templates

Although it is possible to hard-code HTML templates in JavaScript code like samples above, it is not a good
practice to mix View and Controller (notice that JavaScript is activing as a Controller). SNBinder offers
two helper functions that allows developers to load multiple templates in a single HTTP GET.

SNBinder.get_sections(url, callback)
SNBinder.get_named_sections(url, callback)

The load_sections method loads a template bundle (an array of templates joined with "{%}") from the specified URL,
and calls the callback function with an array of templates.

The load_sections method loads a named template bundle (set of named templates, where each name is specified with "{%}...{%}"),
and calls the callback function with a dictionary of templates. For example, assume the named template bundle has follwing
contents (a single template named "main") and accessible at "/static/template.htm"

{%}main{%}

Hello $(.name)!

The following code will load this template bundle, and performs the same view-data binding described in section 2.

SNBinder.get_named_sections("/static/templates.htm", null, function(templates) {
var user = { "name":"Leonardo da Vinci" };
$('.body').html(SNBinder.bind(templates("main", user));
});

4. Loading data via JSON over HTTP

SNBinder has a set of helper methods, which makes it easy to fetch data (Json objects) over HTTP.

SNBinder.get(url, params, isJson, callback, options);
SNBinder.post(url, params, isJson, callback);

url: url to get/post the data from/data
params: url parameters (JavaScript object)
isJson: true if the server returns a JSON data
callback: callback function that processes the data (if isJson is false) or json and data (if isJson is true)
options: optional parameters to control the cache (default is {bypass_cache:false, cache_result:true} )

For example, if "/user/info" returns the JSON object represents the user (such as {"name":"Leonardo da Vinci"}),
the example in previous section will become something like this:

SNBinder.get_named_sections("/static/templates.htm", null, function(templates) {
SNBinder.get("/user/info", null, true, function(user) {
$('.body').html(SNBinder.bind(templates("main", user));
});
});

5. Cache control

SNBinder has an in-memory cache for data and templates fetched via get() method, and following methods allows
the application to access and control the cache.

flush_all(): flush all the cached data
flush(url, params): flush associated with url + url parameters

6. Advanced Initialization

If the application calls SNBinder.get or SNBinder.post with isJson=true and the server returns an JSON object
that has the property "login_required" with true in it, SNBinder calls the "login" function specified in
the optional parameter to the SNBinder.init() method.