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](http://kan.so/packages/details/handlebars) 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 ```javascript { ... "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 ```javascript 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](http://kan.so/packages/details/handlebars-helpers) 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: ```javascript {{{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. ```xml <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](http://kan.so/packages/details/duality-handlebars) 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: ```javascript 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: ```javascript { ... "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](https://github.com/iriscouch/build-couchdb)), but it also seems [[Dust]] templates don't suffer from this problem.