Handlebars

Overview

The Handlebars templating library is based on Mustache and provides some really useful extra features for CouchApp developers. In fact, Mustache templates are compatible with Handlebars, so you can take existing Mustache templates, and start taking advantage of the extra features straight away.

kanso.json

The handlebars package provides the handlebars module for rendering templates and some optional build-steps for loading templates from the filesystem, pre-compiling them, and adding them to your app.

The handlebars build-steps use the following configuration options:

• templates - Finds all templates beneath this path and adds them to your app. This is treated as the template root, so setting it to templates would mean templates/base.html will be available in your app as just base.html
• all_partials - This registers every loaded template as a handlebars partial. This is not necessary if you're using the handlebars-helpers package

{   
    ...
    "handlebars": {
        "all_partials": false,
        "templates": "templates"
    },
    "dependencies": {
        ...
        "handlebars": null
    }
}

After kanso.json has been updated, run kanso install (from a terminal) at the root of your project to install the new dependencies.

Usage

var handlebars = require('handlebars');

// handlebars.templates contains any templates loaded from the template directory in your
// kanso.json, if you're not using the build-steps then this will not exist.
var html = handlebars.templates['base.html'](context, options);

// if you haven't loaded any templates, you can compile your own
var heading = handlebars.compile('<h1>{{title}}</h1>');
var h1 = heading({title: 'Hello, world!'});

handlebars-helpers

The handlebars-helpers package provides some useful extra helper functions inside your handlebars templates.

include

Includes another handlebars template loaded using the optional build-steps described above. This is similar to using a partial, but it supports nested directories and file extensions:

{{{include "path/to/template.html"}}}

Notice, I've used triple-mustaches to make sure the result of rendering that template isn't escaped. The current (not the root) context is used for rendering the included template.

uc

Runs a string through encodeURIComponent, returning the result. This is very useful when constructing URLs.

{{uc page_id}}

ifequal

Block-helper that executes the inner-block if the two arguments test as strict equal (===). This also supports else blocks.

<ul>
  {{#ifequal current_page "home"}}
    <li><strong>home</strong></li>
  {{else}}
    <li><a href="/home">home</a></li>
  {{/ifequal}}
</ul>

duality-handlebars

If you are using the Duality framework, the duality-handlebars package provides an adapter to easily use handlebars with duality list, show and update functions.

After including the duality-handlebars package, the handlebars templates are exposed through the duality/templates module API:

var templates = require('duality/templates');

exports.example = function (doc, req) {
    return templates.render('base.html', req, context);
};

The duality-handlebars package adds a baseURL template helper for getting the root URL of your app, as well as automatically adding userCtx and any flashmessages to the context object.

In Duality, you can return the context object for your base template from a list, show or update function and it will be automatically rendered. If you're using duality-handlebars, its advisable to explicitly set your Duality base template in your kanso.json:

{
    ...
    "duality": {
        "base_template": "base.html"
    },
    "handlebars": {
        "templates": "templates"
    },
    "dependencies": {
        "handlebars": null,
        "handlebars-helpers": null,
        "duality-handlebars": null
    }
}

possible.test and RegExp errors

A number of CouchDB install seem to use a version or configuration of SpiderMonkey with broken regular expressions. Unfortunately, handlebars templates have been known to break due to this bug. Obviously, the best course of action is fix your CouchDB install (try this one), but it also seems Dust templates don't suffer from this problem.