Skip to main content

Handlebars for Django

Project description

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).

How to install

  1. Install package from PyPi pip install django-handlebars. Or alternatively pull the repo and run python setup.py install

  2. Add django_handlebars to project’s settings.INSTALLED_APPS

  3. Optionaly add HANDLEBARS_* configuration parameters to the settings.py. See django_handlebars.appsettings for available options and explanations

  4. Run ./manage.py test django_handlebars to check configuration and requirments.

  5. That should be it. Application is not providing any models or URLs.

How to use

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.

Compiling in browser

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

Using pre-compiled templates

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.

Eliminating extra requests

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.

How to compile

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.

License

Copyright 2012 Sergii Iavorskyi, Licensed new-style BSD. Contains Handlebars.js copyright 2011 Yehuda Katz. See LICENSE file for more information.

Project details


Release history Release notifications | RSS feed

This version

0.1

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

django-handlebars-0.1.tar.gz (40.2 kB view details)

Uploaded Source

File details

Details for the file django-handlebars-0.1.tar.gz.

File metadata

File hashes

Hashes for django-handlebars-0.1.tar.gz
Algorithm Hash digest
SHA256 95f7709cc1096fbcfbf8fc48fdcf4e4c5f347573b9392e9ea1d61f4b398c78f9
MD5 4bd51a15fa3ebcd35c36b1854dfb1f9a
BLAKE2b-256 ea9a316d009cd569ba2b09d7ec5e1695484d3d07091f7c8fd49490466d75d14e

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page