Bitbucket is a code hosting site with unlimited public and private repositories. We're also free for small teams!

Close

django-handlebars

django-handlebars is a helper to use Handlebars client-side templates with Django.

Installation

pip install hg+https://bitbucket.org/chrisv/django-handlebars/

Usage

  1. add django_handlebars to INSTALLED_APPS
  2. put your handlebars templates in a folder named hbtemplates inside your app directory. Example:
myproject/
   myapp/
       hbtemplates/
           myapp/
               forms/
                   form1.html
                   form2.html
               texts/
                   text1.html
                   text2.html
           ...
  1. add {% load handlebars %} at the top of the template, and include the loader tag {% handlebars myapp %} into <head>. Note: you also need to include handlebars.js, of course

  2. use client-side templating like this:

    $('#result').html(Handlebars.templates['myapp.texts.text1.html']({context: 'context'});
    

How it works

django-handlebars takes everything under appdirectory/hbtemplates puts it into <script type="text/x-handlebars-template"> tags and adds these to the page. Also, a little glue script is added to compile the templates on page load and make them available under Handlebars.templates[...].

Precompiling templates

Since compiling templates on the fly inflates the DOM, works not well with browser caching and leads to increased load time, django-handlebars can also use Handlebars' precompilation feature.

To use it, install node.js and the Handlebars precompiler as described in Precompilation. Then add the path to the handlebars command to settings.py:

HANDLEBARS_COMPILER="/path/to/handlebars"

Now, when django-handlebars encounters a {% handlebars %} tag, it will compile the templates to a single javascript file on the fly, and link it in the <head>. If the compiled file is already newer than the newest template, compilation will be skipped.

Additional compilation flags like -k, -o or -m can be used by adding them to settings.HANDLEBARS_COMPILATION_FLAGS (if present, this must be in form of an array, e.g. settings.HANDLEBARS_COMPILATION_FLAGS=['-m', '-k each', '-k if']).

django-handlebars stores precompiled template in its own static directory, so it will work out of the box when the built-in development server is used.

Precompiled templates in production

In production, precompiled templates can be served just like any other static file, and if you run the development server once, manage.py collectstatic will pick up the generated templates automatically. However, to avoid unneccessary runtime checks and compiler invocation, set settings.HANDLEBARS_PRODUCTION. If set to True (default is False) it will override any other setting and {% handlebars %} will directly add the <script> headers for precompiled templates without further checking or compilation.

License

django-handlebars is licensed under BSD License, which basically means you can use it wherever and however you see fit.

Reporting bugs

Use the bugtracker at https://bitbucket.org/chrisv/django-handlebars/

Recent activity

Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.