Last modified: 29 November 2011
Handlebars is an extension to mustache templates, so you should read about that first. Next, read the handlebars.js homepage and also the readme on Github.
Example directory layout
There are two modes in which the templates can be served: debug and compiled.
The code needing to use the template need not worry about this though; it simply just uses the abstraction provided by templates.js and calls Template.get("package.name") to access the template as usual. Under the hood, templates.js will retrieve the contents of the appropriate inline <script> tag, and call Handlebars.compile on the content to convert it to a function at runtime.
Again, this is all abstracted by templates.js, so the code to user the templates will not change.
Since we don't need runtime compilation of the templates in production, we also serve a much smaller version of the handlebars library, called handlebars.vm.js.
In order to support rendering Handlebars templates server-side we use a tiny, badly supported library called PyBars (
To ensure that Handlebars templates are rendered identically on both client and server, all templates that are used on the server are rendered using test data in both PyBars and Node.js by a (large-size) unit test. The test data sits in companion files to the .handlebars files, so if your template is in
A simple way to get some test data for a template that is already rendering client-side is to temporarily uncomment the line in
The unit test will catch bugs in PyBars, helpers that are implemented in JS but have no Python equivalents, and a few cases where something magically works in JS even though it shouldn't. To make sure all the templates are working, run
Handlebars templates can be rendered server-side using the
Note that any helper functions used in the template must be defined in python on the server as well; see
Word of warning; the Handlebars parser on the server seems to be stricter than the client-side parser, and will simply silently stop rendering a template if certain extra spacing is including inside tags, as in:
See the Deploy page.