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.
Permalink
Failed to load latest commit information.
README
snbinder-0.5.2.js
snbinder-0.5.3.js

README

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 = "<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" };
    $('.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 = "<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"

    {%}main{%}
    <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);
    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.