Client-side HTML Template Engine
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


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.

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

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() {

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 = "<p>Hello $(.name)!</p>";
    var user = { "name":"Leonardo da Vinci" };
    $('.body').html(SNBinder.bind(template, user));

will replace the contents of the body tag with "<p>Hello Leonardo da Vinci!</p>". 

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

    var template = "<p>Hello $(.name)!</p>";
    var apply_template = SNBinder.compile(template);
    var user1 = { "name":"Leonardo da Vinci" };
    var user2 = { "name":"Michelangelo di Lodovico Buonarroti Simoni" };

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

    var template = "<li>Hello $(.name)!</li>";
    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"

    <p>Hello $(.name)!</p>

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);, 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 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.