Skip to main content

A Django template tag for embedding Mustache.js templates -- or other JavaScript templates -- safely.

Project description

Build Status Coverage Status

A templatetag framework for easier integration of mustache.js, dust.js, handlebars.js, or other JavaScript templates with Django templates. Also will wrap your templates in elements expected for libraries such as ICanHaz.js. Django-jstemplates is extensible, so if your favorite template library is not included, it’s easy to add. Inspired by django-icanhaz.

Quick Usage

(Read the full docs on Read the Docs)

Add "jstemplate" to your INSTALLED_APPS setting.

Download the templating library of your choice (I like to go straight mustache.js):

mv mustache.js app/static/libs/


  <p>This is {{ name }}'s template</p>


{% load jstemplate %}

  <script src=""></script>
  <script src="{{ STATIC_URL }}libs/mustache.js"></script>
  <script src="{{ STATIC_URL }}libs/django.mustache.js"></script>

  <div id="dynamic-area"></div>

  {% mustachejs "main" %}

    $(document).ready(function() {

      var $area = $('#dynamic-area')
        , template;

      template = Mustache.template('main');


Running tests

To run the tests (for development), install mock and six and run:

jstemplate/tests/project/ test


The collision between Django templates’ use of {{ and }} as template variable markers and mustache.js’ use of same has spawned a variety of solutions. One solution simply replaces [[ and ]] with {{ and }} inside an mustachejs template tag; another makes a valiant attempt to reconstruct verbatim text within a chunk of a Django template after it has already been mangled by the Django template tokenizer.

I prefer to keep my JavaScript templates in separate files in a dedicated directory anyway, to avoid confusion between server-side and client-side templating. So this solution is essentially just an “include” tag that avoids parsing the included file as a Django template.




Fix pacthing of the makemessages command to work for Django later than 1.11.


Thank you to @karlrl for the following changes:

  • Support Python 3.7-3.10

  • Support Django 2.2-4.1

  • Drop support for Python<3.7 and Django<3.2


  • In order to support the latest versions of Django, removed dependence on the FILE_CHARSET setting. This means that the templates will always be read as UTF-8.


  • Bug fix: Update to work with Django 1.9


  • Bug fix: Fail silently when using an invalid regex to match templates.


  • Bug fix: Fix the case on innerHTML (was innerHtml)


  • Use document.getElementById and innerHtml instead of depending on jQuery to get the text of handlebars templates.

  • Switch the order of precompiling and registering partials in handlebars tag, so that partials can used compiled template.


  • Fix compatibility with Python 3.2. Explicity unicode literals (i.e., u’…’) are not supported in Python 3.2 and cause a syntax error. Support was revived in Python 3.3. Python 2.6 and 2.7 allow using unicode string literals by default with from __future__ import unicode_literals, so we use that here.


  • Sort translatable strings so that results are consistent across Python versions.


  • All template renderers handle unicode characters.


  • Bug fix: Closure that was registering Handlbars partials was not wrapped in parentheses.


  • Add a short translation form:

    {{ _ 'this is translatable' }}


  • Allow optional precompiling and and registering of partials for the Handlebars.js tag. For example:

    {% handlebarsjs '(.*)' precompile register_partials }

    This will add a templates object to Handlebars, and register all templates for use as partials.


  • Add Handlebars.js support


  • Fix setup script requirements


  • Python 3 support!


  • Move the static/mustache/js/ folder to static/libs/


  • Update MANIFEST file to use “jstemplate” folder instead of “mustachejs”


  • Simplify the template tag methods, and get rid of unused imports in the template tag modules

  • Update project references in the docs


  • Rename project to “django-jstemplate” (from “django-mustachejs”)

  • Rename the “mustacheraw” template tag to “rawjstemplate”

  • Rename the “mustacheich” template tag to “icanhazjs”


  • Fix incorrect identifier name in makemessages command


  • Fix the FilesystemRegexFinder to match exactly the extensions specified in the configuration, and no more


  • Fix makemessages to work with recent code updates


  • Have the regex finder respect the MUSTACHEJS_EXTS setting

  • Update normal file finders to use glob patterns


  • Fix i18n preprocessor for python 2.6 compatibility


  • Correctly escaped translated strings.


  • Changed search pattern to be non-greedy.


  • Handle translation strings with new lines.


  • Pulled in commit from django-icanhaz to load templates using regular expressions.

  • Added preprocessing framework, and a preprocessor for i18n.

  • Hijack the makemessages command to find js template messages as well.


  • Add dustjs tag to insert a script block to create a compiled dustjs template. Thanks to Gehan Gonsalkorale.


  • Add mustacheraw tag to insert just the raw text of a mustacehe template. Thanks to Greg Hinch.

  • Add mustacheich tag to insert a mustache script block as icanhaz expects.

0.4.1 (2012.01.09)

  • Fixed template reading to explicitly decode template file contents using Django’s FILE_CHARSET setting. Thanks Eduard Iskandarov.

  • Fixed template-finding failure with non-normalized directories in MUSTACHEJS_DIRS. Thanks Eduard Iskandarov for report and patch.


  • Add the MUSTACHEJS_EXTS configuration variable for specifying the extensions allowed for template files located by the FilesystemFinder (and, by extension, the AppFinder).


  • Add a package_data value to the setup call


  • Add the file itself as an entry in


  • Change the name from django-icanhaz to django-mustachejs.

  • Remove dependency on ICanHaz.js. I like the library, but the maintainers were not responsive enough for now. Use Mustache.js straight, with a little bit of minimal sugar. Templates are rendered to straight Javascript.

0.2.0 (2011.06.26)

  • Made template-finding more flexible: ICANHAZ_DIR is now ICANHAZ_DIRS (a list); added ICANHAZ_FINDERS, ICANHAZ_APP_DIRNAMES, and finding of templates in installed apps.

0.1.0 (2011.06.22)

  • Initial release.


Project details

Download files

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

Source Distribution

django-jstemplate-2.0.1.tar.gz (17.7 kB view hashes)

Uploaded Source

Supported by

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