django-handlebars integrates Handlebars JavaScript templating engine with Django. It provides Python and JavaScript helpers for wrapping templates inclusion and loading routines. Optionaly django-handlebars provides manage.py commands facilitating compilation (requires python-spidermonkey) and live templates assets synchronization as you developing (requires pyinotify).
- Install package from PyPi
pip install django-handlebars. Or alternatively pull the repo and runpython setup.py install - Add
django_handlebarsto project'ssettings.INSTALLED_APPS - Optionaly add
HANDLEBARS_*configuration parameters to thesettings.py. See django_handlebars.appsettings for available options and explanations - Run
./manage.py test django_handlebarsto check configuration and requirments. - That should be it. Application is not providing any models or URLs.
django-handlebars can work in two modes: compiling templates in browser and rendering templates pre-compiled on server side. In both scenarios templates might be loaded dynamically with AJAX request or included on page to prevent extra HTTP requests.
First you have to drop in Handlebars scripts on page:
{% load handlebars_tags %}
<html>
<head>
{% handlebars_scripts %}
</head>
<body></body>
</html>
Which will add handlebars_config variable storing configuration, script tags for handlebars.js (or handlebars.runtime.js if settings.HANDLEBARS_COMPILED is True) and handlebars.django.js. Django-handlebars provides template loading client (see handlebars.django.js) by extending Handlebars object with tpl() method.
This mode is simpler and doesn't require optional dependencies to be satisfied. But it adds a little overhead. In this case Handlebars will parse template every other page load and parser script has to be loaded in addition to renderer.
Assuming you have configured application and your Handlebars *.html templates are accessiable from static URL, your typical usage pattern will look like this:
var data = {title: "The title", body: "whatever"}
Handlebars.tpl("your/template/spec", {
success: function(renderer){
console.log("Rendered template:", renderer(data));
},
error: function(xhr, err){
console.warn("Ooops, can't load template", err);
}
});
Notice that template path doesn't include dir URL and extension. Starting slash is tolerated. Handlebars.tpl is NOT returning template, having success callback is the only way to get it.
By default client attempts to use jQuery if it's available, otherwise it will fall back to it's own simple crossbrowser XHR implementation. In case jQuery is available Handlebars.tpl() call would return jQuery.Deferred object, so chaining and other benefits may be used:
var df = Handlebars.tpl("your/template/spec");
df.done(function(renderer){
console.log("Rendered template:", renderer(data));
}).fail(function(xhr, err){
console.warn("Ooops, can't load template", err);
});
Loader appends .html extension and pulls file from settings.HANDLEBARS_TPL_URL
In this mode your JavaScript code stays same, but client will attempt to pull .js file from settings.HANDLEBARS_TPL_URL. Pre-compiled file contains JS function generated by Handlebars.precompile(str_template). You can run this command right in a browser console to see how it looks. Django-handlebars provides manage.py commands to build those files in a batch.
In both cases described above HTTP request will be made, which lowers performance. To avoid that include you templates on page::
{% handlebars_template "your/template/spec" %}
This will cache template by calling Handlebars.tpl("your/template/spec", tpl). Described technique works for both regular and pre-compiled modes.
Run ./manage.py compilehandlebars --help:
--clean Remove all previously compiled templates --watch Watch for changes within appsettings.TPL_DIR and compile --raw Do not format output --quiet Run with no output
Django-hadlebars compiles templates by running Handlebars script using SpiderMonkey and requires python-spidermonkey package to be installed.
So far --watch option is available on Linux platform only since it's using pyinotify. Support for other platforms might be added in future.
If either of these two is not installed compilehandlebars will exit with appropriate error message.
On compilehandlebars start all template files with mtime newer than compiled file mtime will be re-compiled. If you run command without --watch compiler exits once all files compiled, otherwise it will hang until you press Ctl-C.
Copyright 2012 Sergii Iavorskyi, Licensed new-style BSD. Contains Handlebars.js copyright 2011 Yehuda Katz. See LICENSE file for more information.