search

mjumbewu / django-jstemplate

Embed Javascript templates (mustache.js and more) into Django templates with minimal fuss.
Other
41 stars 16 forks source link

readme

================= django-jstemplate

.. image:: https://travis-ci.org/mjumbewu/django-jstemplate.png :alt: Build Status :target: https://travis-ci.org/mjumbewu/django-jstemplate .. image:: https://coveralls.io/repos/mjumbewu/django-jstemplate/badge.png?branch=master :alt: Coverage Status :target: https://coveralls.io/r/mjumbewu/django-jstemplate .. image:: https://img.shields.io/pypi/v/django-jstemplate.svg :target: https://pypi.org/project/django-jstemplate/ .. image:: https://img.shields.io/pypi/dm/django-jstemplate.svg :target: https://pypi.org/project/django-jstemplate/

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

.. _mustache.js: http://mustache.github.com/ .. _dust.js: http://akdubya.github.com/dustjs/ .. _handlebars.js: http://handlebarsjs.com/ .. _ICanHaz.js: http://icanhazjs.com/ .. _django-icanhaz: http://github.com/carljm/django-icanhaz

Quick Usage

(Read the full docs on Read the Docs_)

.. _Read the Docs: http://django-jstemplate.readthedocs.org/en/latest/

Add "jstemplate" to your INSTALLED_APPS setting.

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

wget https://raw.github.com/janl/mustache.js/master/mustache.js
mv mustache.js app/static/libs/

app/jstemplates/main.mustache::

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

app/templates/main.html::

{% load jstemplate %}

<html>
<head>
  <script src="https://ajax.googleapis.com/ajax/libs/jquery/1.7.1/jquery.js"></script>
  <script src="https://github.com/mjumbewu/django-jstemplate/raw/master/{{ STATIC_URL }}libs/mustache.js"></script>
  <script src="https://github.com/mjumbewu/django-jstemplate/raw/master/{{ STATIC_URL }}libs/django.mustache.js"></script>
</head>

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

  {% mustachejs "main" %}

  <script>
    $(document).ready(function() {

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

      template = Mustache.template('main');
      $area.html(template.render());

    });
  </script>
</body>
</html>

Running tests

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

jstemplate/tests/project/manage.py test

Rationale

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.

Enjoy!

.. _one solution: https://gist.github.com/975505 .. _another: https://gist.github.com/629508