A Django template tag for embedding Mustache.js templates -- or other JavaScript templates -- safely.
Project description
=================
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://pypip.in/v/django-jstemplate/badge.png
:target: https://crate.io/packages/django-jstemplate/
.. image:: https://pypip.in/d/django-jstemplate/badge.png
:target: https://crate.io/packages/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="{{ STATIC_URL }}libs/mustache.js"></script>
<script src="{{ 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
CHANGES
=======
1.3.8
-----
- Bug fix: Update to work with Django 1.9
1.3.7
-----
- Bug fix: Fail silently when using an invalid regex to match templates.
1.3.6
-----
- Bug fix: Fix the case on ``innerHTML`` (was ``innerHtml``)
1.3.5
-----
- 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.
1.3.4
-----
- 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.
1.3.3
-----
- Sort translatable strings so that results are consistent across Python
versions.
1.3.2
-----
- All template renderers handle unicode characters.
1.3.1
-----
- Bug fix: Closure that was registering Handlbars partials was not wrapped in
parentheses.
1.3.0
-----
- Add a short translation form::
{{ _ 'this is translatable' }}
1.2.1
-----
- 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.
1.2.0
-----
- Add Handlebars.js support
1.1.1
-----
- Fix setup script requirements
1.1.0
-----
- Python 3 support!
1.0.3
-----
- Move the static/mustache/js/ folder to static/libs/
1.0.2
-----
- Update MANIFEST file to use "jstemplate" folder instead of "mustachejs"
1.0.1
-----
- Simplify the template tag methods, and get rid of unused imports in the
template tag modules
- Update project references in the docs
1.0.0
-----
- Rename project to "django-jstemplate" (from "django-mustachejs")
- Rename the "mustacheraw" template tag to "rawjstemplate"
- Rename the "mustacheich" template tag to "icanhazjs"
0.8.3
-----
- Fix incorrect identifier name in makemessages command
0.8.2
-----
- Fix the FilesystemRegexFinder to match exactly the extensions specified in
the configuration, and no more
0.8.1
-----
- Fix makemessages to work with recent code updates
0.8.0
-----
- Have the regex finder respect the MUSTACHEJS_EXTS setting
- Update normal file finders to use glob patterns
0.7.4
-----
- Fix i18n preprocessor for python 2.6 compatibility
0.7.3
-----
- Correctly escaped translated strings.
0.7.2
-----
- Changed search pattern to be non-greedy.
0.7.1
-----
- Handle translation strings with new lines.
0.7.0
-----
- 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.
0.6.0
-----
- Add ``dustjs`` tag to insert a script block to create a compiled dustjs
template. Thanks to `Gehan Gonsalkorale <https://github.com/gehan>`_.
0.5.0
-----
- 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.
0.4.0
-----
- Add the MUSTACHEJS_EXTS configuration variable for specifying the extensions
allowed for template files located by the FilesystemFinder (and, by extension,
the AppFinder).
0.3.3
-----
- Add a package_data value to the setup call
0.3.2
-----
- Add the MANIFEST.in file itself as an entry in MANIFEST.in.
0.3.0
-----
- 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.
TODO
====
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://pypip.in/v/django-jstemplate/badge.png
:target: https://crate.io/packages/django-jstemplate/
.. image:: https://pypip.in/d/django-jstemplate/badge.png
:target: https://crate.io/packages/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="{{ STATIC_URL }}libs/mustache.js"></script>
<script src="{{ 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
CHANGES
=======
1.3.8
-----
- Bug fix: Update to work with Django 1.9
1.3.7
-----
- Bug fix: Fail silently when using an invalid regex to match templates.
1.3.6
-----
- Bug fix: Fix the case on ``innerHTML`` (was ``innerHtml``)
1.3.5
-----
- 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.
1.3.4
-----
- 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.
1.3.3
-----
- Sort translatable strings so that results are consistent across Python
versions.
1.3.2
-----
- All template renderers handle unicode characters.
1.3.1
-----
- Bug fix: Closure that was registering Handlbars partials was not wrapped in
parentheses.
1.3.0
-----
- Add a short translation form::
{{ _ 'this is translatable' }}
1.2.1
-----
- 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.
1.2.0
-----
- Add Handlebars.js support
1.1.1
-----
- Fix setup script requirements
1.1.0
-----
- Python 3 support!
1.0.3
-----
- Move the static/mustache/js/ folder to static/libs/
1.0.2
-----
- Update MANIFEST file to use "jstemplate" folder instead of "mustachejs"
1.0.1
-----
- Simplify the template tag methods, and get rid of unused imports in the
template tag modules
- Update project references in the docs
1.0.0
-----
- Rename project to "django-jstemplate" (from "django-mustachejs")
- Rename the "mustacheraw" template tag to "rawjstemplate"
- Rename the "mustacheich" template tag to "icanhazjs"
0.8.3
-----
- Fix incorrect identifier name in makemessages command
0.8.2
-----
- Fix the FilesystemRegexFinder to match exactly the extensions specified in
the configuration, and no more
0.8.1
-----
- Fix makemessages to work with recent code updates
0.8.0
-----
- Have the regex finder respect the MUSTACHEJS_EXTS setting
- Update normal file finders to use glob patterns
0.7.4
-----
- Fix i18n preprocessor for python 2.6 compatibility
0.7.3
-----
- Correctly escaped translated strings.
0.7.2
-----
- Changed search pattern to be non-greedy.
0.7.1
-----
- Handle translation strings with new lines.
0.7.0
-----
- 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.
0.6.0
-----
- Add ``dustjs`` tag to insert a script block to create a compiled dustjs
template. Thanks to `Gehan Gonsalkorale <https://github.com/gehan>`_.
0.5.0
-----
- 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.
0.4.0
-----
- Add the MUSTACHEJS_EXTS configuration variable for specifying the extensions
allowed for template files located by the FilesystemFinder (and, by extension,
the AppFinder).
0.3.3
-----
- Add a package_data value to the setup call
0.3.2
-----
- Add the MANIFEST.in file itself as an entry in MANIFEST.in.
0.3.0
-----
- 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.
TODO
====
Release history Release notifications | RSS feed
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-1.3.8.tar.gz
(21.0 kB
view hashes)
